Time

Difference between two instants

Computes the duration between `from` and `to`. `from` and `to` are embedded specifier strings. Accepted specifier forms: - `from=now` - `from=unix=1711300000` - `from=unix_ms=1711300000000` - `from=iso=2026-04-16T09:00:00` - `from=tz=America/New_York` - `from=ip=8.8.8.8` - `from=offset=-05:00` - the same forms are accepted for `to` Timezone hint pairings: - `from_tz` only with `from=iso=...` that has no explicit offset - `from_ip`, `from_lat`/`from_lon`, and `from_offset` only with `from=iso=...` that has no explicit offset - `to_tz` only with `to=iso=...` that has no explicit offset - `to_ip`, `to_lat`/`to_lon`, and `to_offset` only with `to=iso=...` that has no explicit offset Selector semantics: - `tz=...`, `ip=...`, and `offset=...` inside `from` or `to` mean the current request-time instant resolved through that selector - those selector forms do not represent an arbitrary local wall-clock time - returned duration magnitudes are absolute; use `direction` to see whether `to` is after, before, or the same instant as `from` Business-day rules: - `holiday_country` and `holiday_subdivision` require `business_days=true` - `holiday_subdivision` also requires `holiday_country` Examples: - Selector-current instant: `/v1/time/diff?from=unix=1711300000&to=tz=America/New_York` - Wall-clock pairing: `/v1/time/diff?from=iso=2026-04-16T09:00:00&from_tz=America/New_York&to=iso=2026-04-16T09:00:00&to_tz=Europe/London` - Wall-clock via selector: `/v1/time/diff?from=iso=2026-01-01T12:00:00&from_ip=8.8.8.8&to=iso=2026-01-01T12:00:00&to_offset=-05:00`

Method GET
Path /v1/time/diff
Parameters 17
When to use it
  • Use diff when you need the distance between two explicit instants rather than a relative now-to-target calculation.
  • It is the better fit for comparisons, scheduling offsets, and business-day interval analysis.
Request shape
  • Both ends of the calculation are passed as explicit time specifiers.
  • Timezone context fields are only needed when ISO wall-clock inputs omit explicit offsets.
Selector rules
  • Each side can use its own time specifier form, but each specifier still needs to be internally coherent.
  • Business-day mode is additive and only becomes holiday-aware when the calendar fields are also provided.
Parameters

from

query Required string

Time specifier. Supported forms are `now`, `unix=<seconds>`, `unix_ms=<milliseconds>`, `iso=<ISO-8601>`, `offset=±HH:MM`, `tz=<IANA timezone>`, and `ip=<IP address>`. For `tz=...`, `ip=...`, and `offset=...`, the specifier means the current request-time instant resolved through that selector. To express a local wall-clock time, use `from=iso=...` together with one of `from_tz`, `from_ip`, `from_lat`+`from_lon`, or `from_offset`.

to

query Required string

Time specifier. Supported forms are `now`, `unix=<seconds>`, `unix_ms=<milliseconds>`, `iso=<ISO-8601>`, `offset=±HH:MM`, `tz=<IANA timezone>`, and `ip=<IP address>`. For `tz=...`, `ip=...`, and `offset=...`, the specifier means the current request-time instant resolved through that selector. To express a local wall-clock time, use `to=iso=...` together with one of `to_tz`, `to_ip`, `to_lat`+`to_lon`, or `to_offset`.

from_tz

query Optional string

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

from_ip

query Optional string

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

from_lat

query Optional number:double

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

from_lon

query Optional number:double

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

from_offset

query Optional string

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

to_tz

query Optional string

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

to_ip

query Optional string

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

to_lat

query Optional number:double

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

to_lon

query Optional number:double

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

to_offset

query Optional string

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

format

query Optional string

Custom duration format template using `%days`, `%hours`, `%minutes`, and `%seconds`.

business_days

query Optional boolean

Set to `true` to enable weekday/business-day counting.

holiday_country

