API

`findtime.io`
Time Intelligence for Apps and Agents

findtime.io now has a production time intelligence surface for apps and agents. The goal is not thin parity with legacy time APIs. The goal is better ambiguity handling, better DST truth, and better cross-timezone workflow intelligence.

You can use this surface from your app backend, internal tools, or MCP clients. Start with /time/snapshot first, then drop down to narrower endpoints only when you want tighter control.

Built on a global location dataset with 62,179 cities, plus country and timezone coverage tuned for accurate resolution, DST handling, and cross-timezone workflows.

Ambiguity-safe

CST, IST, Victoria, San Jose, and other messy inputs return candidates instead of false confidence.

DST truth

Current state, last transition, next transition, and current abbreviation are packaged directly.

Workflow layer

Overlap and meeting-finding move beyond commodity “what time is it?” answers.

Agent-ready

The same production API powers MCP so agents and apps stay on one truth surface.

API

API Quickstart

If you only try one endpoint first, make it /time/snapshot. It is the cleanest one-call entry point into the platform.

What to expect:

Every API request uses Authorization: Bearer YOUR_SECRET_KEY.
All current endpoints are GET requests.
Use pipe-delimited values for multi-location inputs such as London|Tokyo|New York.
If a query is ambiguous, the API returns candidates instead of guessing.
Batch time snapshots can return partial success with per-location status, so one ambiguous place does not fail the whole request.

request

curl --request GET \
  --url "https://time-api.findtime.io/time/snapshot?query=Tokyo&countryCode=JP&includeTransitions=true" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

sample response

{
  "shape": "time_snapshot.v2",
  "resolved": false,
  "ambiguous": true,
  "partial": true,
  "resolvedCount": 1,
  "ambiguousCount": 1,
  "notFoundCount": 0,
  "locations": [
    {
      "side": 0,
      "status": "resolved",
      "query": "Iceland",
      "resolutionReason": "country=IS",
      "location": {
        "name": "Reykjavík",
        "countryCode": "IS",
        "countryName": "Iceland",
        "timezoneIana": "Atlantic/Reykjavik"
      },
      "timezone": {
        "iana": "Atlantic/Reykjavik",
        "abbreviation": "GMT",
        "utcOffset": "UTC+0"
      }
    },
    {
      "side": 1,
      "status": "ambiguous",
      "query": "Paris",
      "primaryCandidate": {
        "countryCode": "FR",
        "countryName": "France",
        "timezoneIana": "Europe/Paris",
        "suggestedQuery": "Paris, France"
      }
    }
  ]
}

API

Why `findtime.io` API is different

We designed the API around the jobs developers and agents actually need, not around a giant list of thin wrappers. Start with one strong bundled endpoint like /time/snapshot, drop down to narrower calls only when you need more control, and never rely on silent guessing for ambiguous input.

The same production truth surface powers the API, the MCP server, and findtime.io itself. That keeps timezone handling, DST transitions, location resolution, overlap windows, and meeting suggestions aligned across the website, integrations, and agents.

API

Response contract and disambiguation

The API is designed to surface ambiguity instead of hiding it. When a query is underspecified, the contract is to return enough structure for the caller to retry deterministically rather than silently guessing.

How to read the contract:

resolved: true means the request mapped to a canonical location or timezone and the payload can be used directly.
ambiguous: true means the input matched multiple valid places or abbreviations. Inspect the candidates and retry with a city, country hint, or IANA timezone.
/time/snapshot can return partial batch success. Inspect each location row’s status instead of assuming the entire batch resolved or failed together.
notFound or HTTP 404 means the API could not resolve the input with enough confidence. Start with /locations/search if you need a deterministic retry path.
countryCode on /locations/search is a ranking and disambiguation hint. It can move a country to the top of the results, but it does not guarantee that every returned row belongs to that country.
Ambiguous candidates now include both suggestedQuery and suggestedId so apps and agents can retry with either a human-readable city-country form like Paris, France or a stable findtime: id.
Abbreviations such as IST, CST, and BST are often ambiguous. Pair them with a country or region, or resolve them through /locations/search first.
Country-name queries for /time/current and /time/snapshot are supported directly. Single-zone countries resolve to a canonical city, while multi-zone countries return explicit ambiguity with candidate timezones.

