API

Timezone conversion and working days API

Convert time zones, count working days and find DST changes with a few plain HTTP calls.

Get an API key Talk to us

What it does

The Time & Timezone API does the date math that goes wrong in app code. Convert a moment between zones, show a world clock, add or subtract time, find the gap between two datetimes, count working days with public holidays, and look up when daylight saving starts and ends.
It solves the bugs that come from hand-rolled offsets: a meeting booked across a clock change, an SLA counted over a holiday, a report cut at the wrong hour. You send IANA zone names such as Europe/London and get offsets and DST flags back.
Two honest notes. Holidays come from a country-code holiday library, so check the countries you depend on. The business-hours endpoint returns a fixed Monday to Friday, 9 to 5 pattern adjusted for the zone, not your own opening hours.
Affordable by design. Start free* within platform limits for connected ShadowCradle organizations, with affordable pricing beyond that. *Free within platform limits; usage beyond limits may be charged to maintain the platform.

Example use cases

SLA clocks that skip weekends and holidays

Service teams call /time/working-days to count the business days between ticket open and due date.

Schedule across regions

An MSP with clients in several countries converts a maintenance window to each local time and checks whether DST starts that week.

Follow-the-sun dashboards

Ops teams show a world clock for each office from one call.

Product date features

Product teams add durations, show "in 3 days, 4 hours" text, and convert unix timestamps without writing zone code.

Check a DST change before a cutover

Ask for a zone's transitions for a year or a range and avoid planning around the missing hour.

Try it

Convert a time between zones

curl -s -X POST "https://app.takelan.com/api/v1/utils/timezone/convert" \
  -H "X-API-Key: $TAKELAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"datetime_value":"2027-03-27T09:00:00","source_timezone":"America/New_York","target_timezone":"Europe/London"}'

Response (trimmed, fictional): { "converted_datetime": "2027-03-27T13:00:00+00:00", "source_offset": "-04:00", "target_offset": "+00:00", "source_is_dst": true, "target_is_dst": false }

Count working days

curl -s -X POST "https://app.takelan.com/api/v1/utils/time/working-days" \
  -H "X-API-Key: $TAKELAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"start_date":"2027-12-20","end_date":"2028-01-05","country_code":"US"}'

end_date must be after start_date. Weekends and national holidays are excluded by default; both can be turned off.

Endpoints

GET /api/v1/utils/timezone Now: current time in a zone (query: timezone).
GET /api/v1/utils/time/now Now: current UTC time, unix timestamp and ISO string.
GET /api/v1/utils/time/unix/{timestamp} Now: turn a unix timestamp into a time in a zone.
POST /api/v1/utils/world-clock Now: current time in several zones.
POST /api/v1/utils/timezone/convert Convert: between two zones with offsets and DST flags.
POST /api/v1/utils/timezone/dst-transitions Convert: DST start and end for a year or range.
GET /api/v1/utils/timezone/business-hours/{timezone} Convert: standard Mon-Fri 9-5 hours with the zone offset.
GET /api/v1/utils/timezones Reference: all zone names.
GET /api/v1/utils/timezones/common Reference: common zones.
POST /api/v1/utils/time/calculate Math: difference between two datetimes in seconds up to years, plus readable text.
POST /api/v1/utils/time/add Math: add an amount of time to a datetime.
POST /api/v1/utils/time/working-days Math: working days between dates, weekends and holidays optional.
GET /api/v1/utils/calendar/days-in-month/{year}/{month} Calendar: days in a month.
GET /api/v1/utils/calendar/is-leap-year/{year} Calendar: leap-year check.

MCP

Available as tools through /mcp/utils. Read tools work by default with an API key. Anything that writes is off until your tenant turns on the writes switch, and a read-only key never writes. Calls run with your own permissions. These are all read-style calls, so they work without the writes switch. About MCP

Common questions

Is there an API to convert time between time zones?

Yes. POST to /api/v1/utils/timezone/convert with a datetime and two IANA zone names. You get both offsets and DST flags.

How do I calculate business days between two dates by API?

POST start and end dates and a country code to /api/v1/utils/time/working-days. Weekends and that country's public holidays are excluded unless you turn them off.

How do I find when daylight saving time starts?

POST a zone and a year, or a start and end year, to /api/v1/utils/timezone/dst-transitions.

Can I get the current time in many cities at once?

Yes. POST a list of zone names to /api/v1/utils/world-clock.

Can I set custom business hours?

No. The business-hours endpoint returns a fixed Monday to Friday, 9 to 5 pattern with the zone offset. Use working-days for day counts.

What happens with an invalid zone name?

You get a 400 or 422 with a message. Use /timezones to list valid names.

Which holiday calendars are supported?

Those in the holiday library for ISO two-letter country codes. Check the countries you need before relying on it for contracts.

Do I need a separate key?

No. It is the same X-API-Key or bearer token as the other Utils APIs.

All API families | Takelan Utilities & APIs | Pricing