Date Utils

Eight date and timezone utilities for AI agents: current date info, time zone conversion, working day checks, and meeting window finder.

⚡ 1 credit per call (2 for meeting-windows)

Try it

Fill in the fields below and hit Send.

API key

Save to this browser

Timezone (optional)

Why use this

Models don't have a reliable clock, and date arithmetic is error-prone. These utilities give agents accurate time data, timezone-aware conversions, and working day calculations without hallucination.

Endpoints

Endpoint	What it does	Credits
`POST /date-utils/today`	Current date, day, week, quarter, DST, next working day	1
`POST /date-utils/convert-time`	Convert a datetime between timezones	1
`POST /date-utils/is-working-day`	Check if a date is a working day in a country	1
`POST /date-utils/next-working-day`	Find next/previous working day from a date	1
`POST /date-utils/add-working-days`	Add N working days to a date	1
`POST /date-utils/count-working-days`	Count working days between two dates	1
`POST /date-utils/timezone-overlap`	Find overlapping working hours across timezones	1
`POST /date-utils/meeting-windows`	List working days across countries in a date range	2

`/date-utils/today`

Returns full context about the current date in a given timezone.

Request

Field	Type	Notes
`timezone`	string	Optional. IANA timezone (e.g. `Europe/Dublin`). Defaults to `UTC`.

Response fields

Field	Type	Notes
`date`	string	ISO 8601 date (`YYYY-MM-DD`)
`day_of_week`	string	Full day name
`timezone`	string	Timezone used
`utc_offset`	string	Offset string e.g. `+01:00`
`is_dst`	boolean	Whether DST is active
`working_day`	boolean	Whether today is a working day
`week_number`	number	ISO 8601 week number
`quarter`	number	Quarter (1–4)
`days_until_month_end`	number	Calendar days remaining in month
`days_until_quarter_end`	number	Calendar days remaining in quarter
`next_working_day`	string	Next working day date
`reason`	string	Why today is not a working day (if applicable)

`/date-utils/convert-time`

Convert a datetime from one timezone to another.

Request

Field	Type	Notes
`datetime`	string	Required. ISO 8601 datetime e.g. `2026-03-15T14:00:00`
`from_timezone`	string	Required. IANA timezone of the source
`to_timezone`	string	Required. IANA timezone of the target

Example

{
  "datetime": "2026-03-15T14:00:00",
  "from_timezone": "Europe/Dublin",
  "to_timezone": "America/New_York"
}

{
  "original": { "datetime": "2026-03-15T14:00:00", "timezone": "Europe/Dublin", "utc_offset": "+00:00", "is_dst": false },
  "converted": { "datetime": "2026-03-15T10:00:00", "timezone": "America/New_York", "utc_offset": "-04:00", "is_dst": true },
  "difference_minutes": -240
}

`/date-utils/is-working-day`

Check whether a specific date is a working day in a country.

Request

Field	Type	Notes
`date`	string	Required. `YYYY-MM-DD`
`country`	string	Optional. ISO 3166-1 alpha-2 country code (e.g. `IE`, `US`, `GB`). Omit to skip holiday checks.

Example

{ "date": "2026-03-17", "country": "IE" }

{ "date": "2026-03-17", "country": "IE", "working_day": false, "reason": "Saint Patrick's Day" }

`/date-utils/next-working-day`

Find the next (or previous) working day from a given date, optionally skipping country holidays.

Request

Field	Type	Notes
`date`	string	Required. `YYYY-MM-DD`
`country`	string	Optional. ISO 3166-1 alpha-2 country code.
`direction`	string	Optional. `"forward"` (default) or `"backward"`

Example

{ "date": "2026-03-15", "country": "IE" }

{
  "from_date": "2026-03-15",
  "direction": "forward",
  "next_working_day": "2026-03-16",
  "skipped": []
}

`/date-utils/add-working-days`

Add (or subtract) N working days to a date, respecting weekends and country holidays.

Request

Field	Type	Notes
`date`	string	Required. `YYYY-MM-DD`
`days`	number	Required. Number of working days to add (negative to subtract)
`country`	string	Optional. ISO 3166-1 alpha-2 country code.