API

API Keys

Create and manage developer keys from a Google-authenticated findtime.io account. This keeps API access tied to a real developer identity and gives you one place to issue, revoke, and rotate credentials.

How it works:

Sign in with Google from the docs top bar.
Create a key from the docs-styled API Keys console.
Send it using Authorization: Bearer YOUR_SECRET_KEY on every API request.

Open API Keys

request

curl --request GET \
  --url "https://time-api.findtime.io/time/current?query=Tokyo" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

Flagship endpoint

time_snapshot

GET/time/snapshot

Start here when you want one-call time intelligence. It resolves the place, packages timezone and DST truth, includes geo, and can optionally include transition detail so callers make fewer follow-up requests.

Use this as the default entry point for apps and agents. Multi-location requests can return partial success with per-location status so one ambiguous place does not fail the whole batch.

Parameters

query or locationsstring

Single location query or pipe-delimited list of locations to resolve.

countryCode or countryCodesstring

Optional ISO country hint to improve deterministic resolution. Hints improve ranking and disambiguation but do not turn search-like inputs into strict country filters.

includeTransitionsboolean

Adds last and next timezone transition detail when you need full DST context.

request

curl --request GET \
  --url "https://time-api.findtime.io/time/snapshot?locations=Tokyo|New%20York&countryCodes=JP|US&includeTransitions=true" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "shape": "time_snapshot.v2",
  "resolved": false,
  "ambiguous": true,
  "partial": true,
  "resolvedCount": 1,
  "ambiguousCount": 1,
  "notFoundCount": 0,
  "locations": [
    {
      "side": 0,
      "status": "resolved",
      "query": "Iceland",
      "resolutionReason": "country=IS",
      "location": {
        "name": "Reykjavík",
        "countryCode": "IS",
        "countryName": "Iceland",
        "timezoneIana": "Atlantic/Reykjavik"
      },
      "timezone": {
        "iana": "Atlantic/Reykjavik",
        "abbreviation": "GMT",
        "utcOffset": "UTC+0"
      }
    },
    {
      "side": 1,
      "status": "ambiguous",
      "query": "Paris",
      "primaryCandidate": {
        "countryCode": "FR",
        "countryName": "France",
        "timezoneIana": "Europe/Paris",
        "suggestedQuery": "Paris, France"
      }
    }
  ]
}

Core endpoint

get_current_time

GET/time/current

Current local time for a single city or timezone with the same packaged location, timezone, currentTime, dst, and geo model used across the API.

Parameters

city or querystring

A city name, timezone abbreviation, IANA zone, or other free-form location query. Exact country-name queries resolve directly when there is one canonical zone, and return explicit ambiguity when a country spans multiple zones.

countryCodestring

Optional ISO country hint for duplicate city names like Victoria or San Jose.

request

curl --request GET \
  --url "https://time-api.findtime.io/time/current?city=Tokyo&countryCode=JP" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "shape": "current_time.v2",
  "resolved": true,
  "location": {
    "name": "Tokyo",
    "countryName": "Japan",
    "timezoneIana": "Asia/Tokyo"
  },
  "timezone": {
    "abbreviation": "JST",
    "longName": "Japan Standard Time",
    "utcOffset": "UTC+9"
  },
  "currentTime": {
    "time24h": "22:31",
    "time12h": "10:31 PM",
    "weekday": "Tuesday"
  },
  "dst": {
    "observesDST": false,
    "isDSTActiveNow": false
  }
}

Core endpoint

get_dst_schedule

GET/timezone/dst

