Time

Calendar projection for a target instant

Returns calendar fields for an optional timestamp and target. 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` - if no input timestamp is provided, the request time is used Target selector forms: - `tz=America/New_York` - `ip=8.8.8.8` - `lat=40.7128&lon=-74.0060` - `offset=-04:00` Additional flags: - `week=true` adds `week_number` Incompatible combinations: - at most one input timestamp form - at most 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 not supported on this route Examples: - `/v1/time/calendar?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/London&week=true` - `/v1/time/calendar?unix=1711300000&offset=-04:00`

Method GET
Path /v1/time/calendar
Parameters 16
When to use it
  • Use calendar projection when you want structured calendar fields for a target instant rather than only a formatted timestamp.
  • It is helpful for week-based views, reporting, and scheduling UIs that need discrete calendar values.
Request shape
  • Pass one input timestamp form, then resolve the target with the same selector model used elsewhere in the API.
  • Enable the week flag when ISO week information matters to the consumer.
Selector rules
  • Selector rules stay identical to the other target-based routes.
  • If an ISO input lacks an explicit offset, provide the right source timezone context.
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.

format

query Optional string

Custom date/time format template.

week

query Optional boolean

See the public OpenAPI contract for this parameter.

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

Calendar projection with week number

{
  "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",
  "year": 2026,
  "month": 4,
  "month_name": "April",
  "day": 15,
  "week_number": 16
}
Code Examples
curl --request GET \
  --url "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/time/calendar?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&week=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/calendar");
const query = [
  ["iso", "2026-04-16T09:30:00"],
  ["source_tz", "America/Los_Angeles"],
  ["tz", "Europe/London"],
  ["week", "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/calendar");
const query: Array<[string, string]> = [
  ["iso", "2026-04-16T09:30:00"],
  ["source_tz", "America/Los_Angeles"],
  ["tz", "Europe/London"],
  ["week", "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/calendar"
params = {
    "iso": "2026-04-16T09:30:00",
    "source_tz": "America/Los_Angeles",
    "tz": "Europe/London",
    "week": "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/calendar", 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("week", "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/calendar?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&week=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/calendar?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&week=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/calendar?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&week=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/calendar")
params = {
  "iso" => "2026-04-16T09:30:00",
  "source_tz" => "America/Los_Angeles",
  "tz" => "Europe/London",
  "week" => "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/calendar?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&tz=Europe%2FLondon&week=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

  • This route focuses on derived calendar fields rather than only raw instant representation.
  • It still inherits the same canonical target behavior as the broader time payload model.

Common pitfalls

  • Do not reconstruct week logic in client code if the API can provide it explicitly.
  • Do not assume a rendered date string is enough when the consumer really needs structured fields.

Advanced notes

  • Calendar projection is especially useful after an add or convert workflow when the next consumer is UI or analytics logic.

Responses

Status 200

Calendar payload.

Calendar projection with week number
{
  "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",
  "year": 2026,
  "month": 4,
  "month_name": "April",
  "day": 15,
  "week_number": 16
}

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

UTC, Unix, and wall-clock timestamp conversion API

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

Read guide