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.

MCP clients reach the same tools two ways. The local package uses a developer API key. https://mcp.findtime.io/mcp uses OAuth 2.1 with PKCE, and it also accepts that API key as a bearer token. Read Hosted MCP.

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.
The same key authorizes the Time API, the local MCP package through FINDTIME_TIME_API_KEY, and the hosted MCP server as a bearer token.

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”, “convert 3pm next Tuesday in New York to London”, “working hours overlap for SF, Berlin, and Tokyo”, or “what does CST mean?”. This is the right endpoint for messy relative-date prompts such as “tomorrow”, “next Friday”, or “this weekend”. If your integration already knows the intent and has structured parameters, use the narrower endpoint directly; /time/convert can resolve simple time strings like “3pm Tuesday”, and overlap or meeting endpoints can resolve simple date strings like “Thursday”.

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. May include a simple human day phrase such as “3pm Tuesday”.

datestring

Date for the conversion context. Prefer ISO YYYY-MM-DD; simple human values such as “Thursday” or “tomorrow” are accepted.

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

Date used to compute the overlap window. Prefer ISO YYYY-MM-DD; simple human values such as “Thursday” or “tomorrow” are accepted and resolved relative to the first location timezone.

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

Date to anchor the meeting search. Prefer ISO YYYY-MM-DD; simple human values such as “Thursday” or “tomorrow” are accepted and resolved relative to the first location timezone.

durationMinutesintegerOptional

Optional meeting length. Only 30, 45, or 60 are written onto the planner link as aiDuration.

refstringOptional

Planner ref query param. MCP sends mcp-bot.

request

curl --request GET \
  --url "https://time-api.findtime.io/meeting/find?locations=New%20York|Sydney|Tokyo&countryCodes=US|AU|JP&date=2026-09-29&ref=mcp-bot" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "resolved": true,
  "ambiguous": false,
  "source": "deterministic",
  "locations": [
    {
      "query": "New York",
      "displayLabel": "New York City",
      "resolutionReason": "us_state=NY",
      "match": {
        "type": "city",
        "id": "findtime:new-york-city|US|America/New_York",
        "name": "New York City",
        "slug": "new-york-city",
        "countryCode": "US",
        "countryName": "United States",
        "timezoneIana": "America/New_York",
        "population": 8804190
      },
      "timezoneIana": "America/New_York"
    },
    {
      "query": "Sydney",
      "displayLabel": "Sydney",
      "resolutionReason": "countryCode=AU",
      "match": {
        "type": "city",
        "id": "findtime:sydney|AU|Australia/Sydney",
        "name": "Sydney",
        "slug": "sydney",
        "countryCode": "AU",
        "countryName": "Australia",
        "timezoneIana": "Australia/Sydney",
        "population": 5557233
      },
      "timezoneIana": "Australia/Sydney"
    },
    {
      "query": "Tokyo",
      "displayLabel": "Tokyo",
      "resolutionReason": null,
      "match": {
        "type": "city",
        "id": "findtime:tokyo|JP|Asia/Tokyo",
        "name": "Tokyo",
        "slug": "tokyo",
        "countryCode": "JP",
        "countryName": "Japan",
        "timezoneIana": "Asia/Tokyo",
        "population": 9733276
      },
      "timezoneIana": "Asia/Tokyo"
    }
  ],
  "date": "2026-09-29",
  "input": {
    "date": "2026-09-29"
  },
  "options": [
    {
      "rank": 1,
      "badnessScore": 2,
      "qualityLabel": "Excellent",
      "lines": [
        {
          "city": "New York City",
          "time": "Tue 6:00 PM"
        },
        {
          "city": "Tokyo",
          "time": "Wed 7:00 AM"
        },
        {
          "city": "Sydney",
          "time": "Wed 8:00 AM"
        }
      ],
      "startUtc": "2026-09-29T22:00:00.000Z"
    },
    {
      "rank": 2,
      "badnessScore": 2,
      "qualityLabel": "Excellent",
      "lines": [
        {
          "city": "New York City",
          "time": "Tue 7:00 PM"
        },
        {
          "city": "Tokyo",
          "time": "Wed 8:00 AM"
        },
        {
          "city": "Sydney",
          "time": "Wed 9:00 AM"
        }
      ],
      "startUtc": "2026-09-29T23:00:00.000Z"
    },
    {
      "rank": 3,
      "badnessScore": 4,
      "qualityLabel": "Good",
      "lines": [
        {
          "city": "New York City",
          "time": "Tue 6:00 AM"
        },
        {
          "city": "Tokyo",
          "time": "Tue 7:00 PM"
        },
        {
          "city": "Sydney",
          "time": "Tue 8:00 PM"
        }
      ],
      "startUtc": "2026-09-29T10:00:00.000Z"
    }
  ],
  "plannerUrl": "https://findtime.io/?aiCities=New%20York%20City%7CAmerica%2FNew_York%2CSydney%7CAustralia%2FSydney%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%206%3A00%20PM&aiSlots=2026-09-29T22%3A00%3A00.000Z%7C2026-09-29T23%3A00%3A00.000Z%7C2026-09-29T10%3A00%3A00.000Z&ref=mcp-bot",
  "shareText": "Meeting times
