Time Zone API Documentation
Date, Time and Time Zone API
Time zone API provides current time, date, and time zone related information. It can be consumed with the following input variations:
- For a Time Zone Name
- For any Address (preferrably, city address)
- For Location Coordinates (latitude & longitude)
- For any IP address
- For any IATA code
- For any ICAO code
- For any UN/LO Code
In each variation of the time zone API, time zone response remains same. Alongside this geolocation information is provided for IP address and location address search, airport details are provided for IATA code and ICAO code search, and city details are provided for UN/LO code search. Here are the details to consume each variation of the time zone API.
Note: In all examples below, we used API Key everywhere. Time zone API can be called from client side JavaScript with Request Origin authentication as well on only paid plans.
Time Zone Information from a Time Zone Name
You can pass a valid time zone name as a query parameter tz to get the time zone information. Here is an example to get 'America/Los_Angeles' timezone information:
Response
1{
2 "time_zone": {
3 "name": "America/Los_Angeles",
4 "offset": -8,
5 "offset_with_dst": -7,
6 "date": "2025-04-24",
7 "date_time": "2025-04-24 11:30:12",
8 "date_time_txt": "Thursday, April 24, 2025 11:30:12",
9 "date_time_wti": "Thu, 24 Apr 2025 11:30:12 -0700",
10 "date_time_ymd": "2025-04-24T11:30:12-0700",
11 "date_time_unix": 1745519412.353,
12 "time_24": "11:30:12",
13 "time_12": "11:30:12 AM",
14 "week": 17,
15 "month": 4,
16 "year": 2025,
17 "year_abbr": "25",
18 "is_dst": true,
19 "dst_savings": 1,
20 "dst_exists": true,
21 "dst_start": {
22 "utc_time": "2025-03-09 TIME 10",
23 "duration": "+1H",
24 "gap": true,
25 "date_time_after": "2025-03-09 TIME 03",
26 "date_time_before": "2025-03-09 TIME 02",
27 "overlap": false
28 },
29 "dst_end": {
30 "utc_time": "2025-11-02 TIME 09",
31 "duration": "-1H",
32 "gap": false,
33 "date_time_after": "2025-11-02 TIME 01",
34 "date_time_before": "2025-11-02 TIME 02",
35 "overlap": true
36 }
37 }
38}Time Zone Information from any Address
You can pass any address of a location as the query parameter location to get the time zone information. Here is an example to get the time zone information for the address 'London, UK':
Response
1{
2 "location": {
3 "location_string": "London, UK",
4 "country_name": "United Kingdom",
5 "state_prov": "England",
6 "city": "London",
7 "locality": "",
8 "latitude": "51.50002",
9 "longitude": "-0.19244"
10 },
11 "time_zone": {
12 "name": "Europe/London",
13 "offset": 0,
14 "offset_with_dst": 1,
15 "date": "2025-04-24",
16 "date_time": "2025-04-24 19:31:42",
17 "date_time_txt": "Thursday, April 24, 2025 19:31:42",
18 "date_time_wti": "Thu, 24 Apr 2025 19:31:42 +0100",
19 "date_time_ymd": "2025-04-24T19:31:42+0100",
20 "date_time_unix": 1745519502.723,
21 "time_24": "19:31:42",
22 "time_12": "07:31:42 PM",
23 "week": 17,
24 "month": 4,
25 "year": 2025,
26 "year_abbr": "25",
27 "is_dst": true,
28 "dst_savings": 1,
29 "dst_exists": true,
30 "dst_start": {
31 "utc_time": "2025-03-30 TIME 01",
32 "duration": "+1H",
33 "gap": true,
34 "date_time_after": "2025-03-30 TIME 02",
35 "date_time_before": "2025-03-30 TIME 01",
36 "overlap": false
37 },
38 "dst_end": {
39 "utc_time": "2025-10-26 TIME 01",
40 "duration": "-1H",
41 "gap": false,
42 "date_time_after": "2025-10-26 TIME 01",
43 "date_time_before": "2025-10-26 TIME 02",
44 "overlap": true
45 }
46 }
47}Time Zone Information from Location Coordinates
You can pass the latitude and longitude of a location as query parameters lat and long to get the time zone information. Here is an example to get time zone information for '-27.4748, 153.017' coordinates:
Response
1{
2 "time_zone": {
3 "name": "Australia/Brisbane",
4 "offset": 10,
5 "offset_with_dst": 10,
6 "date": "2025-04-25",
7 "date_time": "2025-04-25 04:33:10",
8 "date_time_txt": "Friday, April 25, 2025 04:33:10",
9 "date_time_wti": "Fri, 25 Apr 2025 04:33:10 +1000",
10 "date_time_ymd": "2025-04-25T04:33:10+1000",
11 "date_time_unix": 1745519590.635,
12 "time_24": "04:33:10",
13 "time_12": "04:33:10 AM",
14 "week": 17,
15 "month": 4,
16 "year": 2025,
17 "year_abbr": "25",
18 "is_dst": false,
19 "dst_savings": 0,
20 "dst_exists": false,
21 "dst_start": {},
22 "dst_end": {}
23 }
24}IP to Time Zone
You can pass any IPv4 or IPv6 address as a query parameter ip to get the regional timezone information. Here is an example to get the time zone information for the IP address '1.1.1.1':
Response
1{
2 "ip": "1.1.1.1",
3 "location": {
4 "continent_code": "OC",
5 "continent_name": "Oceania",
6 "country_code2": "AU",
7 "country_code3": "AUS",
8 "country_name": "Australia",
9 "country_name_official": "Commonwealth of Australia",
10 "is_eu": false,
11 "state_prov": "Queensland",
12 "state_code": "AU-QLD",
13 "district": "Brisbane",
14 "city": "South Brisbane",
15 "zipcode": "4101",
16 "latitude": "-27.47306",
17 "longitude": "153.01421"
18 },
19 "time_zone": {
20 "name": "Australia/Brisbane",
21 "offset": 10,
22 "offset_with_dst": 10,
23 "date": "2025-04-25",
24 "date_time": "2025-04-25 05:19:02",
25 "date_time_txt": "Friday, April 25, 2025 05:19:02",
26 "date_time_wti": "Fri, 25 Apr 2025 05:19:02 +1000",
27 "date_time_ymd": "2025-04-25T05:19:02+1000",
28 "date_time_unix": 1745522342.084,
29 "time_24": "05:19:02",
30 "time_12": "05:19:02 AM",
31 "week": 17,
32 "month": 4,
33 "year": 2025,
34 "year_abbr": "25",
35 "is_dst": false,
36 "dst_savings": 0,
37 "dst_exists": false,
38 "dst_start": {},
39 "dst_end": {}
40 }
41}Note: When you get the time zone information through an IP address, API will also return the 'location' field along with the time zone information.
Using Client or Machine IP Address
You can call the time zone API without passing any time zone, coordinates, IATA, ICAO, LO code or IP address as well. It will use the calling machine's IP address to return the regional time zone information. Here is an example:
This variation is widely used on embedded hardware and IoT devices to get current time after reboot.
Time Zone and Airport Details from IATA Code
We can pass any 3 letter IATA code as a query paramter iata_code to get the comprehensive airport details along with the time zone information, in which that airport exists. Here is an example to get the airport details about the IATA code 'DXB':
Response
1{
2 "airport_details": {
3 "type": "large_airport",
4 "name": "Dubai International Airport",
5 "latitude": "25.25280",
6 "longitude": "55.36440",
7 "elevation_ft": 62,
8 "continent_code": "AS",
9 "country_code": "AE",
10 "state_code": "AE-DU",
11 "city": "Dubai",
12 "iata_code": "DXB",
13 "icao_code": "OMDB",
14 "faa_code": ""
15 },
16 "time_zone": {
17 "name": "Asia/Dubai",
18 "offset": 4,
19 "offset_with_dst": 4,
20 "date": "2025-04-24",
21 "date_time": "2025-04-24 23:22:09",
22 "date_time_txt": "Thursday, April 24, 2025 23:22:09",
23 "date_time_wti": "Thu, 24 Apr 2025 23:22:09 +0400",
24 "date_time_ymd": "2025-04-24T23:22:09+0400",
25 "date_time_unix": 1745522529.622,
26 "time_24": "23:22:09",
27 "time_12": "11:22:09 PM",
28 "week": 17,
29 "month": 4,
30 "year": 2025,
31 "year_abbr": "25",
32 "is_dst": false,
33 "dst_savings": 0,
34 "dst_exists": false,
35 "dst_start": {},
36 "dst_end": {}
37 }
38}Time Zone and Airport Details from ICAO Code
We can pass any 4 letter ICAO code as a query paramter icao_code to get the comprehensive airport details along with the time zone information, in which that airport exists. Here is an example to get the airport details about the ICAO code 'KATL':
Response
1{
2 "airport_details": {
3 "type": "large_airport",
4 "name": "Hartsfield Jackson Atlanta International Airport",
5 "latitude": "33.63670",
6 "longitude": "-84.42810",
7 "elevation_ft": 1026,
8 "continent_code": "NA",
9 "country_code": "US",
10 "state_code": "US-GA",
11 "city": "Atlanta",
12 "iata_code": "ATL",
13 "icao_code": "KATL",
14 "faa_code": ""
15 },
16 "time_zone": {
17 "name": "America/New_York",
18 "offset": -5,
19 "offset_with_dst": -4,
20 "date": "2025-04-24",
21 "date_time": "2025-04-24 15:23:06",
22 "date_time_txt": "Thursday, April 24, 2025 15:23:06",
23 "date_time_wti": "Thu, 24 Apr 2025 15:23:06 -0400",
24 "date_time_ymd": "2025-04-24T15:23:06-0400",
25 "date_time_unix": 1745522586.935,
26 "time_24": "15:23:06",
27 "time_12": "03:23:06 PM",
28 "week": 17,
29 "month": 4,
30 "year": 2025,
31 "year_abbr": "25",
32 "is_dst": true,
33 "dst_savings": 1,
34 "dst_exists": true,
35 "dst_start": {
36 "utc_time": "2025-03-09 TIME 07",
37 "duration": "+1H",
38 "gap": true,
39 "date_time_after": "2025-03-09 TIME 03",
40 "date_time_before": "2025-03-09 TIME 02",
41 "overlap": false
42 },
43 "dst_end": {
44 "utc_time": "2025-11-02 TIME 06",
45 "duration": "-1H",
46 "gap": false,
47 "date_time_after": "2025-11-02 TIME 01",
48 "date_time_before": "2025-11-02 TIME 02",
49 "overlap": true
50 }
51 }
52}Time Zone and City Details from UN/LOCODE
We can pass any 5 letter UNLOCODE as a query paramter lo_code to get the comprehensive lo code/city details along with the time zone information of the concerned city. Here is an example to get the Germany city 'Berlin' details using the UNLOCODE code 'DEBER':
Response
1{
2 "lo_code_details": {
3 "lo_code": "DEBER",
4 "city": "Berlin",
5 "state_code": "BE",
6 "country_code": "DE",
7 "country_name": "",
8 "location_type": "Port, Rail Terminal, Road Terminal, Airport, Postal Exchange",
9 "latitude": "52.51667",
10 "longitude": "13.38333"
11 },
12 "time_zone": {
13 "name": "Europe/Berlin",
14 "offset": 1,
15 "offset_with_dst": 2,
16 "date": "2025-04-24",
17 "date_time": "2025-04-24 21:23:59",
18 "date_time_txt": "Thursday, April 24, 2025 21:23:59",
19 "date_time_wti": "Thu, 24 Apr 2025 21:23:59 +0200",
20 "date_time_ymd": "2025-04-24T21:23:59+0200",
21 "date_time_unix": 1745522639.769,
22 "time_24": "21:23:59",
23 "time_12": "09:23:59 PM",
24 "week": 17,
25 "month": 4,
26 "year": 2025,
27 "year_abbr": "25",
28 "is_dst": true,
29 "dst_savings": 1,
30 "dst_exists": true,
31 "dst_start": {
32 "utc_time": "2025-03-30 TIME 01",
33 "duration": "+1H",
34 "gap": true,
35 "date_time_after": "2025-03-30 TIME 03",
36 "date_time_before": "2025-03-30 TIME 02",
37 "overlap": false
38 },
39 "dst_end": {
40 "utc_time": "2025-10-26 TIME 01",
41 "duration": "-1H",
42 "gap": false,
43 "date_time_after": "2025-10-26 TIME 02",
44 "date_time_before": "2025-10-26 TIME 03",
45 "overlap": true
46 }
47 }
48}- Timezone name
- Geo Coordinates
- Location Adddress
- IP Address
- IATA Code
- ICAO Code
- UN/LO Code
Response in Multiple Languages
The geolocation information in the response from Time zone API when called using an IP address, can be retreived in the following languages:
- English (en)
- German (de)
- Russian (ru)
- Japanese (ja)
- French (fr)
- Chinese Simplified (cn)
- Spanish (es)
- Czech (cs)
- Italian (it)
- Korean (ko)
- Persian (fa)
- Portuguese (pt)
By default, the API responds in English. You can change the response language by passing the language code as a query parameter lang. Here are an example to get time zone and geolocation information for an IPv4 IP Address '1.1.1.1' in Chinese language:
Note: Multi language feature is available only for paid users.
Convert Time between Time Zones
You can convert a timestamp provided as a query paramter time from one time zone to another time zone. You can convert the provided timestamp in six ways:
• Convert Time using Time Zone Names
We can provide proper time zone names to find the time difference between the given time zones. Here as an example to convert timestamp from 'America/Argentina/Catamarca' to 'Asia/Kabul' providing as query paramters tz_from and tz_to respectively:
• Convert Time using Location Coordinates
One can also calculate the time difference between the two different locations' geo coordinates. Here is an example to get the time zone difference from latitude '34.0207305', longitude '-118.6919163', to latitude '53.4736827', longitude '-77.3977062', provided as query paramters lat_from, long_from, and lat_to, long_to respectively:
• Convert Time using Location Addresses
We can calculate the time difference between the two different locations using the city address. Here is an example to find the time difference between the timezones of cities 'New York, USA' and 'Lahore, Pakistan' provided as query paramters location_from and location_to respectively:
• Convert Time using IATA Codes
We can calculate the time difference of two airports using their IATA codes. Here's an example to calculate the time difference of airport 'Dubai International Airport' (DXB) and 'Heathrow Airport' (LHR) with their IATA codes provided as query parameters iata_from and iata_to respectively:
• Convert Time using ICAO Codes
Similarly, We can calculate the time difference of two airports using their ICAO codes. Here's an example to calculate the time difference of airport 'Sydney Kingsford Smith Airport' (YSSY) and 'Beijing Capital International Airport' (ZBAA) with their IATA codes provided as query parameters icao_from and icao_to respectively, and the time to convert is provided as query parameter time:
• Convert Time using UN/LOCODE
We can also calculate the time difference between the two cities using their UN/LOCODE with the help of timezone API. Here's an example to calculate the time difference of cities 'Islamabad' (PKISB) and 'New York' (USNYC) with their UN/LOCODE provided as query parameters locode_from and locode_to respectively, and the time to convert is provided as query parameter time:
Note: time parameter takes the input in the following two formats: i) 'yyyy-MM-dd HH:mm', and ii) 'yyyy-MM-dd HH:mm:ss'. This parameter is optional and you can omit it to convert the current time between two coordinates, time zones, locations, airports or UN/LOCODEs.
What's New in /v2/timezone and in /v2/timezone/convert
Below are the key updates introduced in the /v2/timezone API endpoint compared to the previous /timezone version. Although, no new changes have been introduced in the /v2/timezone/convert:
- All timezone-related data is now grouped under a single
time_zoneobject, making the response more consistent with our overall API structure. - When calling
/v2/timezonewithout any parameters or withip=, the response now includes anipfield to indicate the IP address used for the lookup. - Several fields have been renamed for clarity or from camelCase to snake_case for consistency across all endpoints.
geo→locationgeo.loaction→location.location_stringgeo.country→location.country_namegeo.state→location.state_provairportDetails→airport_detailsloCodeDetails→lo_code_detailsloCodeDetails.city_name→lo_code_details.cityloCodeDetails.administrative_country→lo_code_details.country_nametimezone→time_zone.nametimezone_offset→time_zone.offsettimezone_offset_with_dst→time_zone.offset_with_dstdst_start.dateTimeAfter→time_zone.dst_start.date_time_afterdst_start.dateTimeBefore→time_zone.dst_start.date_time_beforedst_end.dateTimeAfter→time_zone.dst_end.date_time_afterdst_end.dateTimeBefore→time_zone.dst_end.date_time_before
Reference to Time Zone API Response
Below we have provided separate tables for each JSON object fields that can be returned by Time Zone API.
• Standalone fields reference
| Field | Type | Description | Can be empty? |
|---|---|---|---|
| ip | string | The IP address used for the timezone lookup. Returned when queried using the ip= parameter or with no parameters. | Yes |
• time_zone JSON object reference
| Field | Type | Description | Can be empty? |
|---|---|---|---|
| name | string | The IANA timezone name/identifier for the location. | No |
| offset | number | The Standard time zone offset from UTC in hours. | No |
| offset_with_dst | number | The time zone offset from UTC in hours, accounting for daylight saving time (DST) if found. | No |
| date | string | The current date in 'YYYY-MM-DD' format. | No |
| date_time | string | The current date and time in 'YYYY-MM-DD HH:mm:ss' format. | No |
| date_time_txt | string | The current date and time in descriptive format for easy reading, formatted as 'EEEE, MMMM dd, yyyy HH:mm:ss'. (e.g., "Friday, November 08, 2024 08:44:26") | No |
| date_time_wti | string | The date and time with time zone information in 'EEE, dd MMM yyyy HH:mm:ss Z' format. (e.g., "Fri, 08 Nov 2024 08:44:26 -0500") | No |
| date_time_ymd | string | The date and time with timezone offset in ISO 8601 format 'YYYY-MM-DDTHH:mm:ss±HHMM'. (e.g., "2024-11-08T08:44:26-0500") | No |
| date_time_unix | float | The Unix timestamp representing the date and time in seconds (e.g., 1731073466.073). | No |
| time_24 | string | The current time in 24-hour format 'HH:mm:ss'. | No |
| time_12 | string | The current time in 12-hour format with AM/PM notation, formatted as 'HH:mm:ss AM/PM'. | No |
| week | number | The week number of the year (1-52). | No |
| month | number | The current month as a number (1-12). | No |
| year | number | The four-digit current year (e.g., 2024). | No |
| year_abbr | string | The two-digit abbreviation for the year (e.g., "24"). | No |
| is_dst | boolean | Is the time zone in daylight savings? | No |
| dst_savings | number | The amount of time added for daylight saving (in hours). | No |
| dst_exists | boolean | Indicates whether Daylight Saving Time (DST) is observed in the region. If true, the dst_start and dst_end objects will include detailed DST transition information. | No |
| dst_start.utc_time | string | The date and time in UTC when DST begins. | Yes |
| dst_start.duration | string | The time change that occurs when DST starts. | Yes |
| dst_start.gap | boolean | Is there is a missing hour (DST forward transition)? | Yes |
| dst_start.date_time_after | string | The local date and time that immediately follows the start of DST. | Yes |
| dst_start.date_time_before | string | The local date and time immediately before DST begins. | Yes |
| dst_start.overlap | boolean | Whether there is an overlap of time due to clocks being set back when DST starts. | Yes |
| dst_end.utc_time | string | The date and time in UTC when DST ends. | Yes |
| dst_end.duration | string | The time change that occurs when DST ends. | Yes |
| dst_end.gap | boolean | Is there is no gap (DST backward transition)? | Yes |
| dst_end.date_time_after | string | The local date and time that immediately follows the ends of DST. | Yes |
| dst_end.date_time_before | string | The local date and time immediately before DST ends. | Yes |
| dst_end.overlap | boolean | Whether there is an overlap of time due to clocks being set back when DST ends. | Yes |
• location JSON object reference
| Field | Type | Description | Can be empty? |
|---|---|---|---|
| location_string | string | The provided location paramter as location. | Yes |
| continent_code | string | The two-letter code of the continent (e.g., "NA" for North America). | Yes |
| continent_name | string | The full name of the continent (e.g., "North America"). | Yes |
| country_code2 | string | The ISO 3166-1 alpha-2 two-letter country code (e.g., "US"). | Yes |
| country_code3 | string | The ISO 3166-1 alpha-3 three-letter country code (e.g., "USA"). | Yes |
| country_name | string | The common name of the country (e.g., "United States"). | Yes |
| country_name_official | string | The official full name of the country (e.g., "United States of America"). | Yes |
| is_eu | boolean | Is the country belong to European Union? | Yes |
| state_prov | string | Name of the state/province/region. | Yes |
| state_code | string | Code of the state/province/region. | Yes |
| district | string | Name of the district or county. | Yes |
| city | string | Name of the city. | Yes |
| locality | string | Smaller area, part or region of a city. | Yes |
| zipcode | string | ZIP/Postal code of the place. | Yes |
| latitude | string | The geographic latitude of the location. | Yes |
| longitude | string | The geographic longitude of the location. | Yes |
• airport_details JSON object reference
| Field | Type | Description | Can be empty? |
|---|---|---|---|
| type | string | Classification of the airport based on size and traffic, such as "large_airport", "medium_airport", or "small_airport". | Yes |
| name | string | The full name of the airport. | Yes |
| latitude | string | The latitude coordinate of the airport. | Yes |
| longitude | string | The longitude coordinate of the airport. | Yes |
| elevation_ft | number | The elevation of the airport above sea level, measured in feet. | Yes |
| continent_code | string | The two-letter code of the continent. | Yes |
| country_code | string | The ISO 3166-1 alpha-2 code for the country where the airport is located. | Yes |
| state_code | string | Code of the state/province/region where the airport is located. | Yes |
| city | string | The city or administrative region that the airport serves to. | Yes |
| iata_code | string | The three-letter IATA airport code (e.g., "LHR" for London Heathrow Airport). | Yes |
| icao_code | string | The four-letter ICAO airport code (e.g., "EGLL" for London Heathrow Airport). | Yes |
| faa_code | string | The FAA location identifier, used primarily in the United States. May be empty if not applicable. | Yes |
• lo_code_details JSON object reference
| Field | Type | Description | Can be empty? |
|---|---|---|---|
| lo_code | string | A unique identifier for the location, often used in logistics and shipping, consisting of a country code and a city or terminal identifier (e.g., "USNYC" for New York, USA). | Yes |
| city | string | The name of the city or location associated with the lo_code. | Yes |
| state_code | string | The code for the state, province or region. | Yes |
| country_code | string | The ISO 3166-1 alpha-2 country code (e.g., "US" for the United States). | Yes |
| country_name | string | The name of the country in an administrative context. | Yes |
| location_type | string | The type of the location as comma separted list showing the available facilites (e.g., Port, Rail Terminal, Road Terminal, Airport, Postal Exchange, Multimodal). | Yes |
| latitude | string | The latitude coordinate of the location. | Yes |
| longitude | string | The longitude coordinate of the location. | Yes |
Note: lo_code - UN/LOCODE for all the countries and their cities are available at the UNECE website.
Reference to Time Conversion API Response
| Field | Type | Description | Can be empty? |
|---|---|---|---|
| original_time | string | The original date and time before any conversion, presented in the format 'yyyy-MM-dd HH:mm:ss' (e.g., "2024-03-11 14:47:32"). | No |
| converted_time | string | The date and time after conversion, in the format 'yyyy-MM-dd HH:mm:ss' (e.g., "2024-03-11 02:47:32"). | No |
| diff_hour | number | The difference in hours between the original_time and the converted_time. | No |
| diff_min | number | The difference in minutes between the original_time and the converted_time. | No |
Error Codes
Time Zone API and Time Conversion API returns HTTP status code 200 for a successful API request along with the response.
While, in case of a bad or invalid request, Time Zone API and Time Conversion API returns 4xx HTTP status code along with a descriptive message explaining the reason for the error.
Below is a detailed explanation of the specific HTTP status codes and their corresponding error conditions:
| HTTP Status | Description |
|---|---|
| 400 Bad Request | It is returned for one of the following reasons:
|
| 401 Unauthorized | It is returned for one of the following reasons:
|
| 404 Not Found | It is returned for one of the following reasons:
|
| 405 Method Not Allowed |
|
| 429 Too Many Requests | It is returned for one of the following reasons:
|
| 499 Client Closed Request |
|
| 5XX Server Side Error |
|
API SDKs
To facilitate the developers, we have added some SDKs for various programming languages. The detailed documentation on how to use these SDKs is available in the respective SDK's documentation page linked below.
Our SDKs are also available on Github. Feel free to help us improve them. Following are the available SDKs: