Time

Time elapsed since or remaining until a reference instant

Computes elapsed or remaining duration relative to one required reference timestamp. Reference 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` Compare timestamp forms: - `compare_unix=1711213600` - `compare_unix_ms=1711213600000` - `compare_iso=2026-04-16T09:00:00Z` - `compare_iso=2026-04-16T09:00:00&compare_source_tz=Europe/London` - `compare_iso=2026-04-16T09:00:00&compare_source_ip=8.8.8.8` - `compare_iso=2026-04-16T09:00:00&compare_source_lat=40.7128&compare_source_lon=-74.0060` - `compare_iso=2026-04-16T09:00:00&compare_source_offset=-05:00` Compare selector forms: - `tz=America/New_York` - `ip=8.8.8.8` - `lat=40.7128&lon=-74.0060` - `offset=-04:00` Incompatible combinations: - exactly one reference timestamp form - use either one compare timestamp form or one compare selector family, not both - use at most one of `source_tz`, `source_ip`, `source_lat`/`source_lon`, or `source_offset` - use at most one of `compare_source_tz`, `compare_source_ip`, `compare_source_lat`/`compare_source_lon`, or `compare_source_offset` - local-ISO companion selectors are valid only with `iso=...` that has no explicit offset - compare local-ISO companion selectors are valid only with `compare_iso=...` that has no explicit offset - if no compare input is provided, the comparison defaults to the request time Business-day rules: - `holiday_country` and `holiday_subdivision` require `business_days=true` - `holiday_subdivision` also requires `holiday_country` Examples: - Timestamp-to-timestamp: `/v1/time/elapsed?iso=2026-04-16T09:00:00&source_tz=America/New_York&compare_iso=2026-04-16T09:00:00&compare_source_tz=Europe/London` - Timestamp-to-selector: `/v1/time/elapsed?unix=1711300000&tz=America/New_York&business_days=true`

Method GET
Path /v1/time/elapsed
Parameters 26
When to use it
  • Use elapsed when you need time since or time until a reference instant, optionally relative to another explicit comparison instant.
  • It is especially useful for countdowns, SLA windows, planning tools, and business-day projections.
Request shape
  • Provide a base timestamp, then optionally provide comparison inputs and business-day modifiers.
  • When wall-clock ISO values omit offsets, the matching timezone context fields become important on both sides of the calculation.
Selector rules
  • Target selectors follow the same one-family rule used elsewhere in the API.
  • Business-day and holiday fields only matter when the corresponding mode is enabled.
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.

compare_unix

query Optional integer:int64

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

compare_unix_ms

query Optional integer:int64

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

compare_iso

query Optional string

ISO-8601 comparison timestamp. To supply a local wall-clock time without an explicit offset, pair it with one of `compare_source_tz=Area/City`, `compare_source_ip=...`, `compare_source_lat=...&compare_source_lon=...`, or `compare_source_offset=±HH:MM`.

compare_source_tz

query Optional string

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

compare_source_ip

query Optional string

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

compare_source_lat

query Optional number:double

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

compare_source_lon

query Optional number:double

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

compare_source_offset

query Optional string

Used only with `compare_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 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

Remaining duration with business-day count

{
  "seconds": 172800,
  "minutes": 2880,
  "hours": 48,
  "days": 2,
  "human": "2 days left",
  "direction": "left",
  "formatted": "2d 0h 0m 0s",
  "business_days": 2
}
Code Examples
curl --request GET \
  --url "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/time/elapsed?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FNew_York&compare_iso=2026-04-18T17%3A00%3A00&compare_source_tz=America%2FNew_York&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/elapsed");
const query = [
  ["iso", "2026-04-16T09:30:00"],
  ["source_tz", "America/New_York"],
  ["compare_iso", "2026-04-18T17:00:00"],
  ["compare_source_tz", "America/New_York"],
  ["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/elapsed");
const query: Array<[string, string]> = [
  ["iso", "2026-04-16T09:30:00"],
  ["source_tz", "America/New_York"],
  ["compare_iso", "2026-04-18T17:00:00"],
  ["compare_source_tz", "America/New_York"],
  ["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/elapsed"
params = {
    "iso": "2026-04-16T09:30:00",
    "source_tz": "America/New_York",
    "compare_iso": "2026-04-18T17:00:00",
    "compare_source_tz": "America/New_York",
    "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/elapsed", nil)
	query := req.URL.Query()
	query.Set("iso", "2026-04-16T09:30:00")
	query.Set("source_tz", "America/New_York")
	query.Set("compare_iso", "2026-04-18T17:00:00")
	query.Set("compare_source_tz", "America/New_York")
	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/elapsed?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FNew_York&compare_iso=2026-04-18T17%3A00%3A00&compare_source_tz=America%2FNew_York&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/elapsed?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FNew_York&compare_iso=2026-04-18T17%3A00%3A00&compare_source_tz=America%2FNew_York&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/elapsed?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FNew_York&compare_iso=2026-04-18T17%3A00%3A00&compare_source_tz=America%2FNew_York&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/elapsed")
params = {
  "iso" => "2026-04-16T09:30:00",
  "source_tz" => "America/New_York",
  "compare_iso" => "2026-04-18T17:00:00",
  "compare_source_tz" => "America/New_York",
  "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/elapsed?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FNew_York&compare_iso=2026-04-18T17%3A00%3A00&compare_source_tz=America%2FNew_York&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 response is duration-oriented and may indicate whether the target instant is still ahead or already passed.
  • Holiday-aware business-day output changes interpretation, so surface that clearly in downstream UX.

Common pitfalls

  • Do not enable holiday fields without also enabling business-day mode.
  • Do not assume `now` is always the right comparison baseline if your workflow needs a custom reference instant.

Advanced notes

  • Elapsed and diff overlap conceptually, but elapsed is the better fit when one side is naturally treated as a reference point in product language.

Responses

Status 200

Elapsed-duration result.

Remaining duration with business-day count
{
  "seconds": 172800,
  "minutes": 2880,
  "hours": 48,
  "days": 2,
  "human": "2 days left",
  "direction": "left",
  "formatted": "2d 0h 0m 0s",
  "business_days": 2
}

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