Time

Get the current time for a target

Returns current time data for a single target, or a bulk array when exactly one of `tz`, `ip`, or `offset` is supplied as a comma-separated list. Target selector rules: - Use at most one selector family per request: `tz`, `ip`, `lat` + `lon`, `offset`. - If no selector is provided, the response defaults to UTC with `timezone=null` and `iso_local=null`. - Bulk mode is available only through one comma-separated `tz`, `ip`, or `offset` selector and cannot be combined with any other selector. Example: - Single target: `/v1/time/current?tz=America/New_York` - For bulk, provide one comma-separated `tz`, `ip`, or `offset` value, for example `/v1/time/current?tz=America/New_York,Europe/London,Asia/Tokyo`.

Method GET
Path /v1/time/current
Parameters 7
When to use it
  • Use this route to validate selector resolution and inspect the canonical single-target time payload.
  • It is also the simplest way to compare multiple supported locations in bulk mode.
Request shape
  • Pass one selector family per request: timezone, IP, coordinates, or fixed offset.
  • Optional formatting and signing behavior sit on top of the target selection.
Selector rules
  • Bulk mode only applies when a supported selector is passed as a comma-separated list.
  • Do not mix selector families in the same request.
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.

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

Single-target time 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",
  "formatted": "2026-04-15 13:30"
}
Code Examples
curl --request GET \
  --url "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/time/current?tz=America%2FNew_York&format=%25Y-%25m-%25d+%25H%3A%25M&sign=true" \
  --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/current");
const query = [
  ["tz", "America/New_York"],
  ["format", "%Y-%m-%d %H:%M"],
  ["sign", "true"]
];

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/current");
const query: Array<[string, string]> = [
  ["tz", "America/New_York"],
  ["format", "%Y-%m-%d %H:%M"],
  ["sign", "true"]
];

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/current"
params = {
    "tz": "America/New_York",
    "format": "%Y-%m-%d %H:%M",
    "sign": "true"
}
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/current", nil)
	query := req.URL.Query()
	query.Set("tz", "America/New_York")
	query.Set("format", "%Y-%m-%d %H:%M")
	query.Set("sign", "true")
	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/current?tz=America%2FNew_York&format=%25Y-%25m-%25d+%25H%3A%25M&sign=true"))
      .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/current?tz=America%2FNew_York&format=%25Y-%25m-%25d+%25H%3A%25M&sign=true");
    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/current?tz=America%2FNew_York&format=%25Y-%25m-%25d+%25H%3A%25M&sign=true";

$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/current")
params = {
  "tz" => "America/New_York",
  "format" => "%Y-%m-%d %H:%M",
  "sign" => "true"
}
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/current?tz=America%2FNew_York&format=%25Y-%25m-%25d+%25H%3A%25M&sign=true")
        .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

  • Successful responses include canonical time fields plus human-readable display fields.
  • Bulk responses may include per-item errors inside the returned array.

Common pitfalls

  • Do not parse the `human` field as if it were a stable machine contract.
  • Do not assume bulk mode exists just because a selector can accept lists on this route.

Advanced notes

  • Signed responses are useful when current time results are being cached or forwarded into other trust boundaries.

Responses

Status 200

Current time payload or bulk array.

Single-target time 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",
  "formatted": "2026-04-15 13:30"
}
Bulk current-time response
[
  {
    "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"
  },
  {
    "unix": 1776274247,
    "unix_ms": 1776274247883,
    "utc": "2026-04-15T17:30:47Z",
    "iso_local": "2026-04-15T18:30:47+01:00",
    "rfc2822": "Wed, 15 Apr 2026 18:30:47 +0100",
    "human": "April 15, 2026, 6:30 PM Europe/London",
    "day_number": 4,
    "day_short": "Wed",
    "day_full": "Wednesday",
    "timezone": "Europe/London"
  }
]
Bulk current-time response with a per-item failure
[
  {
    "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"
  },
  {
    "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

Signed JSON responses and verification

Signing is optional, explicit, and documented as a verification workflow rather than a generic response flag.

Read concept

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

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