DST truth surface: current state, current abbreviation, last transition, next transition, and yearly DST context without guessing.

This is the endpoint to use when you need to answer “does this place observe DST?” or “when do clocks change this year?” with current and upcoming transition detail. The request example below uses the optional `at` and `year` parameters together.

Parameters

city, query, or timezonestring

Location input or direct IANA timezone.

countryCodestring

Optional ISO hint to break city-name ties.

atstring

Optional ISO timestamp, for example `2026-01-15T12:00:00Z`, that anchors lastTransition and nextTransition to a specific reference instant.

yearinteger

Optional calendar year that adds a year-specific transition view with transitions, springTransition, and fallTransition.

request

curl --request GET \
  --url "https://time-api.findtime.io/timezone/dst?timezone=Europe/London&at=2026-01-15T12:00:00Z&year=2026" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "shape": "dst_schedule.v2",
  "resolved": true,
  "referenceAt": "2026-01-15T12:00:00.000Z",
  "location": {
    "name": "London",
    "countryName": "United Kingdom",
    "timezoneIana": "Europe/London"
  },
  "timezone": {
    "abbreviation": "GMT",
    "longName": "Greenwich Mean Time",
    "utcOffset": "UTC+0"
  },
  "dst": {
    "observesDST": true,
    "isDSTActiveNow": false,
    "currentAbbreviation": "GMT",
    "lastTransition": {
      "type": "ends",
      "date": "October 26, 2025"
    },
    "nextTransition": {
      "type": "begins",
      "date": "March 29, 2026"
    },
    "year": 2026,
    "transitions": [
      {
        "type": "begins",
        "date": "March 29, 2026"
      },
      {
        "type": "ends",
        "date": "October 25, 2026"
      }
    ],
    "springTransition": {
      "type": "begins",
      "date": "March 29, 2026"
    },
    "fallTransition": {
      "type": "ends",
      "date": "October 25, 2026"
    }
  }
}

Core endpoint

convert_time

GET/time/convert

One-to-one or one-to-many conversion with explicit ambiguity handling. No silent guessing when inputs like CST or Victoria are underspecified.

Parameters

fromstring

Source location or timezone.

tostring

One target or pipe-delimited targets.

timestring

Source local time to convert.

datestring

ISO date for the conversion context.

request

curl --request GET \
  --url "https://time-api.findtime.io/time/convert?from=New%20York&to=London|Tokyo&toCountryCodes=GB|JP&time=9:00%20AM&date=2026-03-10" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "shape": "convert_time.v2",
  "source": {
    "location": {
      "name": "New York",
      "countryName": "United States"
    },
    "timezone": {
      "abbreviation": "EDT"
    },
    "currentTime": {
      "time12h": "9:00 AM"
    }
  },
  "targets": [
    {
      "location": { "name": "London", "countryName": "United Kingdom" },
      "timezone": { "abbreviation": "GMT" },
      "currentTime": { "time12h": "1:00 PM" }
    },
    {
      "location": { "name": "Tokyo", "countryName": "Japan" },
      "timezone": { "abbreviation": "JST" },
      "currentTime": { "time12h": "10:00 PM" }
    }
  ]
}

Differentiator

get_overlap_hours

GET/time/overlap

Shared business-hours overlap across locations. This is where findtime.io moves from utility to workflow intelligence.

This is one of the clearest parity++ surfaces. It answers the workflow question legacy time APIs usually leave to the caller.

Parameters

locationsstring

Pipe-delimited list of cities or timezones.

countryCodesstring

Optional pipe-delimited ISO hints aligned with the locations list.

datestring

ISO date used to compute the overlap window.

request

curl --request GET \
  --url "https://time-api.findtime.io/time/overlap?locations=New%20York|London&countryCodes=US|GB&date=2026-03-10" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "shape": "overlap_hours.v2",
  "resolved": true,
  "overlap": {
    "hasOverlap": true,
    "minutes": 300,
    "window": {
      "start": "2026-03-10T13:00:00.000Z",
      "end": "2026-03-10T18:00:00.000Z"
    }
  }
}