1. New York City Tue 6:00 PM · Tokyo Wed 7:00 AM · Sydney Wed 8:00 AM
2. New York City Tue 7:00 PM · Tokyo Wed 8:00 AM · Sydney Wed 9:00 AM
3. New York City Tue 6:00 AM · Tokyo Tue 7:00 PM · Sydney Tue 8:00 PM
https://findtime.io/?aiCities=New%20York%20City%7CAmerica%2FNew_York%2CSydney%7CAustralia%2FSydney%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%206%3A00%20PM&aiSlots=2026-09-29T22%3A00%3A00.000Z%7C2026-09-29T23%3A00%3A00.000Z%7C2026-09-29T10%3A00%3A00.000Z&ref=mcp-bot",
  "presentation": {
    "plainText": "Meeting times
1. New York City Tue 6:00 PM · Tokyo Wed 7:00 AM · Sydney Wed 8:00 AM
2. New York City Tue 7:00 PM · Tokyo Wed 8:00 AM · Sydney Wed 9:00 AM
3. New York City Tue 6:00 AM · Tokyo Tue 7:00 PM · Sydney Tue 8:00 PM
https://findtime.io/?aiCities=New%20York%20City%7CAmerica%2FNew_York%2CSydney%7CAustralia%2FSydney%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%206%3A00%20PM&aiSlots=2026-09-29T22%3A00%3A00.000Z%7C2026-09-29T23%3A00%3A00.000Z%7C2026-09-29T10%3A00%3A00.000Z&ref=mcp-bot"
  }
}

Differentiator

check_proposed_time

GET/meeting/check

Judge a proposed meeting instant for each city. Returns verdicts, alternatives, shareText, and a planner URL with up to three UTC aiSlots.

Production https://time-api.findtime.io returns 404 for /meeting/check, /meeting/awake, /meeting/recurring, and /meeting/team until this branch is deployed to Time API. The find_meeting_time shareText field is on the same branch.

Parameters

locationsstring

Pipe-delimited cities or timezones.

countryCodesstringOptional

Pipe-delimited ISO hints aligned with locations.

startstring

ISO instant with offset, or a floating local time such as 2026-09-29T09:00.

homestringOptional

IANA timezone for a floating start, such as America/Los_Angeles.

datestringOptional

YYYY-MM-DD when start is only a clock time.

durationMinutesintegerOptional

Optional. Only 30, 45, or 60 are written onto the planner link.

workStartintegerOptional

First in-hours local hour. Default 9.

workEndintegerOptional

Last in-hours local hour, inclusive. Default 18.

request

