Skip to content
TimeLogic API logoTimeLogic API
Sign in

Bulk time and timezone API guide: many zones in one request

Fetch the current time, or convert one timestamp, for up to 10 time zones, IPs or offsets in a single request, returned as an array in input order.

Updated

Short answer: put up to 10 comma-separated values in one selector family on /v1/time/current or /v1/time/convert. You get one array back, in the same order as your input.

curl "https://api.timelogicapi.com/v1/time/current?tz=Europe/Paris,Asia/Tokyo,America/New_York" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

When should I use bulk mode?

Use the bulk timezone API or bulk time conversion API when one operation needs several timezone, IP, or fixed-offset targets. /v1/time/current and /v1/time/convert accept a comma-separated list in one selector family and return an array in input order. Resolve city, country, or IP locations first when your application needs those selectors.

What do bulk requests look like?

Current time with several named zones:

GET /v1/time/current?tz=Europe/Paris,Asia/Tokyo,America/New_York

Conversion to several offsets:

GET /v1/time/convert?unix=1711300000&offset=-04:00,%2B00:00,%2B09:00

The input order is preserved in the response array, which lets a caller pair each result with the original selector without guessing how the service sorted the values.

What are the rules and limits?

  • Send at most 10 values per request; more returns 400 INVALID_PARAMETER.
  • A bulk call returns HTTP 200 even if some items fail. Failed items appear in place as { "item", "error", "request_id" }, so check each element.
  • Any comma, including a trailing one, makes the response an array.
  • Keep all values in one selector family. tz=a&ip=b is ambiguous and is rejected.
  • Use one timestamp input for bulk conversion; every returned item represents that same instant.
  • URL-encode a plus sign in fixed offsets as %2B.
  • /v1/time/clock is single-target only, so use the JSON endpoints for bulk work.
  • Keep the API key server-side even when the results are rendered in a browser application.

Related guides and documentation

Frequently asked questions

How many time zones can I request at once?

Up to 10 comma-separated values per request. Sending more returns 400 INVALID_PARAMETER.

What happens if one item in a bulk request fails?

The request still returns HTTP 200. The failed item appears in its place in the array as an object with item, error and request_id, so check each element.

Can I mix time zones and IP addresses in one bulk request?

No. Keep all values in one selector family; a request such as tz=a&ip=b is ambiguous and is rejected.

Is the order of results guaranteed?

Yes. The response array follows the order of the values you sent, so you can pair each result with its input.

Which endpoints support bulk mode?

/v1/time/current and /v1/time/convert. /v1/time/clock is single-target only.

Is there a batch timezone API for multiple time zones at once?

Yes. Bulk mode is a batch timezone API built into the normal endpoints: pass up to 10 comma-separated time zones, IP addresses or offsets to one selector on /v1/time/current or /v1/time/convert and get one array back, in input order.