Differentiator

find_meeting_time

GET/meeting/find

Ranked meeting suggestions across multiple cities with a deep link back into findtime.io. This is one of the strongest parity++ surfaces in the platform.

Parameters

locationsstring

Pipe-delimited list of locations to include in the meeting search.

countryCodesstring

Optional pipe-delimited ISO hints aligned with the locations list.

datestring

Optional ISO date to anchor the meeting search.

request

curl --request GET \
  --url "https://time-api.findtime.io/meeting/find?locations=Tokyo|Cairo|New%20York&countryCodes=JP|EG|US" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "shape": "find_meeting_time.v2",
  "resolved": true,
  "options": [
    {
      "rank": 1,
      "score": 0.94,
      "deepLink": "https://findtime.io/..."
    },
    {
      "rank": 2,
      "score": 0.88,
      "deepLink": "https://findtime.io/..."
    }
  ]
}

Catalog

locations/search + locations/:id

GET/locations/search and /locations/:id

Search locations first, then hydrate exact locations by stable findtime: id. This keeps external callers on a clean, deterministic location model for findtime.io.

Parameters

querystring

Search term such as Victoria, Sao Paulo, or Tokyo.

countryCodestring

Optional ISO country hint for ranking and disambiguation. This is a hint, not an exclusive country filter.

limitnumber

Maximum number of search results to return.

request

curl --request GET \
  --url "https://time-api.findtime.io/locations/search?query=Victoria&countryCode=CA&limit=3" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "shape": "locations_search.v2",
  "results": [
    {
      "id": "findtime:victoria|CA|America/Vancouver",
      "name": "Victoria",
      "countryName": "Canada",
      "timezoneIana": "America/Vancouver",
      "population": 85792
    }
  ]
}

API

API Quick Reference

Production base URL: https://time-api.findtime.io
Flagship call: /time/snapshot
Use /locations/search first when you want deterministic location resolution, then store the returned findtime: id.
Every endpoint expects Authorization: Bearer YOUR_SECRET_KEY.
/time/overlap returns the shared overlap window across locations.
/meeting/find returns ranked meeting suggestions built from that overlap.

Surface	Best for	Why it matters
time_snapshot	Default integration	One-call packaged time intelligence with fewer follow-up requests.
get_overlap_hours	Scheduling workflows	Turns time data into useful workflow intelligence.
find_meeting_time	Agents and teams	Returns ranked meeting options across cities with a deep link back into `findtime.io`.

Open API health Open live JSON Open MCP Docs Apps and integrations

Plan Meetings Across Time Zones with findtime.io

How to use findtime.io

Time Zones Directory & World Clock

How to use this page

`findtime.io`
Time Intelligence for Apps and Agents

Ambiguity-safe

DST truth

Workflow layer

Agent-ready

API Quickstart

Why `findtime.io` API is different

Response contract and disambiguation

API Keys

time_snapshot

Parameters

get_current_time

Parameters

get_dst_schedule

Parameters

convert_time

Parameters

get_overlap_hours

Parameters

find_meeting_time

Parameters

locations/search + locations/:id

Parameters

API Quick Reference

Plan Meetings Across Time Zones with findtime.io

How to use findtime.io

Time Zones Directory & World Clock

How to use this page

findtime.ioTime Intelligence for Apps and Agents

Ambiguity-safe

DST truth

Workflow layer

Agent-ready

API Quickstart

Why findtime.io API is different

Response contract and disambiguation

API Keys

time_snapshot

Parameters

get_current_time

Parameters

get_dst_schedule

Parameters

convert_time

Parameters

get_overlap_hours

Parameters

find_meeting_time

Parameters

locations/search + locations/:id

Parameters

API Quick Reference

`findtime.io`
Time Intelligence for Apps and Agents

Why `findtime.io` API is different