Example

{ "date": "2026-03-15", "days": 5, "country": "IE" }

{
  "from_date": "2026-03-15",
  "days": 5,
  "country": "IE",
  "result_date": "2026-03-23",
  "working_days_added": 5,
  "calendar_days_elapsed": 8,
  "skipped_holidays": [
    { "date": "2026-03-17", "name": "Saint Patrick's Day" }
  ]
}

`/date-utils/count-working-days`

Count working days between two dates, optionally excluding country holidays.

Request

Field	Type	Notes
`start`	string	Required. `YYYY-MM-DD`
`end`	string	Required. `YYYY-MM-DD`
`country`	string	Optional. ISO 3166-1 alpha-2 country code.

Example

{ "start": "2026-03-15", "end": "2026-03-31", "country": "IE" }

{
  "start": "2026-03-15",
  "end": "2026-03-31",
  "country": "IE",
  "working_days": 11,
  "calendar_days": 17,
  "weekends_excluded": 5,
  "holidays_excluded": [
    { "date": "2026-03-17", "name": "Saint Patrick's Day" }
  ]
}

`/date-utils/timezone-overlap`

Find overlapping working hours (09:00–17:00 local) across a list of timezones for a given date.

Request

Field	Type	Notes
`timezones`	string[]	Required. List of IANA timezone identifiers
`date`	string	Optional. `YYYY-MM-DD`. Defaults to today (UTC).

Example

{ "timezones": ["Europe/Dublin", "America/New_York"], "date": "2026-03-15" }

{
  "date": "2026-03-15",
  "working_hours": { "start": "09:00", "end": "17:00" },
  "timezones": ["Europe/Dublin", "America/New_York"],
  "overlap_minutes": 240,
  "best_windows": [
    {
      "start_utc": "2026-03-15T13:00:00Z",
      "end_utc": "2026-03-15T17:00:00Z",
      "duration_minutes": 240,
      "local_times": [
        { "timezone": "Europe/Dublin", "start": "13:00", "end": "17:00" },
        { "timezone": "America/New_York", "start": "09:00", "end": "13:00" }
      ]
    }
  ]
}

`/date-utils/meeting-windows`

List all days in a date range and show whether each country considers it a working day. Useful for scheduling across countries. Costs 2 credits per call.

Request

Field	Type	Notes
`from_date`	string	Required. `YYYY-MM-DD`
`to_date`	string	Required. `YYYY-MM-DD`
`countries`	string[]	Required. ISO 3166-1 alpha-2 country codes

Example

{ "from_date": "2026-03-16", "to_date": "2026-03-20", "countries": ["IE", "US"] }

{
  "from_date": "2026-03-16",
  "to_date": "2026-03-20",
  "countries": ["IE", "US"],
  "windows": [
    { "date": "2026-03-16", "day_of_week": "Monday", "available_in_all": true, "availability": [
      { "country": "IE", "working_day": true },
      { "country": "US", "working_day": true }
    ]},
    { "date": "2026-03-17", "day_of_week": "Tuesday", "available_in_all": false, "availability": [
      { "country": "IE", "working_day": false, "reason": "Saint Patrick's Day" },
      { "country": "US", "working_day": true }
    ]}
  ]
}

Errors

All endpoints return 400 with no credit charge for validation errors:

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request body",
  "details": [{ "path": ["timezone"], "message": "Invalid timezone" }]
}

API Reference

Endpoint

POST https://api.lightningapi.tools/date-utils/today

Required headers

Authorization: Bearer <apiKey>
Content-Type: application/json

Example request

{
  "timezone": "Europe/Dublin"
}

Example response

{
  "date": "2026-03-15",
  "day_of_week": "Sunday",
  "timezone": "Europe/Dublin",
  "utc_offset": "+00:00",
  "is_dst": false,
  "working_day": false,
  "week_number": 11,
  "quarter": 1,
  "days_until_month_end": 16,
  "days_until_quarter_end": 16,
  "next_working_day": "2026-03-16",
  "reason": "Sunday"
}