Time

Add modifiers to a timestamp

Adds `seconds`, `minutes`, `hours`, and `days` to an optional base timestamp. 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 base timestamp defaults to the request time Modifiers: - `seconds=30` - `minutes=15` - `hours=2` - `days=7` 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: - 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/add?iso=2026-04-16T09:00:00&source_tz=America/New_York&days=1&tz=Europe/London` - `/v1/time/add?minutes=30&utc=true`

Method GET
Path /v1/time/add
Parameters 20
When to use it
  • Use add when you want the API to shift a timestamp by explicit modifiers and then resolve the result in a target context.
  • It is useful for countdowns, deadlines, follow-up scheduling, and test fixtures.
Request shape
  • Start from one input timestamp form, add the numeric modifiers you need, then optionally resolve the output target.
  • Timezone context rules for wall-clock ISO inputs are the same as conversion.
Selector rules
  • Target selectors are optional, but when used they still follow the one-family rule.
  • UTC forcing changes the rendered output, not how the modifiers are applied to the source instant.
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.

seconds

query Optional integer

See the public OpenAPI contract for this parameter.

minutes

query Optional integer

See the public OpenAPI contract for this parameter.

hours

query Optional integer

See the public OpenAPI contract for this parameter.

days

query Optional integer

See the public OpenAPI contract for this parameter.

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

Adjusted timestamp payload

{
  "unix": 1711386400,
  "unix_ms": 1711386400000,
  "utc": "2024-03-25T18:53:20Z",
  "iso_local": "2024-03-25T14:53:20-04:00",
  "rfc2822": "Mon, 25 Mar 2024 14:53:20 -0400",
  "human": "March 25, 2024, 2:53 PM America/New_York",
  "day_number": 2,
  "day_short": "Mon",
  "day_full": "Monday",
  "timezone": "America/New_York",
  "formatted": "2024-03-25 14:53"
}
Code Examples
curl --request GET \
  --url "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/time/add?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&days=3&hours=4&tz=Europe%2FLondon" \
  --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/add");
const query = [
  ["iso", "2026-04-16T09:30:00"],
  ["source_tz", "America/Los_Angeles"],
  ["days", "3"],
  ["hours", "4"],
  ["tz", "Europe/London"]
];

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/add");
const query: Array<[string, string]> = [
  ["iso", "2026-04-16T09:30:00"],
  ["source_tz", "America/Los_Angeles"],
  ["days", "3"],
  ["hours", "4"],
  ["tz", "Europe/London"]
];

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/add"
params = {
    "iso": "2026-04-16T09:30:00",
    "source_tz": "America/Los_Angeles",
    "days": "3",
    "hours": "4",
    "tz": "Europe/London"
}
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/add", nil)
	query := req.URL.Query()
	query.Set("iso", "2026-04-16T09:30:00")
	query.Set("source_tz", "America/Los_Angeles")
	query.Set("days", "3")
	query.Set("hours", "4")
	query.Set("tz", "Europe/London")
	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/add?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&days=3&hours=4&tz=Europe%2FLondon"))
      .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/add?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&days=3&hours=4&tz=Europe%2FLondon");
    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/add?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&days=3&hours=4&tz=Europe%2FLondon";

$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/add")
params = {
  "iso" => "2026-04-16T09:30:00",
  "source_tz" => "America/Los_Angeles",
  "days" => "3",
  "hours" => "4",
  "tz" => "Europe/London"
}
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/add?iso=2026-04-16T09%3A30%3A00&source_tz=America%2FLos_Angeles&days=3&hours=4&tz=Europe%2FLondon")
        .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 returned payload mirrors the canonical time shape after arithmetic is applied.
  • Formatting helps with display, but UTC and Unix fields remain the durable result.

Common pitfalls

  • Do not mix local wall-clock assumptions with missing source timezone context.
  • Do not bury arithmetic rules inside client code when the API can produce the same result directly.

Advanced notes

  • This route is a good companion to calendar projection when you need both a shifted instant and calendar fields for the result.

Responses

Status 200

Adjusted timestamp payload.

Adjusted timestamp payload
{
  "unix": 1711386400,
  "unix_ms": 1711386400000,
  "utc": "2024-03-25T18:53:20Z",
  "iso_local": "2024-03-25T14:53:20-04:00",
  "rfc2822": "Mon, 25 Mar 2024 14:53:20 -0400",
  "human": "March 25, 2024, 2:53 PM America/New_York",
  "day_number": 2,
  "day_short": "Mon",
  "day_full": "Monday",
  "timezone": "America/New_York",
  "formatted": "2024-03-25 14:53"
}

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