curl --request GET \
  --url "https://time-api.findtime.io/meeting/check?locations=San%20Francisco|London|Tokyo&countryCodes=US|GB|JP&start=2026-09-29T09:00&home=America/Los_Angeles" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "resolved": true,
  "startUtc": "2026-09-29T16:00:00.000Z",
  "overall": "bad",
  "workStart": 9,
  "workEnd": 18,
  "verdicts": [
    {
      "city": "San Francisco",
      "timezone": "America/Los_Angeles",
      "local": "Tue 9:00 AM",
      "verdict": "ok",
      "weekend": false,
      "hour": 9
    },
    {
      "city": "London",
      "timezone": "Europe/London",
      "local": "Tue 5:00 PM",
      "verdict": "ok",
      "weekend": false,
      "hour": 17
    },
    {
      "city": "Tokyo",
      "timezone": "Asia/Tokyo",
      "local": "Wed 1:00 AM",
      "verdict": "sleep",
      "weekend": false,
      "hour": 1
    }
  ],
  "alternatives": [
    {
      "rank": 1,
      "badnessScore": 6,
      "qualityLabel": "Acceptable",
      "lines": [
        {
          "city": "San Francisco",
          "time": "Tue 1:00 PM"
        },
        {
          "city": "London",
          "time": "Tue 9:00 PM"
        },
        {
          "city": "Tokyo",
          "time": "Wed 5:00 AM"
        }
      ],
      "startUtc": "2026-09-29T20:00:00.000Z"
    },
    {
      "rank": 2,
      "badnessScore": 8,
      "qualityLabel": "Late hours",
      "lines": [
        {
          "city": "San Francisco",
          "time": "Tue 6:00 AM"
        },
        {
          "city": "London",
          "time": "Tue 2:00 PM"
        },
        {
          "city": "Tokyo",
          "time": "Tue 10:00 PM"
        }
      ],
      "startUtc": "2026-09-29T13:00:00.000Z"
    },
    {
      "rank": 3,
      "badnessScore": 8,
      "qualityLabel": "Late hours",
      "lines": [
        {
          "city": "San Francisco",
          "time": "Tue 12:00 PM"
        },
        {
          "city": "London",
          "time": "Tue 8:00 PM"
        },
        {
          "city": "Tokyo",
          "time": "Wed 4:00 AM"
        }
      ],
      "startUtc": "2026-09-29T19:00:00.000Z"
    }
  ],
  "plannerUrl": "https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%201%3A00%20PM&aiSlots=2026-09-29T20%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z%7C2026-09-29T19%3A00%3A00.000Z&ref=mcp-bot",
  "shareText": "Proposed time is rough
San Francisco Tue 9:00 AM (ok)
London Tue 5:00 PM (ok)
Tokyo Wed 1:00 AM (sleep)
Alt 1. San Francisco Tue 1:00 PM · London Tue 9:00 PM · Tokyo Wed 5:00 AM
Alt 2. San Francisco Tue 6:00 AM · London Tue 2:00 PM · Tokyo Tue 10:00 PM
Alt 3. San Francisco Tue 12:00 PM · London Tue 8:00 PM · Tokyo Wed 4:00 AM
https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%201%3A00%20PM&aiSlots=2026-09-29T20%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z%7C2026-09-29T19%3A00%3A00.000Z&ref=mcp-bot",
  "presentation": {
    "plainText": "Proposed time is rough
San Francisco Tue 9:00 AM (ok)
London Tue 5:00 PM (ok)
Tokyo Wed 1:00 AM (sleep)
Alt 1. San Francisco Tue 1:00 PM · London Tue 9:00 PM · Tokyo Wed 5:00 AM
Alt 2. San Francisco Tue 6:00 AM · London Tue 2:00 PM · Tokyo Tue 10:00 PM
Alt 3. San Francisco Tue 12:00 PM · London Tue 8:00 PM · Tokyo Wed 4:00 AM
https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%201%3A00%20PM&aiSlots=2026-09-29T20%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z%7C2026-09-29T19%3A00%3A00.000Z&ref=mcp-bot"
  }
}

