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/answer for raw user prompts, or /time/snapshot when you already know the locations and want packaged time data.

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 are building an agent or accepting raw user text, start with /time/answer. If your app already knows the intent, use the narrower deterministic endpoint directly, such as /time/snapshot for one-call packaged time data.

What to expect:

Every API request uses Authorization: Bearer YOUR_SECRET_KEY.
All current endpoints are GET requests.
Use /time/answer when you want findtime.io to classify a natural-language prompt and choose the right deterministic behavior. Use narrower endpoints directly when your app already knows the intent.
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 /time/answer for natural-language prompts, or use narrower deterministic endpoints when your integration already knows the intent.

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/answer is the natural-language agent endpoint. It returns intent, toolUsed, answer, and the underlying deterministic result so callers can audit how the answer was produced. Structured callers can skip classification and call the narrower endpoint directly.
/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 use /time/answer or /locations/search to get structured clarification.
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"

Agent endpoint

answer_time_question

GET/time/answer

Natural-language time intelligence for apps and agents. Send the raw user prompt and findtime.io classifies the intent, dispatches to deterministic time behavior, and returns either an answer or structured clarification.

Use this as the default entry point for natural-language prompts like “3pm PST to London”, “what is the IANA timezone for San Francisco?”, “working hours overlap for SF, Berlin, and Tokyo”, or “what does CST mean?”. If your integration already knows the intent and has structured parameters, use the narrower endpoint directly.

Parameters

querystring

Raw natural-language time, timezone, conversion, DST, overlap, scheduling, abbreviation, or IANA question.

userTimezonestringOptional

IANA timezone for the user, used for relative questions like “my time” or “tomorrow”.

localestringOptional

Locale hint such as en-US.

nowstringOptional

ISO timestamp for deterministic relative-date handling.

datestringOptional

YYYY-MM-DD date context.

request

curl --request GET \
  --url "https://time-api.findtime.io/time/answer?query=what%20is%20the%20IANA%20timezone%20for%20San%20Francisco%3F" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "shape": "answer_time_question.v1",
  "resolved": true,
  "status": "ok",
  "intent": "iana_timezone_lookup",
  "query": "what is the IANA timezone for San Francisco?",
  "answer": "The IANA timezone for San Francisco, United States is America/Los_Angeles.",
  "toolUsed": "get_current_time",
  "confidence": "high",
  "needsClarification": false,
  "result": {
    "shape": "current_time.v2",
    "resolved": true,
    "location": {
      "name": "San Francisco",
      "countryName": "United States",
      "timezoneIana": "America/Los_Angeles"
    },
    "timezone": {
      "iana": "America/Los_Angeles",
      "abbreviation": "PDT",
      "utcOffset": "UTC-7"
    }
  }
}

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 countryCodesstringOptional

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

includeTransitionsbooleanOptional

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.

countryCodestringOptional

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.

countryCodestringOptional

ISO hint to break city-name ties.

atstringOptional

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

yearintegerOptional

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.

countryCodesstringOptional

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.

countryCodesstringOptional

Pipe-delimited ISO hints aligned with the locations list.

datestringOptional

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.

countryCodestringOptional

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

limitnumberOptional

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
Natural-language agent call: /time/answer
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
answer_time_question	Raw user prompts	Classifies time questions, answers them through deterministic handlers, and returns structured clarification for ambiguity.
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 answer JSON Open live JSON Open MCP Docs Apps and integrations

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

answer_time_question

Parameters

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