Skip to content
Endpoint guide

Convert time

GET /v1/time/convertOpenAPI YAML

Convert one input timestamp into a target timezone, offset, IP, coordinate, or UTC. Supports bulk targets.

What do I need to send?

Required / choose this first

Send exactly one input (unix, unix_ms, or iso) and exactly one target (tz, ip, lat + lon, offset, or utc).

Optional

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.

NameNeeded?Use it for
unixChoose one inputInput timestamp as Unix seconds.
unix_msChoose one inputInput timestamp as Unix milliseconds.
isoChoose one inputInput timestamp as ISO 8601. May include offset (e.g. ...Z) or be local with a source_* hint.
source_tzConditional hintInterpret a local iso= as wall time in this IANA zone.
source_ipConditional hintInterpret local iso= using the timezone of this IP.
source_latPair parameterLatitude for local iso= zone resolution. Pair with source_lon.
source_lonPair parameterLongitude for local iso= zone resolution.
source_offsetConditional hintInterpret local iso= against a fixed UTC offset.
tzChoose one targetTarget IANA timezone. Comma-separated for bulk.
ipChoose one targetTarget via IP address. Comma-separated for bulk.
latPair parameterTarget latitude. Pair with lon.
lonPair parameterTarget longitude.
offsetChoose one targetTarget fixed UTC offset. URL-encode + as %2B. Comma-separated for bulk.
auto_tzChoose one targetSet true to target the request IP's timezone.
utcChoose one targetSet true to render the target in UTC (iso_local and timezone are then null).
formatOptionalstrftime pattern for the additional `formatted` field, e.g. %Y-%m-%d %H:%M:%S. Unsupported directives return 400; see /docs#selectors for the list.
signOptionalSet 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 malformed iso; a date that does not exist (2027-02-29); a local time inside a spring-forward gap (2026-03-08T02:30:00 with source_tz=America/New_York); or a value outside 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z (for example unix=99999999999999).
  • 400 MISSING_TARGET — no target selector / utc=true provided.
  • 400 AMBIGUOUS_TARGET — multiple input or target families combined, or a bulk selector mixed with another target (including utc=true).
  • 400 INVALID_PARAMETER — invalid timezone, offset, or unsupported strftime directive.
  • 404 NOT_FOUND — a target ip with 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.