Add to a timestamp
GET /v1/time/addOpenAPI YAMLAdd days, hours, minutes, and seconds to a base timestamp. Modifiers may be negative.
What do I need to send?
Provide at least one modifier: days, hours, minutes, or seconds.
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.
| Name | Needed? | Use it for |
|---|---|---|
unix | Choose one input | Base timestamp as Unix seconds. Defaults to current request time when omitted. |
unix_ms | Choose one input | Base timestamp as Unix milliseconds. |
iso | Choose one input | Base timestamp as ISO 8601. |
days | Optional | Whole days to add, each exactly 24 hours (86,400 seconds). Negative subtracts. |
hours | Optional | Hours to add. Negative subtracts. |
minutes | Optional | Minutes to add. Negative subtracts. |
seconds | Optional | Seconds to add. Negative subtracts. |
source_tz | Conditional hint | Interpret a local iso= base as wall time in this IANA zone. |
source_ip | Conditional hint | Interpret a local iso= base using this IP address timezone. |
source_lat | Pair parameter | Latitude hint for local iso=. Pair with source_lon. |
source_lon | Pair parameter | Longitude hint for local iso=. Pair with source_lat. |
source_offset | Conditional hint | Interpret a local iso= base against a fixed UTC offset. |
tz | Choose one target | Render the result in this IANA timezone. |
ip | Choose one target | Render the result in the timezone of this IP address. |
lat | Pair parameter | Target latitude. Pair with lon. |
lon | Pair parameter | Target longitude. Pair with lat. |
offset | Choose one target | Render the result against a fixed UTC offset (URL-encode + as %2B). |
auto_tz | Choose one target | Set true to render the result in the request IP's timezone. |
utc | Choose one target | Set true to render the target in UTC. |
format | Optional | strftime pattern for an additional `formatted` field, e.g. %Y-%m-%d %H:%M:%S. |
sign | Optional | Set 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.