Timezone API

The Timezone API by APIGrid is a managed timezone API designed to resolve timezone, daylight saving time (DST), local time conversion, schedule windows, business hours overlap, and timezone boundaries from coordinates, IP addresses, and city names.

This API provides rich timezone and time metadata in multiple formats, making it a powerful tool for developers building timezone lookup, DST detection, and timezone scheduling helpers.

Getting Started

To start using the Timezone API, you need to:

1. Obtain an API key from APIGrid.
2. Use the base URL: https://api.apigrid.net
3. Include your API key in the Authorization header as a Bearer token.

The API supports multiple endpoints for timezone lookup by coordinates, IP, city, and more, with responses including multiple time formats and DST information.

Authentication

All requests require an API key sent in the HTTP header:

Replace YOUR_API_KEY with your actual API key.

API Endpoints Reference

1. Resolve Timezone by Coordinates

GET /v1/timezone/lookup

Resolve a timezone from latitude and longitude coordinates and retrieve rich current time metadata including DST status and multiple time formats.

Query Parameters

2. IP Timezone Lookup

GET /v1/timezone/ip

Resolve timezone, local time, city, and country metadata from an IP address. If no IP is provided, the API falls back to the requester's IP.

Query Parameters

3. City Timezone Data Lookup

GET /v1/timezone/city

Resolve timezone and current local time by city name, with optional country narrowing to improve accuracy.

Query Parameters

4. Get Current Local Time in Multiple Formats

GET /v1/timezone/time/now

Return the current local time in multiple useful formats for any valid IANA timezone.

Query Parameters

5. Convert Local Time with DST Adjustments

GET /v1/timezone/time/convert

Interpret a local datetime in the source timezone and convert it into the destination timezone, accounting for daylight saving time changes.

Query Parameters

6. Check Business Hours Overlap

GET /v1/timezone/time/business-hours

Check whether a timezone is currently inside default business hours and return the evaluated local time.

Query Parameters

7. Calculate Business Hours Overlap Between Two Timezones

GET /v1/timezone/time/overlap

Calculate the current-day business-hours overlap between two real timezones, returning UTC and local windows.

Query Parameters

8. List All Supported Timezones

GET /v1/timezone/list

List all supported timezones with current offset, DST support, and current local time snapshots.

9. List Timezones by Country Code

GET /v1/timezone/list/country

List all timezones for a given two-letter ISO country code with current local time snapshots.

Query Parameters

10. Get Timezone Boundaries and Metadata

GET /v1/timezone/boundary

Return boundary GeoJSON for a timezone together with current timezone metadata.

Query Parameters

11. Optimize Schedule Windows Across Multiple Timezones

POST /v1/timezone/schedule/optimize

Recommend the best meeting windows across multiple timezones with rich UTC and local time views.

Request Body

Response Field Descriptions

• coordinates: Latitude and longitude of the resolved location.
• timezone:
  • id: IANA timezone identifier.
  • name: Common name of the timezone or city.
  • abbreviation: Current timezone abbreviation (e.g., BST).
  • offset: UTC offset in ±HH:mm format.
  • offsetMinutes: Offset in minutes from UTC.
  • isDstActive: Boolean indicating if daylight saving time is currently active.
  • dstObserved: Boolean indicating if the timezone observes DST at all.
• time:
  • iso8601: Time in ISO 8601 UTC format.
  • rfc3339: Time in RFC 3339 format with offset.
  • unix: Unix timestamp in seconds.
  • unixMs: Unix timestamp in milliseconds.
  • localDate: Local date in YYYY-MM-DD.
  • localTime24: Local time in 24-hour format HH:mm:ss.
  • localTime12: Local time in 12-hour format with AM/PM.
  • localDateTime: Local datetime in YYYY-MM-DDTHH:mm:ss.
  • weekday: Day of the week.
  • isWeekend: Boolean indicating if the day is a weekend.
  • weekendDays: Array of weekend days for the timezone.
  • dayPeriod: Part of the day (e.g., Morning, Afternoon).

Error Handling

The API returns standard HTTP status codes to indicate success or failure:

Best Practices

• Always cache timezone and DST results where possible to reduce API calls.
• Use the timezone lookup by coordinates or IP to resolve local time and DST info dynamically.
• Leverage the schedule windows API and business hours overlap calculation API to optimize meeting times across global teams.
• Use the timezone boundaries endpoint for geospatial applications requiring timezone overlap detection and boundary data.
• Validate input parameters strictly to avoid 400 errors.
• Monitor rate limits and implement exponential backoff on 429 responses.

Frequently Asked Questions (FAQ)

Q: How do I convert local time with the timezone API?
A: Use the /v1/timezone/time/convert endpoint by providing the source timezone, destination timezone, and the local datetime in the source timezone. The API handles DST adjustments automatically.

Q: Can I lookup timezone by coordinates and IP?
A: Yes, use /v1/timezone/lookup for coordinates timezone lookup and /v1/timezone/ip for IP timezone lookup.

Q: Does the API support DST detection and calculation?
A: Yes, every timezone response includes DST metadata such as isDstActive and dstObserved, making it a reliable DST API.

Q: How can I calculate business hours overlap across timezones?
A: Use the /v1/timezone/time/overlap endpoint to get current-day business-hours overlap between two timezones.

Q: Is there an API for timezone boundaries and schedule windows?
A: Yes, /v1/timezone/boundary returns timezone boundary GeoJSON, and /v1/timezone/schedule/optimize helps manage schedule windows across multiple timezones.

Q: Can I get multiple time formats from one API call?
A: Yes, all major endpoints return multiple time formats including ISO 8601, RFC 3339, Unix timestamps, and local time in 12- and 24-hour formats.