Convert time
GET /v1/time/convertOpenAPI YAMLConvert one input timestamp into a target timezone, offset, IP, coordinate, or UTC. Supports bulk targets.
What do I need to send?
Send exactly one input (unix, unix_ms, or iso) and exactly one target (tz, ip, lat + lon, offset, or utc).
source_* fields explain a local ISO value; format and sign are optional.
Rule: Bulk conversion is available with one comma-separated tz, ip, or offset target.
| Name | Needed? | Use it for |
|---|---|---|
unix | Choose one input | Input timestamp as Unix seconds. |
unix_ms | Choose one input | Input timestamp as Unix milliseconds. |
iso | Choose one input | Input timestamp as ISO 8601. May include offset (e.g. ...Z) or be local with a source_* hint. |
source_tz | Conditional hint | Interpret a local iso= as wall time in this IANA zone. |
source_ip | Conditional hint | Interpret local iso= using the timezone of this IP. |
source_lat | Pair parameter | Latitude for local iso= zone resolution. Pair with source_lon. |
source_lon | Pair parameter | Longitude for local iso= zone resolution. |
source_offset | Conditional hint | Interpret local iso= against a fixed UTC offset. |
tz | Choose one target | Target IANA timezone. Comma-separated for bulk. |
ip | Choose one target | Target via IP address. Comma-separated for bulk. |
lat | Pair parameter | Target latitude. Pair with lon. |
lon | Pair parameter | Target longitude. |
offset | Choose one target | Target fixed UTC offset. URL-encode + as %2B. Comma-separated for bulk. |
auto_tz | Choose one target | Set true to target the request IP's timezone. |
utc | Choose one target | Set true to render the target in UTC (iso_local and timezone are then null). |
format | Optional | strftime pattern for the additional `formatted` field, e.g. %Y-%m-%d %H:%M:%S. Unsupported directives return 400; see /docs#selectors for the list. |
sign | Optional | Set true for a signed response. |
Code samples
Copy a request in your preferred language and replace YOUR_TIMELOGIC_API_KEY with your direct API key.
curl "https://api.timelogicapi.com/v1/time/convert?unix=1711300000&tz=Europe/London" \
-H "Authorization: Bearer $TIMELOGIC_API_KEY"Example response
{
"unix": 1711300000,
"unix_ms": 1711300000000,
"utc": "2024-03-24T17:06:40Z",
"iso_local": "2024-03-24T17:06:40+00:00",
"rfc2822": "Sun, 24 Mar 2024 17:06:40 +0000",
"human": "March 24, 2024, 5:06 PM Europe/London",
"day_number": 1,
"day_short": "Sun",
"day_full": "Sunday",
"timezone": "Europe/London"
}
Additional endpoint notes
Provide exactly one input timestamp form (unix, unix_ms, or iso) and exactly one target selector family.
# Numeric input → named zone
curl "https://api.timelogicapi.com/v1/time/convert?unix=1711300000&tz=Europe/London" \
-H "Authorization: Bearer $TIMELOGIC_API_KEY"
# Local ISO with source zone hint
https://api.timelogicapi.com/v1/time/convert?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/London
# Bulk targets — one comma-separated selector
https://api.timelogicapi.com/v1/time/convert?unix=1711300000&offset=-04:00,%2B00:00,%2B09:00
# strftime
https://api.timelogicapi.com/v1/time/convert?unix=1711300000&tz=Europe/London&format=%25Y-%25m-%25d%20%25H:%25M:%25S
# → adds "formatted": "2024-03-24 17:06:40"
Supported format directives: %a %A %b %B %C %d %D %e %F %h %H %I %j %k %l %m %M %n %p %P %r %R %s %S %t %T %u %v %w %x %X %y %Y %z %:z %Z %%, with the -, _ and 0 padding flags on numeric directives. %Z prints the IANA zone name (for example Europe/London), not an abbreviation. Anything else, such as %U, %f or %Q, returns 400 INVALID_PARAMETER naming the directive.
Bulk response: an array of payloads, one per target (up to 10), in input order. A target that fails appears in place as { "item", "error", "request_id" } and the response is still HTTP 200.
Common errors
400 INVALID_TIMESTAMP— no input timestamp provided; a malformediso; a date that does not exist (2027-02-29); a local time inside a spring-forward gap (2026-03-08T02:30:00withsource_tz=America/New_York); or a value outside0001-01-01T00:00:00Zto9999-12-31T23:59:59Z(for exampleunix=99999999999999).400 MISSING_TARGET— no target selector /utc=trueprovided.400 AMBIGUOUS_TARGET— multiple input or target families combined, or a bulk selector mixed with another target (includingutc=true).400 INVALID_PARAMETER— invalid timezone, offset, or unsupported strftime directive.404 NOT_FOUND— a targetipwith no timezone mapping.
When to use this endpoint
Use Convert time when you already have a source timestamp and need to project it into another timezone, fixed offset, IP-derived zone, coordinate-derived zone, or UTC. It is designed for meeting planners, notification systems, travel tools, and scheduling interfaces.
Request model
Provide exactly one input timestamp (unix, unix_ms, or iso). If an ISO value is a local wall time without an embedded offset, add one source hint such as source_tz so TimeLogic can interpret that wall time safely before converting it. Without a hint, a local ISO value is read as UTC. A wall time that occurs twice at a fall-back change (for example 2026-11-01T01:30:00 in America/New_York) resolves to the first occurrence (01:30 EDT); a wall time skipped at a spring-forward change returns 400 INVALID_TIMESTAMP. See Selectors for the accepted ISO shapes.
utc=true is a target of its own and cannot be combined with tz, ip, lat/lon, offset or auto_tz; the resulting 400 AMBIGUOUS_TARGET message lists only the five selector families. With utc=true, iso_local and timezone are null.
Bulk targets
Bulk conversion is useful for world clocks and availability screens. Send comma-separated target selectors in one target family to get an array of converted values in the same order as the input list.
Frequently asked questions
How do I convert a Unix timestamp to a time zone?
Call GET /v1/time/convert?unix=1711300000&tz=Europe/London. Send exactly one input form (unix, unix_ms or iso) and exactly one target.
How do I convert a local time from one zone to another?
Send the local wall time as iso= with source_tz= naming its zone, and the target as tz=, for example iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/London.
Can one request convert to several zones?
Yes. One comma-separated target selector with up to 10 values returns an array of results in input order.
Which strftime directives does format support?
The documented list on this page, with the -, _ and 0 padding flags on numeric directives. An unsupported directive returns 400 INVALID_PARAMETER naming it.