query Optional string

ISO 3166-1 alpha-2 holiday calendar country code. Requires `business_days=true`.

holiday_subdivision

query Optional string

Holiday calendar subdivision code from the upstream `python-holidays` calendar, for example `CA` or `ENG`. Requires `holiday_country` and `business_days=true`.

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

Duration between two instants

{
  "seconds": 3600,
  "minutes": 60,
  "hours": 1,
  "days": 0,
  "direction": "forward",
  "human": "1 hour",
  "formatted": "1h 0m 0s",
  "business_days": 0,
  "from": {
    "unix_ms": 1711300000000
  },
  "to": {
    "unix_ms": 1711303600000
  }
}
Code Examples
curl --request GET \
  --url "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/time/diff?from=iso%3D2026-04-16T09%3A30%3A00&from_tz=America%2FLos_Angeles&to=tz%3DEurope%2FLondon&business_days=true&holiday_country=US" \
  --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/diff");
const query = [
  ["from", "iso=2026-04-16T09:30:00"],
  ["from_tz", "America/Los_Angeles"],
  ["to", "tz=Europe/London"],
  ["business_days", "true"],
  ["holiday_country", "US"]
];

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/diff");
const query: Array<[string, string]> = [
  ["from", "iso=2026-04-16T09:30:00"],
  ["from_tz", "America/Los_Angeles"],
  ["to", "tz=Europe/London"],
  ["business_days", "true"],
  ["holiday_country", "US"]
];

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/diff"
params = {
    "from": "iso=2026-04-16T09:30:00",
    "from_tz": "America/Los_Angeles",
    "to": "tz=Europe/London",
    "business_days": "true",
    "holiday_country": "US"
}
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/diff", nil)
	query := req.URL.Query()
	query.Set("from", "iso=2026-04-16T09:30:00")
	query.Set("from_tz", "America/Los_Angeles")
	query.Set("to", "tz=Europe/London")
	query.Set("business_days", "true")
	query.Set("holiday_country", "US")
	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/diff?from=iso%3D2026-04-16T09%3A30%3A00&from_tz=America%2FLos_Angeles&to=tz%3DEurope%2FLondon&business_days=true&holiday_country=US"))
      .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/diff?from=iso%3D2026-04-16T09%3A30%3A00&from_tz=America%2FLos_Angeles&to=tz%3DEurope%2FLondon&business_days=true&holiday_country=US");
    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/diff?from=iso%3D2026-04-16T09%3A30%3A00&from_tz=America%2FLos_Angeles&to=tz%3DEurope%2FLondon&business_days=true&holiday_country=US";

$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/diff")
params = {
  "from" => "iso=2026-04-16T09:30:00",
  "from_tz" => "America/Los_Angeles",
  "to" => "tz=Europe/London",
  "business_days" => "true",
  "holiday_country" => "US"
}
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/diff?from=iso%3D2026-04-16T09%3A30%3A00&from_tz=America%2FLos_Angeles&to=tz%3DEurope%2FLondon&business_days=true&holiday_country=US")
        .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 duration-oriented data rather than a resolved time payload.
  • Formatting can shape the output string while numeric fields remain the durable values.

Common pitfalls

  • Do not turn on business-day counting without deciding whether holiday calendars matter to your use case.
  • Do not confuse local wall-clock comparison with exact instant comparison.

Advanced notes

  • Holiday subdivision support can materially change business-day output for regional workflows.

Responses

Status 200

Duration result.

Duration between two instants
{
  "seconds": 3600,
  "minutes": 60,
  "hours": 1,
  "days": 0,
  "direction": "forward",
  "human": "1 hour",
  "formatted": "1h 0m 0s",
  "business_days": 0,
  "from": {
    "unix_ms": 1711300000000
  },
  "to": {
    "unix_ms": 1711303600000
  }
}

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

DST and business-day calculations API

Daylight-saving changes and business-day logic are where time APIs stop being trivial utilities.

Read guide