Time Addition API: Add or Subtract Time from Dates

Need to calculate future or past dates by adding or subtracting time? This guide covers date arithmetic using a REST API, including handling edge cases like month boundaries, leap years, and daylight saving time transitions.

What is Time Addition?

Time addition (or date arithmetic) is the process of adding or subtracting time units from a given date. This seems simple, but it gets complex when dealing with varying month lengths, leap years, and timezone transitions.

For example, adding 1 month to January 31st results in February 28th (or 29th in leap years), not an invalid February 31st.

Supported Time Units

The API supports adding or subtracting the following units:

• Years: Calendar years (accounts for leap years)
• Months: Calendar months (handles varying lengths)
• Weeks: 7-day periods
• Days: 24-hour periods
• Hours: 60-minute periods
• Minutes: 60-second periods
• Seconds: Individual seconds

Using the Time Addition API

TinyFn provides a flexible endpoint for time addition:

GET https://api.tinyfn.io/v1/time/add
Headers: X-API-Key: your-api-key

{
  "original": "2024-01-15T10:30:00.000Z",
  "result": "2024-02-15T10:30:00.000Z",
  "added": {
    "months": 1
  },
  "timezone": "UTC"
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/time/add?' + new URLSearchParams({
    date: '2024-01-15T10:00:00Z',
    months: 3,
    days: 15
  }),
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const result = await response.json();
console.log(result.result); // 2024-04-30T10:00:00.000Z

Python

import requests

response = requests.get(
    'https://api.tinyfn.io/v1/time/add',
    params={
        'date': '2024-01-15T10:00:00Z',
        'years': 1,
        'months': -6  # Subtract 6 months
    },
    headers={'X-API-Key': 'your-api-key'}
)
result = response.json()
print(result['result'])  # 2024-07-15T10:00:00.000Z

cURL

curl "https://api.tinyfn.io/v1/time/add?date=2024-01-15&days=30&hours=12" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Expiration Dates: Calculate subscription or trial expiration
• Due Dates: Set payment or delivery due dates
• Scheduling: Calculate future meeting or event times
• Reminders: Schedule notifications before events
• Date Ranges: Generate start and end dates for reports

Best Practices

1. Handle month boundaries: Be aware that adding months may adjust the day
2. Consider DST: Specify timezone for daylight saving time handling
3. Combine units carefully: Multiple units are applied in order (years, months, days, etc.)
4. Validate results: Check that the resulting date is valid for your use case