{ "service": "time", "title": "Time API", "description": "Current time anywhere. Local date and time, Unix seconds, UTC offset and daylight saving. Supply an IANA timezone, coordinates, an explicit IP, city, country, airport, supported port or US address; /time defaults to UTC. Discover and filter timezone identifiers with /time/zones. Convert one instant with to or up to ten targets.", "endpoints": { "now": "GET /time", "lookup": "GET /time/{timezone}", "locate": "GET /time?lat={lat}&lon={lon}", "convert": "GET /time/{timezone}?to={timezone}&at={time}", "zones": "GET /time/zones?q={query}", "convert_many": "GET /time/{timezone}?targets={timezone1},{timezone2}&at={time}", "location": "GET /time?city={city}&country={country}" }, "examples": { "utc": "/time", "encoded": "/time/America%2FNew_York", "path": "/time/America/New_York", "at": "/time/America%2FNew_York?at=2026-01-15T12:00:00Z", "convert": "/time/America/New_York?to=Asia/Tokyo&at=2026-08-29T15:00", "coords": "/time?lat=40.7128&lon=-74.006", "coords_at": "/time?lat=40.7128&lon=-74.006&at=2026-01-15T12:00:00Z", "coords_convert": "/time?lat=40.7128&lon=-74.006&to=Asia/Tokyo&at=2026-08-29T15:00", "deep": "/time/America/New_York?deep=true", "reject_ambiguous": "/time/America/New_York?to=UTC&at=2026-11-01T01:30&disambiguation=reject", "zones": "/time/zones", "zones_search": "/time/zones?q=new%20york", "convert_many": "/time/America/New_York?targets=Europe/London,Asia/Tokyo&at=2026-08-29T15:00", "city": "/time?city=Paris&country=FR", "country": "/time?country=IE", "ip": "/time?ip=8.8.8.8", "airport": "/time?iata=JFK", "icao": "/time?icao=KJFK", "address": "/time?address=1600%20Pennsylvania%20Ave%20NW%2C%20Washington%2C%20DC%2020500&country=US", "filtered_zones": "/time/zones?country=US&observes_dst=true&details=true&at=2026-01-01", "abbreviation_candidates": "/time/zones?abbreviation=CST&details=true&at=2026-01-01", "port": "/time?unlocode=USNYC" }, "response": { "latitude": "Input latitude for coordinate mode; resolved location latitude for explicit location mode, otherwise null when absent or unresolved", "longitude": "Input longitude for coordinate mode; resolved location longitude for explicit location mode, otherwise null when absent or unresolved", "timezone": "IANA timezone id. Nautical Etc/GMT zone over open ocean", "abbreviation": "Short zone name (EDT, EST, …)", "offset": "Exact UTC offset: ±HH:MM, with :SS for historical zones whose offsets included seconds", "dst": "The timezone rule DST indicator, including negative seasonal adjustments (Ireland winter time and Morocco Ramadan suspension). It does not mean the clock is ahead of UTC.", "at": "Resolved local date and time as ISO 8601 with its UTC offset, on every successful lookup. Null when coordinates are unmapped.", "to": "With ?to= only: the target timezone at the same instant, including at and unix. Null when the source coordinates are unmapped.", "unix": "Seconds since 1970-01-01T00:00:00Z, rounded down. Both conversion zones have the same unix value. Null when coordinates are unmapped.", "deep": "With ?deep=true: optional detail, included on every plan.", "targets": "With targets only: 1–10 destination objects in request order, including duplicates, at the same instant. Each has the same shape as to, including optional deep. Null when the source coordinates are unmapped. Never combined with to.", "location": "Only with an explicit location selector: { input: { type, value }, status, candidates, truncated, source }. Status is resolved, ambiguous or not_found. Ambiguous/missing results retain null clock/coordinate fields and null to/targets; choose a returned timezone or refine city/country/state explicitly. At most 50 candidates; truncated=true never selects a winner." }, "parameters": { "lat": "Latitude (-90 to 90), with lon", "lon": "Longitude (-180 to 180), with lat", "at": "ISO date or timestamp (default: now). Without to or targets, a missing UTC offset means UTC. With to or targets, it means local wall time in the source zone. Impossible calendar dates reject. Explicit offsets always identify an instant. Supported instants are UTC years 0001 through 9999; returned local timestamps may cross into year 0000 or +010000 and still round-trip. ISO input only, not a Unix timestamp; fractional seconds support up to three digits.", "to": "Target IANA timezone. Works with an IANA, coordinate or explicit-location source. Invalid destinations reject even when the source location is unresolved.", "deep": "With ?deep=true: optional detail, included on every plan.", "lang": "Optional display language: one BCP 47 tag, up to 64 characters. Supports 41 language, script and regional choices. Missing translations keep existing display names; no lang preserves existing behavior. Invalid or empty tags return 400.", "disambiguation": "How to resolve an offsetless at with to or targets: compatible (default) selects the earlier repeated time and advances a skipped time by the clock jump; earlier selects the earlier instant, including moving backward across a gap; later selects the later instant; reject returns HTTP 400 with code ambiguous_time for repeated wall times or nonexistent_time for skipped wall times. Valid settings do not change explicit-offset instants, now, or requests without to or targets. Invalid settings return 400.", "targets": "Optional comma-separated list of 1–10 IANA timezone identifiers, each at most 64 characters after trimming; raw query value at most 649 characters. Mutually exclusive with to. Order and duplicates are preserved. Every target shares one captured instant and source wall-time resolution. An unknown target rejects the entire request with 404; malformed lists or mixed selectors return 400. One pooled request, with no per-target charge.", "q": "On /time/zones only: optional identifier search, at most 64 characters after trimming. All case-insensitive whitespace-separated tokens must occur in the identifier; spaces and underscores are equivalent. Omit or leave blank for all identifiers. Use explicit city or abbreviation parameters for those input types.", "id": "Optional IANA source identifier on /time; omit for UTC. Mutually exclusive with a timezone path, coordinates or a location selector.", "ip": "Explicit IPv4 or IPv6 address, at most 45 characters. Uses existing geofeed or measured-location evidence; never silently uses the caller IP or registry allocation country. Private/special-use or unlocated addresses return not_found. IP location is an estimate.", "city": "Exact stored city name or stable city ID, at most 200 characters. Optional country/state narrow matches. Multiple matches return candidates; no population-based default.", "country": "Two-letter country code. By itself selects the country-specific IANA zone choices; a multi-zone country returns ambiguous candidates. With city/address it is context. On /time/zones it filters source-recorded country associations, which can be plural.", "state": "Optional 1–3-character state code (or matching CC- prefix), only with city/address and country.", "iata": "Three-letter airport code, mutually exclusive with other source selectors. Resolves the captured airport point through serving timezone boundaries.", "icao": "Four-letter airport code, mutually exclusive with other source selectors. Airport-code duplicates remain candidate choices.", "address": "Address text, at most 200 characters, with country=US. Exact matching against existing address points; unsupported countries reject. A missing/ambiguous address never becomes an invented point or timezone. This is location matching, not postal-delivery or ownership validation.", "area": "On /time/zones only: IANA naming area, such as America, Europe, Atlantic, Indian or Etc. Not a physical-continent classification.", "offset": "On /time/zones only: exact signed UTC offset at the selected instant, ±HH:MM or historical ±HH:MM:SS. URL-encode a literal + as %2B.", "abbreviation": "On /time/zones only: exact case-insensitive abbreviation at the selected instant. Returns all matching identifiers; ambiguous CST never silently selects one region.", "dst": "On /time/zones only: true or false, filtering the actual DST flag at the selected instant, including negative saving.", "observes_dst": "On /time/zones only: true or false, filtering whether the actual DST flag occurs at any instant in the selected instant’s UTC calendar year. This differs from whether DST is active now.", "details": "On /time/zones only: true adds rich zones rows and one shared UTC at; false or omission keeps the identifiers list.", "sort": "On /time/zones only: timezone (default), or numerical offset with timezone identifier as tie-breaker.", "unlocode": "Five-character UN/LOCODE, with an optional single space after its two-letter country prefix. Resolves captured NGA World Port Index points only, not the complete UN/LOCODE directory. Unknown codes return not_found; duplicate locations remain explicit candidates." }, "tips": [ "URL-encode / in the timezone as %2F, or use /time/America/New_York", "Pass lat and lon when you have a point, not an IANA id", "Convert with ?to=: /time/America/New_York?to=Asia/Tokyo&at=2026-08-29T15:00 answers 2026-08-30T04:00:00+09:00. No ?at= converts now", "Open ocean answers nautical time: Etc/GMT ids carry the POSIX sign, so Etc/GMT+3 means UTC-03:00. The offset fields read the normal way", "Pass ?at= for historical or future offsets", "Without disambiguation, local times in a spring-forward gap advance by the size of the jump and repeated fall-back times choose the earlier instant. Choose disambiguation=reject to require an unambiguous wall time, earlier or later to choose an occurrence, or pass an explicit UTC offset.", "Clock responses use Cache-Control: no-store. unix is integer seconds; at preserves milliseconds when present.", "Existing /timezone paths remain compatible. Bare /timezone requires lat and lon; bare /time defaults to UTC.", "Some historical offsets include seconds, for example Paris in 1900: +00:09:21. at preserves that offset, offset_seconds is exact, and unix identifies the instant. The API accepts its own at value on the next request.", "Historical results use the best available recorded rules for the named zone; very early local records can be incomplete. Future rules can change when governments change them.", "Without ?deep=true the deep key is omitted. With ?deep=true: optional detail, included on every plan.", "URL-encode a literal + in an at offset as %2B, or use your HTTP client query builder; unix is output in seconds, not milliseconds.", "Timezone offsets, abbreviations and DST flags use the bundled IANA 2026c snapshot. It is a pinned rule edition, not a claim of live updates; future government changes require a reviewed refresh.", "Use /time/zones to populate a picker from supported identifiers and aliases. Its timezones array is sorted, and a search with no matches returns []. The response identifies the bundled timezone_database_version.", "targets provides bounded multi-zone conversion on current /time routes only. Existing /timezone routes retain scalar to. Both scalar and multi-zone conversion use one pooled request; deep adds no extra charge.", "With deep=true, resolution reports what actually happened to source wall time. An explicit offset is authoritative even when that offset differs from the named source zone at that instant; the answer is rendered in the named zone and resolution is null.", "Choose exactly one source mode. country/state can narrow city/address; they cannot override timezone/coordinate/airport/IP input. All location, lookup and up-to-ten-target conversion requests use the same pooled request unit.", "Location status ambiguous or not_found returns HTTP 200 with null clock fields and explicit candidates. A store failure returns 503 with a static message, never a fabricated miss.", "Standard offsets, seasonal boundaries and country timezone choices use the same pinned IANA edition. Existing address/city/IP observations and captured airport points have their own source limits; rule edition is not a freshness promise for those datasets." ], "deep": { "name": "Friendly generic name, or null when the display name cannot be verified against the active timezone rule", "offset_minutes": "Whole UTC offset minutes, truncated toward zero. Use offset_seconds for exact historical offsets.", "offset_seconds": "Exact UTC offset in seconds (integer); null when coordinates are unmapped", "next_dst": "Next UTC offset change within 400 days as { at, dst, offset, abbreviation }, including political changes, or null when none is found in that window.", "timezone_database_version": "Actual bundled IANA timezone-rule edition used for this answer. It does not identify the separate coordinate boundaries or ICU display-name data; this is a pinned edition, not a live freshness guarantee.", "resolution": "Source wall-time resolution when offsetless at is converted with to or targets: { kind, policy, adjustment_seconds, alternatives }. Null for now, explicit-offset input, no conversion, or unmapped coordinates. Source only; never repeated in destination deep.", "standard_offset": "Exact standard UTC offset from the same pinned source at the selected instant, or null when unresolved. Includes :SS for historical seconds.", "standard_offset_seconds": "Exact source standard offset in seconds. Not inferred from winter, January or nearby dates; Ireland can have a +3600 standard base in winter.", "dst_offset_seconds": "Total UTC offset minus the source standard offset. Can be negative (Ireland/Morocco), zero or positive; null when unresolved.", "season": "Current continuous DST-flag interval, or the next beginning within 400 days if DST is inactive: { start, end }, each nullable. Each boundary gives { at, before, after, change_seconds }; before/after are the boundary clock reading under old/new offsets with { at, offset, offset_seconds, abbreviation, dst }. Both describe one transition instant. Seasons can cross years; political changes without a DST-flag change are not season boundaries. No matching season is null; unsupported/absent endpoints remain null." }, "to_response": { "timezone": "IANA timezone id. Nautical Etc/GMT zone over open ocean", "abbreviation": "Short zone name (EDT, EST, …)", "offset": "Exact UTC offset: ±HH:MM, with :SS for historical zones whose offsets included seconds", "dst": "The timezone rule DST indicator, including negative seasonal adjustments (Ireland winter time and Morocco Ramadan suspension). It does not mean the clock is ahead of UTC.", "at": "Resolved local date and time as ISO 8601 with its UTC offset, on every successful lookup. Null when coordinates are unmapped.", "unix": "Seconds since 1970-01-01T00:00:00Z, rounded down. Both conversion zones have the same unix value. Null when coordinates are unmapped.", "deep": "With ?deep=true: { name, offset_minutes, offset_seconds } for the target zone. All plans." }, "headers": { "Content-Language": "Languages used by translated display labels and known English reference fallbacks; unchanged native place text is not assigned an inferred language" }, "localization": { "fields": [ "deep.name", "to.deep.name", "targets[].deep.name" ], "native_names": "Native names, registered/legal/person/provider names, addresses, codes, enums and numeric facts retain their existing values. Native-name equality is evaluated before lang is applied, so a preserved native name can equal the translated display name.", "selection": "Explicit lang only; Accept-Language does not select translations. Unknown languages or unsupported explicit scripts use English.", "source": "Existing ICU formatter with pinned timezone-rule verification" }, "data": { "timezone_database": "IANA", "timezone_database_version": "2026c", "next_transition_horizon_days": 400, "location_sources": { "city": "Existing ParseAPI City records", "ip": "Existing geofeed declarations or measured coordinates; estimated location", "address": "Existing US address points only", "airport": "Captured OurAirports points; individual source label appears in location.source", "unlocode": "Captured NGA World Port Index ports with usable codes; incomplete UN/LOCODE coverage", "country": "Country-specific IANA zone.tab choices from the serving edition" } }, "zones_response": { "timezone_database_version": "The actual pinned IANA rule edition used by Time; not a promise of live source refreshes", "timezones": "Serving timezone identifiers and aliases, sorted by identifier unless sort=offset is selected. Empty array when no matches. Always strings, including with details=true.", "at": "Present with details or time-dependent filters/sorting: one captured ISO UTC instant shared by all catalog rows.", "zones": "Only with details=true: rows aligned with timezones, each { timezone, countries, area, abbreviation, offset, offset_seconds, dst, observes_dst }. countries is a source-recorded ISO2 array; no association is []. area can be null. Observance uses the selected UTC calendar year." }, "resolution_response": { "kind": "unique, overlap, or gap, determined from the actual source timezone rules", "policy": "Applied compatible, earlier, later, or reject policy; omitted query uses compatible", "adjustment_seconds": "Signed resolved source wall time minus requested wall time in seconds. Zero for unique/overlap; negative when moving backward across a gap and positive when moving forward", "alternatives": "Empty array for unique input. Exactly two { at, unix, offset } objects ordered by instant for overlap/gap: earlier then later, preserving milliseconds in at. unix is integer seconds. The selected answer remains in source at and unix" }, "errors": { "ambiguous_time": "HTTP 400 when disambiguation=reject encounters a repeated wall time. Retry with an explicitly chosen earlier/later policy or UTC offset", "nonexistent_time": "HTTP 400 when disambiguation=reject encounters a skipped wall time. Retry with an explicitly chosen earlier/later policy or UTC offset", "invalid_request": "HTTP 400 for other invalid inputs; correct the input before retrying", "service_unavailable": "HTTP 503 when location data or required boundaries cannot be read; never reported as a not_found location verdict" }, "location_candidate_response": { "id": "Stable dataset ID when available, otherwise null", "name": "Source location label, or null", "country": "Recorded country code, or null", "state": "Public state code without a country prefix, or null", "timezone": "Supported IANA identifier from recorded evidence or exact available coordinates; null when unavailable", "latitude": "Recorded/mapped latitude, or null", "longitude": "Recorded/mapped longitude, or null" }, "agent": { "schema_version": "1.0.0", "api_version": "2.0.0", "operation": "time", "endpoint": "GET /time or /time/{timezone}", "determines": [ "Local ISO time, integer Unix seconds, UTC offset and the timezone-rule DST flag at one instant", "The same captured instant in one destination with to, or in 1–10 ordered destinations with targets", "With deep=true, friendly name, exact total and standard offsets, signed seasonal saving, the next offset change, full applicable seasonal boundaries, actual rule edition and source wall-time resolution", "Exact location evidence for explicit IP, city, country, airport, supported port or US address input, with ambiguity retained as candidates" ], "does_not_determine": [ "Future government rule changes or complete early historical records", "Clock synchronization accuracy or a latency-free current time", "A unique timezone from an abbreviation such as CST", "A precise or verified person/device location from IP evidence", "Postal-delivery validity, ownership, global address coverage or complete UN/LOCODE coverage" ], "required_context": [ "Choose one source: omitted timezone for UTC, IANA timezone, paired lat/lon, explicit IP, exact city/country/state, country alone, IATA/ICAO airport, covered UN/LOCODE port, or address with country=US", "at accepts an ISO date or timestamp with at most three fractional digits; omit it for now. Unix seconds are output, not input", "Without to or targets, offsetless at means UTC. With to or targets, it means source wall time", "disambiguation defaults to compatible: earlier occurrence on overlap, forward by the actual gap. earlier, later or reject apply only to offsetless conversion; an explicit offset identifies the instant", "targets is a comma-separated list of 1–10 IANA IDs, mutually exclusive with to. Duplicates remain ordered; any invalid target rejects the whole conversion", "For location.status=ambiguous, choose a returned candidate timezone or refine context. not_found and truncated results never guess a source instant. Airport/port codes and countries are explicit selectors, not arbitrary path identifiers." ], "freshness": { "mode": "computed_from_pinned_rules", "timezone_database": "IANA", "timezone_database_version": "2026c", "cache_control": "no-store", "next_transition_horizon_days": 400, "uniform_refresh_interval_seconds": null, "actual_age_seconds": null, "actual_age_status": "not_exposed; rule edition is pinned, current time is evaluated for each request", "answer_evidence": "deep.timezone_database_version binds a requested detailed answer to the bundled rule edition, independently of coordinate boundary and display-name data" }, "uncertainty": { "timezone": { "null": "Coordinates or explicit location input did not identify one usable timezone; clock facts and requested to/targets stay null" }, "dst": { "true": "The active timezone rule carries its DST indicator, including negative seasonal adjustments; not proof the offset is positive", "false": "The active timezone rule does not carry its DST indicator", "null": "Source timezone is unresolved" }, "deep.name": { "null": "Friendly display name unavailable or inconsistent with the pinned rule" }, "deep.next_dst": { "null": "No UTC offset change found within 400 days, or source timezone unresolved; not a promise of no future changes" }, "deep": { "omitted": "Not requested", "object": "Requested; optional detail is included on every plan" }, "http_status": { "400": "Invalid input, or a repeated/nonexistent source wall time with disambiguation=reject. Supply an explicit UTC offset or choose earlier/later", "404": "Unknown IANA timezone", "503": "Location store or required coordinate index unavailable; no negative location verdict" }, "targets": { "omitted": "Not requested", "null": "Source is unresolved or ambiguous; no target instant was guessed", "array": "Ordered requested target objects, including duplicates; all share the same captured instant" }, "deep.resolution": { "null": "Now, explicit-offset input, no conversion, or unresolved source; no wall-time ambiguity was evaluated", "object": "Actual unique/overlap/gap classification, applied policy, signed wall adjustment in seconds, and two chronological alternatives for overlap/gap (empty for unique)" }, "error_code": { "ambiguous_time": "HTTP 400: reject policy encountered repeated source wall time; choose earlier/later or an explicit offset", "nonexistent_time": "HTTP 400: reject policy encountered skipped source wall time; choose earlier/later or an explicit offset", "invalid_request": "HTTP 400: other invalid input; correct it before retrying" }, "location": { "omitted": "No explicit location selector was used", "resolved": "One usable location candidate selected", "ambiguous": "Multiple or truncated candidates; choose/refine explicitly", "not_found": "No usable match in the available data; not proof the place does not exist" }, "deep.season": { "null": "No current interval or next DST-flag interval starting within 400 days, or source unresolved", "object": "Current continuous DST-flag interval, otherwise the next beginning within 400 days; nullable start/end boundaries preserve limits", "endpoint_null": "Boundary absent from pinned rules or outside supported UTC years 0001 through 9999" } }, "billing": { "pooled_requests_per_success": 1, "metered": null, "deep_extra_units": 0, "conversion_extra_units": 0, "monetary_quote": null, "account_state": "unknown; pooled allowance and accepted account terms are not checked", "targets_extra_units": 0, "maximum_targets": 10 }, "access": { "api_key_required": true, "key_types": [ "secret", "public", "app" ], "key_fences": { "public": "Allowed browser origin required", "app": "Allowed X-App-Id required" }, "deep": { "entitlement": "Optional time detail on every plan" }, "effective_access": null, "effective_access_status": "not_checked; key fences, account access and quotas still apply" }, "retry": { "client": "javascript_sdk_and_mcp", "default_retries": 2, "retry_http_statuses": [ 429, 500, 502, 503, 504 ], "retry_network_errors": true, "successful_unknown_retried": false, "guidance": "Do not retry unresolved/ambiguous locations or rejected wall times automatically. Correct the input or choose a resolution. Retried calls with omitted at evaluate a later now; pin an explicit instant when repeatability matters." }, "docs": { "help": "https://api.parseapi.com/version/2.0.0/time/help", "guide": "https://parseapi.com/docs/time" } } }