Skip to content
Endpoint guide

Add to a timestamp

GET /v1/time/addOpenAPI YAML

Add days, hours, minutes, and seconds to a base timestamp. Modifiers may be negative.

What do I need to send?

Required / choose this first

Provide at least one modifier: days, hours, minutes, or seconds.

Optional

A base timestamp (unix, unix_ms, or iso) is optional; without one, the request time is used.

Rule: Use one base form and choose one target selector if you need a rendered timezone.

NameNeeded?Use it for
unixChoose one inputBase timestamp as Unix seconds. Defaults to current request time when omitted.
unix_msChoose one inputBase timestamp as Unix milliseconds.
isoChoose one inputBase timestamp as ISO 8601.
daysOptionalWhole days to add, each exactly 24 hours (86,400 seconds). Negative subtracts.
hoursOptionalHours to add. Negative subtracts.
minutesOptionalMinutes to add. Negative subtracts.
secondsOptionalSeconds to add. Negative subtracts.
source_tzConditional hintInterpret a local iso= base as wall time in this IANA zone.
source_ipConditional hintInterpret a local iso= base using this IP address timezone.
source_latPair parameterLatitude hint for local iso=. Pair with source_lon.
source_lonPair parameterLongitude hint for local iso=. Pair with source_lat.
source_offsetConditional hintInterpret a local iso= base against a fixed UTC offset.
tzChoose one targetRender the result in this IANA timezone.
ipChoose one targetRender the result in the timezone of this IP address.
latPair parameterTarget latitude. Pair with lon.
lonPair parameterTarget longitude. Pair with lat.
offsetChoose one targetRender the result against a fixed UTC offset (URL-encode + as %2B).
auto_tzChoose one targetSet true to render the result in the request IP's timezone.
utcChoose one targetSet true to render the target in UTC.
formatOptionalstrftime pattern for an additional `formatted` field, e.g. %Y-%m-%d %H:%M:%S.
signOptionalSet true for a signed response.

Code samples

Copy a request in your preferred language and replace YOUR_TIMELOGIC_API_KEY with your direct API key.

curl "https://api.timelogicapi.com/v1/time/add?unix=1711300000&days=3&hours=2" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

Example response

{
  "unix": 1711566400,
  "unix_ms": 1711566400000,
  "utc": "2024-03-27T19:06:40Z",
  "iso_local": null,
  "rfc2822": "Wed, 27 Mar 2024 19:06:40 +0000",
  "human": "March 27, 2024, 7:06 PM UTC",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": null
}
Additional endpoint notes
# Add 3 days and 2 hours to a Unix timestamp
https://api.timelogicapi.com/v1/time/add?unix=1711300000&days=3&hours=2

# Add 2h30m to an ISO timestamp
https://api.timelogicapi.com/v1/time/add?iso=2026-04-16T09:00:00Z&hours=2&minutes=30

# Subtract one day
https://api.timelogicapi.com/v1/time/add?unix=1711300000&days=-1

Provide at most one base form. With no base, the modifier is applied to the current request time. With no target selector the result is rendered in UTC with iso_local and timezone set to null, as in the sample above.

Units. Only days, hours, minutes and seconds exist. There are no weeks, months or years parameters, and unknown parameters are ignored rather than rejected, so weeks=1 returns the base time unchanged. Modifiers are added as exact durations: days=1 always adds 24 hours, so across a daylight-saving change the local wall-clock time shifts by an hour (in America/New_York, 09:00 on March 7, 2026 plus days=1 is 10:00 on March 8). This endpoint is not calendar-aware and does not skip weekends or holidays; it is not a business-day adder.

Range. The base and the result must both fall between 0001-01-01T00:00:00Z and 9999-12-31T23:59:59Z. A result outside that range returns 400 INVALID_PARAMETER ("The resulting timestamp is out of range. Supported range: …").

Common errors

  • 400 AMBIGUOUS_TARGET — multiple base forms supplied.
  • 400 INVALID_PARAMETER — non-integer modifier values, or a result outside the supported range.
  • 400 INVALID_TIMESTAMP — a malformed, nonexistent (2027-02-29) or out-of-range base timestamp.

When to use this endpoint

Use Add to a timestamp when you need deterministic date math around an input moment. Common use cases include trial expiration, reminder scheduling, countdown targets, and generating future or past timestamps from a known base.

Request model

Pass one base timestamp (unix, unix_ms, or iso) or omit it to use the current request time. Then provide any combination of days, hours, minutes, and seconds; negative values subtract time.

Date math guidance

Use this endpoint when you want server-side consistency across clients. Store machine-readable values such as unix_ms for comparisons, then display the returned ISO or human string in the user's target context.

Frequently asked questions

How do I add days to a date with an API?

Call GET /v1/time/add?unix=1711300000&days=3. Use negative values to subtract, and omit the base to start from the current request time.

Which units can I add?

days, hours, minutes and seconds. There are no weeks, months or years parameters.

Does adding a day respect daylight saving time?

Modifiers are exact durations: days=1 always adds 24 hours, so across a DST change the local wall-clock time shifts by an hour. The endpoint does not skip weekends or holidays.