Differentiator

are_they_awake

GET/meeting/awake

Say whether people in other cities are in work, awake, or sleep at one moment. Use for ping timing before you interrupt someone in another timezone.

Parameters

theirCitystringOptional

One city or timezone to judge.

theirCitiesstringOptional

Pipe-delimited cities or timezones to judge.

myTimestringOptional

ISO instant or floating local time in myTimezone. Defaults to now.

myTimezonestringOptional

IANA timezone for the caller, such as America/Los_Angeles.

myCitystringOptional

Caller city when myTimezone is omitted.

datestringOptional

YYYY-MM-DD when myTime is only a clock time.

durationMinutesintegerOptional

Optional. Only 30, 45, or 60 are written onto the planner link.

workStartintegerOptional

First in-hours local hour. Default 9.

workEndintegerOptional

Last in-hours local hour, inclusive. Default 18.

request

curl --request GET \
  --url "https://time-api.findtime.io/meeting/awake?myTime=2026-09-29T15:00&myTimezone=America/Los_Angeles&theirCity=Bangalore" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "resolved": true,
  "startUtc": "2026-09-29T22:00:00.000Z",
  "rows": [
    {
      "role": "me",
      "city": "America/Los_Angeles",
      "timezone": "America/Los_Angeles",
      "local": "Tue 3:00 PM",
      "verdict": "ok",
      "label": "work",
      "weekend": false,
      "hour": 15
    },
    {
      "role": "them",
      "city": "Bengaluru",
      "timezone": "Asia/Kolkata",
      "local": "Wed 3:30 AM",
      "verdict": "sleep",
      "label": "sleep",
      "weekend": false,
      "hour": 3
    }
  ],
  "needsRescue": true,
  "alternatives": [
    {
      "rank": 1,
      "badnessScore": 2,
      "qualityLabel": "Excellent",
      "lines": [
        {
          "city": "America/Los_Angeles",
          "time": "Tue 7:00 AM"
        },
        {
          "city": "Bengaluru",
          "time": "Tue 7:30 PM"
        }
      ],
      "startUtc": "2026-09-29T14:00:00.000Z"
    },
    {
      "rank": 2,
      "badnessScore": 2,
      "qualityLabel": "Excellent",
      "lines": [
        {
          "city": "America/Los_Angeles",
          "time": "Tue 7:00 PM"
        },
        {
          "city": "Bengaluru",
          "time": "Wed 7:30 AM"
        }
      ],
      "startUtc": "2026-09-30T02:00:00.000Z"
    },
    {
      "rank": 3,
      "badnessScore": 4,
      "qualityLabel": "Good",
      "lines": [
        {
          "city": "America/Los_Angeles",
          "time": "Tue 6:00 AM"
        },
        {
          "city": "Bengaluru",
          "time": "Tue 6:30 PM"
        }
      ],
      "startUtc": "2026-09-29T13:00:00.000Z"
    }
  ],
  "plannerUrl": "https://findtime.io/?aiCities=America%2FLos_Angeles%7CAmerica%2FLos_Angeles%2CBengaluru%7CAsia%2FKolkata&aiTime=Tue%207%3A00%20AM&aiSlots=2026-09-29T14%3A00%3A00.000Z%7C2026-09-30T02%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z&ref=mcp-bot",
  "shareText": "Not a good ping
America/Los_Angeles Tue 3:00 PM (work)
Bengaluru Wed 3:30 AM (sleep)
Better 1. America/Los_Angeles Tue 7:00 AM · Bengaluru Tue 7:30 PM
Better 2. America/Los_Angeles Tue 7:00 PM · Bengaluru Wed 7:30 AM
Better 3. America/Los_Angeles Tue 6:00 AM · Bengaluru Tue 6:30 PM
https://findtime.io/?aiCities=America%2FLos_Angeles%7CAmerica%2FLos_Angeles%2CBengaluru%7CAsia%2FKolkata&aiTime=Tue%207%3A00%20AM&aiSlots=2026-09-29T14%3A00%3A00.000Z%7C2026-09-30T02%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z&ref=mcp-bot",
  "presentation": {
    "plainText": "Not a good ping
America/Los_Angeles Tue 3:00 PM (work)
Bengaluru Wed 3:30 AM (sleep)
Better 1. America/Los_Angeles Tue 7:00 AM · Bengaluru Tue 7:30 PM
Better 2. America/Los_Angeles Tue 7:00 PM · Bengaluru Wed 7:30 AM
Better 3. America/Los_Angeles Tue 6:00 AM · Bengaluru Tue 6:30 PM
https://findtime.io/?aiCities=America%2FLos_Angeles%7CAmerica%2FLos_Angeles%2CBengaluru%7CAsia%2FKolkata&aiTime=Tue%207%3A00%20AM&aiSlots=2026-09-29T14%3A00%3A00.000Z%7C2026-09-30T02%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z&ref=mcp-bot"
  }
}

Differentiator

rank_recurring_slot

GET/meeting/recurring

Score who a weekly wall-clock time punishes across the next few weeks, including a daylight-saving week when one falls in the scan window. Returns per-city pain, a kinder slot, shareText, and plannerUrl.

Parameters

locationsstring

Pipe-delimited cities or timezones.

countryCodesstringOptional

Pipe-delimited ISO hints aligned with locations.

weekdaystring

Day name such as Mon or Monday.

timestring

Clock time such as 9am or 09:00 in the home timezone.

homestring

IANA timezone of the recurring clock, such as America/Los_Angeles.

occurrencesintegerOptional

Weeks to score before adding a DST week. Default 4. Max 8.

nowstringOptional

ISO instant used as today when choosing the next weekday.

durationMinutesintegerOptional

Optional. Only 30, 45, or 60 are written onto the planner link.

workStartintegerOptional

First in-hours local hour. Default 9.

workEndintegerOptional

Last in-hours local hour, inclusive. Default 18.

request

