Time

Convert a timestamp into a target timezone or offset

Converts one required input timestamp into a single target or a bulk array. Input timestamp forms: - `unix=1711300000` - `unix_ms=1711300000000` - `iso=2026-04-16T09:00:00Z` - `iso=2026-04-16T09:00:00&source_tz=America/New_York` - `iso=2026-04-16T09:00:00&source_ip=8.8.8.8` - `iso=2026-04-16T09:00:00&source_lat=40.7128&source_lon=-74.0060` - `iso=2026-04-16T09:00:00&source_offset=-05:00` Target selector forms: - `tz=America/New_York` - `ip=8.8.8.8` - `lat=40.7128&lon=-74.0060` - `offset=-04:00` - `utc=true` Incompatible combinations: - exactly one input timestamp form - exactly one target selector family - use at most one of `source_tz`, `source_ip`, `source_lat`/`source_lon`, or `source_offset` - local-ISO companion selectors are valid only with `iso=...` that has no explicit offset - bulk is allowed only through one comma-separated `tz`, `ip`, or `offset` selector Examples: - Single target: `/v1/time/convert?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/London` - Bulk target set: `/v1/time/convert?unix=1711300000&offset=-04:00,+00:00,+09:00`

Method GET
Path /v1/time/convert
Parameters 16
When to use it
  • Use conversion when you already know the source instant and need the target rendered in another timezone or offset.
  • This is the route that most directly answers UTC, Unix, and wall-clock conversion workflows.
Request shape
  • Provide exactly one input timestamp form, then resolve the output target with a single selector family.
  • If an ISO input has no explicit offset, pass the matching source timezone field.
Selector rules
  • The target side follows the same selector family rules as the rest of the API.
  • Bulk output is available only on the routes that document it, including this one.
Parameters

unix

query Optional integer:int64

UNIX seconds timestamp. Constrained to the JavaScript `Date` safe range.

unix_ms

query Optional integer:int64

UNIX milliseconds timestamp. Constrained to the JavaScript `Date` safe range.

iso

query Optional string

ISO-8601 timestamp. To supply a local wall-clock time without an explicit offset, pair it with one of `source_tz=Area/City`, `source_ip=...`, `source_lat=...&source_lon=...`, or `source_offset=±HH:MM`.

source_tz

query Optional string

Used only with `iso=...` when the ISO value has no explicit offset.

source_ip

query Optional string

Used only with `iso=...` when the ISO value has no explicit offset. Resolves that local wall-clock time through the timezone mapped from this IP address.

source_lat

query Optional number:double

Used only with `iso=...` when the ISO value has no explicit offset. Provide together with `source_lon` to resolve that local wall-clock time through the timezone mapped from these coordinates.

source_lon

query Optional number:double

Used only with `iso=...` when the ISO value has no explicit offset. Provide together with `source_lat`.

source_offset

query Optional string

Used only with `iso=...` when the ISO value has no explicit offset. Interprets that local wall-clock time at this fixed UTC offset.

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.

utc

query Optional boolean

Set to `true` to force UTC on routes that support it.

format

query Optional string

Custom date/time format template.

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

Converted timestamp payload

{
  "unix": 1711300000,
  "unix_ms": 1711300000000,
  "utc": "2024-03-24T18:53:20Z",
  "iso_local": "2024-03-24T14:53:20-04:00",
  "rfc2822": "Sun, 24 Mar 2024 14:53:20 -0400",
  "human": "March 24, 2024, 2:53 PM America/New_York",
  "day_number": 1,
  "day_short": "Sun",
  "day_full": "Sunday",
  "timezone": "America/New_York",
  "formatted": "2024-03-24 14:53"
}
Code Examples
curl --request GET \
  --url "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/time/convert?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&format=%25Y-%25m-%25d+%25H%3A%25M" \
  --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/time/convert");
const query = [
  ["iso", "2026-04-16T09:30:00"],
  ["source_tz", "America/Los_Angeles"],
  ["tz", "Europe/London"],
  ["format", "%Y-%m-%d %H:%M"]
];

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/time/convert");
const query: Array<[string, string]> = [
  ["iso", "2026-04-16T09:30:00"],
  ["source_tz", "America/Los_Angeles"],
  ["tz", "Europe/London"],
  ["format", "%Y-%m-%d %H:%M"]
];

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/time/convert"
params = {
    "iso": "2026-04-16T09:30:00",
    "source_tz": "America/Los_Angeles",
    "tz": "Europe/London",
    "format": "%Y-%m-%d %H:%M"
}
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/time/convert", nil)
	query := req.URL.Query()
	query.Set("iso", "2026-04-16T09:30:00")
	query.Set("source_tz", "America/Los_Angeles")
	query.Set("tz", "Europe/London")
	query.Set("format", "%Y-%m-%d %H:%M")
	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/time/convert?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&format=%25Y-%25m-%25d+%25H%3A%25M"))
      .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/time/convert?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&format=%25Y-%25m-%25d+%25H%3A%25M");
    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/time/convert?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&format=%25Y-%25m-%25d+%25H%3A%25M";

$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/time/convert")
params = {
  "iso" => "2026-04-16T09:30:00",
  "source_tz" => "America/Los_Angeles",
  "tz" => "Europe/London",
  "format" => "%Y-%m-%d %H:%M"
}
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/time/convert?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&format=%25Y-%25m-%25d+%25H%3A%25M")
        .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

  • The route returns the converted instant in canonical forms plus optional display-oriented fields.
  • UTC forcing and custom formatting change presentation, not the underlying instant.

Common pitfalls

  • Do not omit source timezone context when sending a local wall-clock ISO value.
  • Do not confuse a formatted output string with the canonical timestamp fields.

Advanced notes

  • This route is one of the best places to demonstrate bulk target conversion in a single request.

Responses

Status 200

Converted time payload or bulk array.

Converted timestamp payload
{
  "unix": 1711300000,
  "unix_ms": 1711300000000,
  "utc": "2024-03-24T18:53:20Z",
  "iso_local": "2024-03-24T14:53:20-04:00",
  "rfc2822": "Sun, 24 Mar 2024 14:53:20 -0400",
  "human": "March 24, 2024, 2:53 PM America/New_York",
  "day_number": 1,
  "day_short": "Sun",
  "day_full": "Sunday",
  "timezone": "America/New_York",
  "formatted": "2024-03-24 14:53"
}
Bulk convert response
[
  {
    "unix": 1711300000,
    "unix_ms": 1711300000000,
    "utc": "2024-03-24T18:53:20Z",
    "iso_local": "2024-03-24T14:53:20-04:00",
    "rfc2822": "Sun, 24 Mar 2024 14:53:20 -0400",
    "human": "March 24, 2024, 2:53 PM America/New_York",
    "day_number": 1,
    "day_short": "Sun",
    "day_full": "Sunday",
    "timezone": "America/New_York"
  },
  {
    "unix": 1711300000,
    "unix_ms": 1711300000000,
    "utc": "2024-03-24T18:53:20Z",
    "iso_local": "2024-03-24T18:53:20+00:00",
    "rfc2822": "Sun, 24 Mar 2024 18:53:20 +0000",
    "human": "March 24, 2024, 6:53 PM UTC+00:00",
    "day_number": 1,
    "day_short": "Sun",
    "day_full": "Sunday",
    "timezone": null
  }
]
Bulk convert response with a per-item failure
[
  {
    "unix": 1711300000,
    "unix_ms": 1711300000000,
    "utc": "2024-03-24T18:53:20Z",
    "iso_local": "2024-03-24T14:53:20-04:00",
    "rfc2822": "Sun, 24 Mar 2024 14:53:20 -0400",
    "human": "March 24, 2024, 2:53 PM America/New_York",
    "day_number": 1,
    "day_short": "Sun",
    "day_full": "Sunday",
    "timezone": "America/New_York"
  },
  {
    "error": {
      "code": "INVALID_PARAMETER",
      "message": "Unsupported timezone identifier."
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "timestamp": "2026-04-15T17:30:47.883Z",
    "item": "Mars/Olympus"
  }
]

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

Bulk mode, partial failures, and error handling

Bulk mode is intentionally narrow, and per-item failures should be treated differently from request-level errors.

Read concept

UTC, Unix, and wall-clock timestamp conversion API

Conversion is where timestamp inputs, source timezone context, and formatting choices start to matter.

Read guide

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