Time zone conversion API guide: convert timestamps between zones
Convert Unix seconds, milliseconds or ISO 8601 timestamps to any IANA zone, IP, coordinates or offset, with UTC, local ISO and RFC 2822 output.
Updated
Short answer: call GET /v1/time/convert with exactly one input timestamp (unix, unix_ms or iso) and one target (tz, ip, lat+lon, offset or utc=true). The response gives the same instant in the target zone as UTC, local ISO 8601, RFC 2822, Unix and calendar fields.
curl "https://api.timelogicapi.com/v1/time/convert?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/Paris" \
-H "Authorization: Bearer $TIMELOGIC_API_KEY"
How do I convert a timestamp between timezones?
Use /v1/time/convert as a time zone conversion API, date time conversion API, or UTC conversion API (a time zone converter API for your backend) with exactly one input form (unix, unix_ms, or iso) and one target selector such as tz, ip, lat plus lon, offset, or utc.
What are the input and target rules?
Provide exactly one input timestamp:
| Input | Meaning |
|---|---|
unix | Unix seconds. |
unix_ms | Unix milliseconds. |
iso | ISO 8601, with an offset or a source hint for a local wall time. |
Then provide exactly one target family: tz, ip, lat + lon, offset, or utc=true. Combining target families, or mixing utc=true with a bulk target, returns AMBIGUOUS_TARGET.
How do I convert a local time without an offset?
An ISO value such as 2026-04-16T09:00:00 has no offset. Tell the API how to interpret that wall time with one source hint:
GET /v1/time/convert?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/Paris
Use source_ip, source_lat + source_lon, or source_offset when those are the inputs available to your application. An ISO value with Z or an explicit numeric offset is already an instant and does not need a source hint.
Formatting, historical conversion, and date math
Use format for an additional strftime-style formatted field. Unix timestamp conversion and historical time conversion use the supplied instant rather than the current clock. The response preserves that instant and supplies UTC, local ISO, RFC 2822, Unix, and calendar fields. For date math and date arithmetic, use /v1/time/add, /v1/time/diff, or /v1/time/elapsed.
Can I convert to several zones in one request?
Send comma-separated targets within one selector family to receive an array in input order. Keep the input timestamp fixed and let the response provide the target timezone and local representation for each item. See the conversion endpoint documentation, bulk mode and the bulk time API guide.
Related guides and documentation
- World Time API guide: the current time instead of a supplied timestamp.
- Timezone API guide: resolve the target zone from an IP or coordinates.
- Daylight saving time API guide: DST status and transitions.
- Business days and holiday API guide: differences counted in working days.
- Docs: selectors and the convert endpoint reference.
- Code walkthroughs: JavaScript and Python.
Frequently asked questions
How do I convert a Unix timestamp to a time zone?
Call GET /v1/time/convert?unix=1711300000&tz=Europe/Paris with your API key. Use unix_ms for milliseconds. The response gives the same instant as UTC, local ISO 8601, RFC 2822, Unix and calendar fields for the target zone.
How do I convert a local time that has no offset?
Send the ISO wall time with a source hint, for example iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/Paris. An ISO value that ends in Z or carries a numeric offset is already an instant and needs no hint.
Can I convert one timestamp to several time zones at once?
Yes. Send comma-separated targets in one selector family, such as tz=Europe/Paris,Asia/Tokyo or offset=-04:00,%2B09:00. The response is an array in input order.
Does the conversion API handle historical dates?
Yes. Conversion uses the instant you supply, not the current clock, so historical time conversion applies the zone rules in force at that instant.
How do I add or subtract time or find the difference between dates?
Use /v1/time/add for date arithmetic, and /v1/time/diff or /v1/time/elapsed for differences between two moments.
Can the conversion API format dates with strftime?
Yes. Add format= with a URL-encoded strftime pattern, for example format=%25Y-%25m-%25d%20%25H:%25M, and the response gains a formatted field next to the standard ISO 8601, UTC and RFC 2822 values. An unsupported directive returns 400 INVALID_PARAMETER naming it.