curl --request GET \
  --url "https://time-api.findtime.io/meeting/recurring?locations=San%20Francisco|London|Bangalore&countryCodes=US|GB|IN&weekday=Mon&time=9am&home=America/Los_Angeles&now=2026-09-29T16:00:00.000Z" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "resolved": true,
  "weekday": "Mon",
  "home": "America/Los_Angeles",
  "time": "09:00",
  "summary": [
    {
      "city": "San Francisco",
      "timezone": "America/Los_Angeles",
      "pain": 0,
      "verdict": "ok",
      "weekend": false,
      "local": "Mon 9:00 AM"
    },
    {
      "city": "London",
      "timezone": "Europe/London",
      "pain": 0,
      "verdict": "ok",
      "weekend": false,
      "local": "Mon 5:00 PM"
    },
    {
      "city": "Bengaluru",
      "timezone": "Asia/Kolkata",
      "pain": 6,
      "verdict": "late",
      "weekend": false,
      "local": "Mon 9:30 PM"
    }
  ],
  "occurrences": [
    {
      "week": 0,
      "date": "2026-10-05",
      "startUtc": "2026-10-05T16:00:00.000Z",
      "cities": [
        {
          "city": "San Francisco",
          "timezone": "America/Los_Angeles",
          "local": "Mon 9:00 AM",
          "verdict": "ok",
          "weekend": false,
          "pain": 0,
          "offsetMinutes": -420
        },
        {
          "city": "London",
          "timezone": "Europe/London",
          "local": "Mon 5:00 PM",
          "verdict": "ok",
          "weekend": false,
          "pain": 0,
          "offsetMinutes": 60
        },
        {
          "city": "Bengaluru",
          "timezone": "Asia/Kolkata",
          "local": "Mon 9:30 PM",
          "verdict": "late",
          "weekend": false,
          "pain": 6,
          "offsetMinutes": 330
        }
      ]
    },
    {
      "week": 1,
      "date": "2026-10-12",
      "startUtc": "2026-10-12T16:00:00.000Z",
      "cities": [
        {
          "city": "San Francisco",
          "timezone": "America/Los_Angeles",
          "local": "Mon 9:00 AM",
          "verdict": "ok",
          "weekend": false,
          "pain": 0,
          "offsetMinutes": -420
        },
        {
          "city": "London",
          "timezone": "Europe/London",
          "local": "Mon 5:00 PM",
          "verdict": "ok",
          "weekend": false,
          "pain": 0,
          "offsetMinutes": 60
        },
        {
          "city": "Bengaluru",
          "timezone": "Asia/Kolkata",
          "local": "Mon 9:30 PM",
          "verdict": "late",
          "weekend": false,
          "pain": 6,
          "offsetMinutes": 330
        }
      ]
    },
    {
      "week": 2,
      "date": "2026-10-19",
      "startUtc": "2026-10-19T16:00:00.000Z",
      "cities": [
        {
          "city": "San Francisco",
          "timezone": "America/Los_Angeles",
          "local": "Mon 9:00 AM",
          "verdict": "ok",
          "weekend": false,
          "pain": 0,
          "offsetMinutes": -420
        },
        {
          "city": "London",
          "timezone": "Europe/London",
          "local": "Mon 5:00 PM",
          "verdict": "ok",
          "weekend": false,
          "pain": 0,
          "offsetMinutes": 60
        },
        {
          "city": "Bengaluru",
          "timezone": "Asia/Kolkata",
          "local": "Mon 9:30 PM",
          "verdict": "late",
          "weekend": false,
          "pain": 6,
          "offsetMinutes": 330
        }
      ]
    },
    {
      "week": 3,
      "date": "2026-10-26",
      "startUtc": "2026-10-26T16:00:00.000Z",
      "cities": [
        {
          "city": "San Francisco",
          "timezone": "America/Los_Angeles",
          "local": "Mon 9:00 AM",
          "verdict": "ok",
          "weekend": false,
          "pain": 0,
          "offsetMinutes": -420
        },
        {
          "city": "London",
          "timezone": "Europe/London",
          "local": "Mon 4:00 PM",
          "verdict": "ok",
          "weekend": false,
          "pain": 0,
          "offsetMinutes": 0
        },
        {
          "city": "Bengaluru",
          "timezone": "Asia/Kolkata",
          "local": "Mon 9:30 PM",
          "verdict": "late",
          "weekend": false,
          "pain": 6,
          "offsetMinutes": 330
        }
      ]
    }
  ],
  "dstDate": "2026-10-26",
  "alternate": {
    "rank": 1,
    "badnessScore": 2,
    "qualityLabel": "Excellent",
    "lines": [
      {
        "city": "San Francisco",
        "time": "Mon 7:00 AM"
      },
      {
        "city": "London",
        "time": "Mon 3:00 PM"
      },
      {
        "city": "Bengaluru",
        "time": "Mon 7:30 PM"
      }
    ],
    "startUtc": "2026-10-05T14:00:00.000Z"
  },
  "plannerUrl": "https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CBengaluru%7CAsia%2FKolkata&aiTime=Mon%207%3A00%20AM&aiSlots=2026-10-05T14%3A00%3A00.000Z%7C2026-10-05T13%3A00%3A00.000Z%7C2026-10-05T15%3A00%3A00.000Z&ref=mcp-bot",
  "shareText": "Standup pain · Mon 09:00 America/Los_Angeles
