Time

Resolve timezone information for a target

Resolves timezone metadata for a single target. Target selector rules: - Use exactly one selector family: `tz`, `ip`, `lat` + `lon`, or `offset`. - Bulk is not supported on this route. - `offset` queries return a specialized payload that includes `matching_zones` for the request-time offset match. Examples: - Single target: `/v1/timezone?tz=America/New_York` - Offset match: `/v1/timezone?offset=-04:00`

Method GET
Path /v1/timezone
Parameters 6
When to use it
  • Use timezone resolution when the main question is zone identity and metadata rather than the formatted current time.
  • It is the route that best exposes matching-zone behavior for offset-only lookups.
Request shape
  • Pass exactly one target selector family and let the route resolve the timezone metadata for that target.
Selector rules
  • The same one-family rule applies here.
  • Offset inputs may map to multiple zones, which is a feature of the data rather than an error in the route.
Parameters

tz

query Optional string

IANA timezone name. On bulk-capable routes, a comma-separated list enables bulk mode.

ip

query Optional string

IP address. On bulk-capable routes, a comma-separated list enables bulk mode.

lat

query Optional number:double

Latitude. Must be provided together with `lon`.

lon

query Optional number:double

Longitude. Must be provided together with `lat`.

offset

query Optional string

Fixed UTC offset in `+HH:MM` or `-HH:MM` format. On bulk-capable routes, a comma-separated list enables bulk mode.

sign

query Optional boolean

Set to `true` to ask the gateway to sign the final JSON response. Not supported on `/v1/time/clock`.

Response Example

Resolved timezone payload

{
  "unix": 1776274247,
  "unix_ms": 1776274247883,
  "utc": "2026-04-15T17:30:47Z",
  "iso_local": "2026-04-15T13:30:47-04:00",
  "rfc2822": "Wed, 15 Apr 2026 13:30:47 -0400",
  "human": "April 15, 2026, 1:30 PM America/New_York",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": "America/New_York",
  "offset": -240,
  "dst": true
}
Code Examples
curl --request GET \
  --url "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone?ip=8.8.8.8" \
  --header "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  --header "X-RapidAPI-Host: timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com"
const url = new URL("https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone");
const query = [
  ["ip", "8.8.8.8"]
];

for (const [key, value] of query) {
  url.searchParams.set(key, value);
}

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-RapidAPI-Key": process.env.TIMELOGIC_API_KEY,
    "X-RapidAPI-Host": "timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com",
  },
});

const body = await response.text();
console.log(body);
const url = new URL("https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone");
const query: Array<[string, string]> = [
  ["ip", "8.8.8.8"]
];

for (const [key, value] of query) {
  url.searchParams.set(key, value);
}

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-RapidAPI-Key": process.env.TIMELOGIC_API_KEY ?? "",
    "X-RapidAPI-Host": "timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com",
  },
});

const body = await response.text();
console.log(body);
import os
import requests

url = "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone"
params = {
    "ip": "8.8.8.8"
}
headers = {
    "X-RapidAPI-Key": os.environ["TIMELOGIC_API_KEY"],
    "X-RapidAPI-Host": "timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com",
}

response = requests.get(url, params=params, headers=headers, timeout=30)
print(response.text)
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone", nil)
	query := req.URL.Query()
	query.Set("ip", "8.8.8.8")
	req.URL.RawQuery = query.Encode()
	req.Header.Set("X-RapidAPI-Key", os.Getenv("TIMELOGIC_API_KEY"))
	req.Header.Set("X-RapidAPI-Host", "timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class TimeLogicExample {
  public static void main(String[] args) throws IOException, InterruptedException {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone?ip=8.8.8.8"))
      .header("X-RapidAPI-Key", System.getenv("TIMELOGIC_API_KEY"))
      .header("X-RapidAPI-Host", "timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com")
      .GET()
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program {
  static async Task Main() {
    using var client = new HttpClient();
    using var request = new HttpRequestMessage(HttpMethod.Get, "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone?ip=8.8.8.8");
    request.Headers.Add("X-RapidAPI-Key", Environment.GetEnvironmentVariable("TIMELOGIC_API_KEY"));
    request.Headers.Add("X-RapidAPI-Host", "timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com");

    using var response = await client.SendAsync(request);
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
  }
}
<?php
$url = "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone?ip=8.8.8.8";

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-RapidAPI-Key: " . getenv("TIMELOGIC_API_KEY"),
        "X-RapidAPI-Host: timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
require "net/http"
require "uri"

uri = URI("https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone")
params = {
  "ip" => "8.8.8.8"
}
uri.query = URI.encode_www_form(params)

request = Net::HTTP::Get.new(uri)
request["X-RapidAPI-Key"] = ENV.fetch("TIMELOGIC_API_KEY")
request["X-RapidAPI-Host"] = "timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body
import okhttp3.OkHttpClient
import okhttp3.Request

fun main() {
    val client = OkHttpClient()
    val request = Request.Builder()
        .url("https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/timezone?ip=8.8.8.8")
        .get()
        .addHeader("X-RapidAPI-Key", System.getenv("TIMELOGIC_API_KEY"))
        .addHeader("X-RapidAPI-Host", "timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com")
        .build()

    client.newCall(request).execute().use { response ->
        println(response.body?.string())
    }
}
Expand full detail

Response notes

  • Resolved zone metadata is the core payload, with special handling for offset-based matches.
  • This route pairs naturally with current time and DST routes when you need both identity and time state.

Common pitfalls

  • Do not collapse offset-based results into a single zone if the API returns multiple matches.
  • Do not infer permanent zone identity from transient user context such as IP unless that tradeoff is acceptable for the product.

Advanced notes

  • This is the strongest route for explaining the difference between offset equivalence and real timezone identity in the docs.

Responses

Status 200

Resolved timezone payload.

Resolved timezone payload
{
  "unix": 1776274247,
  "unix_ms": 1776274247883,
  "utc": "2026-04-15T17:30:47Z",
  "iso_local": "2026-04-15T13:30:47-04:00",
  "rfc2822": "Wed, 15 Apr 2026 13:30:47 -0400",
  "human": "April 15, 2026, 1:30 PM America/New_York",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": "America/New_York",
  "offset": -240,
  "dst": true
}
Offset match response with matching zones
{
  "unix": 1776274247,
  "unix_ms": 1776274247883,
  "utc": "2026-04-15T17:30:47Z",
  "iso_local": "2026-04-15T13:30:47-04:00",
  "rfc2822": "Wed, 15 Apr 2026 13:30:47 -0400",
  "human": "April 15, 2026, 1:30 PM UTC-04:00",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": null,
  "offset": -240,
  "dst": false,
  "matching_zones": [
    {
      "unix": 1776274247,
      "unix_ms": 1776274247883,
      "utc": "2026-04-15T17:30:47Z",
      "iso_local": "2026-04-15T13:30:47-04:00",
      "rfc2822": "Wed, 15 Apr 2026 13:30:47 -0400",
      "human": "April 15, 2026, 1:30 PM America/New_York",
      "day_number": 4,
      "day_short": "Wed",
      "day_full": "Wednesday",
      "timezone": "America/New_York",
      "offset": -240,
      "dst": true
    },
    {
      "unix": 1776274247,
      "unix_ms": 1776274247883,
      "utc": "2026-04-15T17:30:47Z",
      "iso_local": "2026-04-15T13:30:47-04:00",
      "rfc2822": "Wed, 15 Apr 2026 13:30:47 -0400",
      "human": "April 15, 2026, 1:30 PM America/Toronto",
      "day_number": 4,
      "day_short": "Wed",
      "day_full": "Wednesday",
      "timezone": "America/Toronto",
      "offset": -240,
      "dst": true
    }
  ]
}

Status 400

Invalid or ambiguous request parameters.

Generic invalid-parameter error
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid offset. Use +HH:MM or -HH:MM."
  },
  "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "timestamp": "2026-04-15T17:30:47.883Z"
}
Ambiguous target selector error
{
  "error": {
    "code": "AMBIGUOUS_TARGET",
    "message": "Ambiguous target selectors. Provide only one of tz, ip, lat/lon, or offset."
  },
  "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "timestamp": "2026-04-15T17:30:47.883Z"
}

Status 405

Only `GET` is supported.

Status 500

Internal server error, including signing failures.

Internal gateway or core failure
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error."
  },
  "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "timestamp": "2026-04-15T17:30:47.883Z"
}

Status 501

A required resolver or dependency is not configured or not ready.

Missing resolver binding
{
  "error": {
    "code": "DEPENDENCY_NOT_READY",
    "message": "Timezone resolver binding is not configured."
  },
  "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "timestamp": "2026-04-15T17:30:47.883Z"
}

Status 502

Gateway failed to forward the request to the core worker.

Core forwarding failure
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to forward request to core worker.",
    "details": {
      "cause": "upstream failure"
    }
  },
  "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "timestamp": "2026-04-15T17:30:47.883Z"
}

Related links

Selector families and target resolution

Choose one target strategy per request and keep that rule consistent across your integration.

Read concept

Timezone Lookup API by IANA zone, IP, coordinates, or offset

The strongest timezone APIs make input strategy and ambiguity handling clear before you ship.

Read guide

World Time API for production apps

How to evaluate a world time API when you need more than a bare UTC conversion utility.

Read guide