Sign in

DateDelta API Documentation

Integrate DateDelta's powerful date calculations into your applications with our RESTful API.

Getting Started

Base URL

https://datedelta.com/api

Headers

Content-Type: application/json

Authentication

The API supports both anonymous access and authenticated requests with API keys.

🔑 API Keys Now Available!

Create an API key in your dashboard to unlock premium features:

  • Up to 10,000 requests/day (vs 100/min for anonymous)
  • Customizable rate limits per key
  • Usage analytics and monitoring
  • Priority support
Get Your API Key
Quick Examples
Try these example requests to get started quickly

Calculate days between dates

POST
https://datedelta.com/api/calculate/date-difference

Add 30 days to a date

POST
https://datedelta.com/api/calculate/date-arithmetic

Get US holidays

GET
https://datedelta.com/api/holidays/us?year=2024

Calculate business days

POST
https://datedelta.com/api/calculate/business-days

Endpoints

Date Difference
POST
Calculate the difference between two dates
/api/calculate/date-difference

Basic Example

POST https://datedelta.com/api/calculate/date-difference
{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "includeEndDate": false
}

Include End Date

POST https://datedelta.com/api/calculate/date-difference
{
  "startDate": "2024-03-15",
  "endDate": "2024-03-20",
  "includeEndDate": true
}

Date-Time Format

POST https://datedelta.com/api/calculate/date-difference
{
  "startDate": "2024-01-01T09:00:00Z",
  "endDate": "2024-01-01T17:30:00Z",
  "includeEndDate": false
}
Date Arithmetic
POST
Add or subtract time units from a date
/api/calculate/date-arithmetic

Add Days

POST https://datedelta.com/api/calculate/date-arithmetic
{
  "date": "2024-01-01",
  "operation": "add",
  "value": 30,
  "unit": "days"
}

Subtract Months

POST https://datedelta.com/api/calculate/date-arithmetic
{
  "date": "2024-06-15",
  "operation": "subtract",
  "value": 3,
  "unit": "months"
}

Add Years

POST https://datedelta.com/api/calculate/date-arithmetic
{
  "date": "2024-02-29",
  "operation": "add",
  "value": 1,
  "unit": "years"
}
Business Days
POST
Calculate working days between dates
/api/calculate/business-days

With US Holidays

POST https://datedelta.com/api/calculate/business-days
{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "skipWeekends": true,
  "holidays": [
    {
      "date": "2024-01-01",
      "name": "New Year's Day",
      "type": "federal"
    },
    {
      "date": "2024-01-15",
      "name": "Martin Luther King Jr. Day",
      "type": "federal"
    }
  ]
}

Without Holidays

POST https://datedelta.com/api/calculate/business-days
{
  "startDate": "2024-03-01",
  "endDate": "2024-03-31",
  "skipWeekends": true,
  "holidays": []
}

Custom Weekend Days

POST https://datedelta.com/api/calculate/business-days
{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "skipWeekends": true,
  "weekendDays": [5, 6],
  "holidays": []
}
Batch Calculations
POST
Perform multiple calculations in a single request
/api/calculate/batch

Mixed Calculations

POST https://datedelta.com/api/calculate/batch
{
  "calculations": [
    {
      "type": "date-difference",
      "params": {
        "startDate": "2024-01-01",
        "endDate": "2024-12-31",
        "includeEndDate": false
      }
    },
    {
      "type": "date-arithmetic",
      "params": {
        "date": "2024-01-01",
        "operation": "add",
        "value": 30,
        "unit": "days"
      }
    }
  ]
}

Multiple Date Differences

POST https://datedelta.com/api/calculate/batch
{
  "calculations": [
    {
      "type": "date-difference",
      "params": {
        "startDate": "2024-01-01",
        "endDate": "2024-03-31"
      }
    },
    {
      "type": "date-difference",
      "params": {
        "startDate": "2024-04-01",
        "endDate": "2024-06-30"
      }
    },
    {
      "type": "date-difference",
      "params": {
        "startDate": "2024-07-01",
        "endDate": "2024-09-30"
      }
    }
  ]
}
Get Holidays
GET
Get holidays for a specific country and year
/api/holidays/[country]

US Holidays 2024

GET https://datedelta.com/api/holidays/us?year=2024

Current Year (Default)

GET https://datedelta.com/api/holidays/us

Future Year

GET https://datedelta.com/api/holidays/us?year=2025
Error Handling

All endpoints return errors in a consistent format:

{
  "success": false,
  "error": "Validation error",
  "details": [
    {
      "path": ["startDate"],
      "message": "Invalid date format"
    }
  ]
}
Rate Limiting

Current Limits

Anonymous Users

100 requests/min

Per IP address

API Key Holders

Customizable

Up to 10,000/day

Rate Limit Headers

Rate limit information is included in all API responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1672531200
Retry-After: 60 (when rate limited)

⚡ Need Higher Limits?

Create an API key in your dashboard to customize your rate limits. Contact support for enterprise-level limits.

Create API Key
Using API Keys

Authenticate your requests with an API key to unlock higher rate limits and track usage.

Authentication Methods

Header Authentication (Recommended)

curl -X POST https://datedelta.com/api/calculate/date-difference \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"startDate": "2024-01-01", "endDate": "2024-12-31"}'

Query Parameter (Alternative)

GET https://datedelta.com/api/holidays/us?year=2024&apiKey=your_api_key_here

🔐 Security Best Practices

  • Never expose your API key in client-side code
  • Use environment variables to store keys
  • Rotate keys regularly
  • Use header authentication over query parameters