San Francisco Mon 9:00 AM (ok, pain 0)
London Mon 5:00 PM (ok, pain 0)
Bengaluru Mon 9:30 PM (late, pain 6)
DST week 2026-10-26: San Francisco Mon 9:00 AM · London Mon 4:00 PM · Bengaluru Mon 9:30 PM
Kinder slot. San Francisco Mon 7:00 AM · London Mon 3:00 PM · Bengaluru Mon 7:30 PM
https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CBengaluru%7CAsia%2FKolkata&aiTime=Mon%207%3A00%20AM&aiSlots=2026-10-05T14%3A00%3A00.000Z%7C2026-10-05T13%3A00%3A00.000Z%7C2026-10-05T15%3A00%3A00.000Z&ref=mcp-bot",
  "presentation": {
    "plainText": "Standup pain · Mon 09:00 America/Los_Angeles
San Francisco Mon 9:00 AM (ok, pain 0)
London Mon 5:00 PM (ok, pain 0)
Bengaluru Mon 9:30 PM (late, pain 6)
DST week 2026-10-26: San Francisco Mon 9:00 AM · London Mon 4:00 PM · Bengaluru Mon 9:30 PM
Kinder slot. San Francisco Mon 7:00 AM · London Mon 3:00 PM · Bengaluru Mon 7:30 PM
https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CBengaluru%7CAsia%2FKolkata&aiTime=Mon%207%3A00%20AM&aiSlots=2026-10-05T14%3A00%3A00.000Z%7C2026-10-05T13%3A00%3A00.000Z%7C2026-10-05T15%3A00%3A00.000Z&ref=mcp-bot"
  }
}

Teams

team

GET/meeting/team

Homepage planner Saved groups and a hosted agent's teams are one record when both use the same Google account. list_teams returns those names. Pass that exact spelling as teamId to load the group's cities when the call has no locations. save_team writes the full city list. A city may be a plain name or City|IANA. rename_team and delete_team need the meetings:plan scope. list_teams and get_team need time:read. A deleted group stays deleted. Marketing and marketing are two groups. This public route does not read the account. An API key gets teams_not_persisted. Pass locations on each meeting call in that case.

Parameters

teamIdstringOptional

Exact homepage group name. This public route still returns the stub. A signed-in hosted agent loads that group.

request

curl --request GET \
  --url "https://time-api.findtime.io/meeting/team?teamId=standup" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

response

{
  "stub": true,
  "error": "teams_not_persisted",
  "teamId": "standup",
  "message": "No-auth MCP does not store teams. Pass locations on each call. Account storage is a later batch."
}

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.
Hosted MCP is POST https://mcp.findtime.io/mcp with OAuth 2.1 and PKCE, and it accepts bearer API keys.
/time/overlap returns the shared overlap window across locations.
/meeting/find returns ranked meeting suggestions with shareText and a planner URL.
/meeting/check, /meeting/awake, and /meeting/recurring return paste-ready meeting intelligence for proposed times, ping timing, and recurring standups.
/meeting/team does not store a team.

Surface	Best for	Why it matters
answer_time_question	Raw user prompts	Classifies time questions, resolves relative dates like tomorrow or next Friday, 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 `shareText` and a planner URL.
check_proposed_time	Proposed slots	Verdicts per city plus alternatives when the proposed instant is rough.
are_they_awake	Ping timing	Work, awake, or sleep labels for other cities at your moment.
rank_recurring_slot	Weekly standups	Per-city pain, daylight-saving week, and a kinder recurring slot.
team	Saved teams	Homepage Saved groups and a hosted agent on the same Google account share one list. Copy the exact name from list_teams. save_team writes the full city list, as a plain name or City\|IANA. rename_team and delete_team need meetings:plan. A deleted group stays deleted. An API key gets teams_not_persisted.

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

check_proposed_time

Parameters

are_they_awake

Parameters

rank_recurring_slot

Parameters

team

Parameters

locations/search + locations/:id

Parameters

API Quick Reference

`findtime.io`
Time Intelligence for Apps and Agents

Why `findtime.io` API is different