Time Zone API and IP to Timezone Lookup

IPGeolocation's free Timezone API and Time conversion API provides date and time related information such as current time, date in various formats, week, month, year, time in unix timestamp, UTC/GMT offset and day light saving time from timezone name, any IPv4 or IPv6 address or geolocation coordinates in JSON and XML format over secure HTTPS connection. The API also calculates precise time differences in hours and minutes between two locations using timezone, coordinates, or city.

Get Free API Access

geo:Object,
- original_time:"",
- converted_time:"",
- diff_hour:,
- diff_min:,

Detailed Timezone Data

Detailed timezone data consists of comprehensive information about the current time and date, presented in multiple formats. It also covers timezone offset values, daylight saving details like start and end times, any gaps or overlaps, and whether DST is active. Optionally, this data can be enriched with geolocation information when IP-based timezone detection is requested.

Response

1{
2  "timezone": "America/Los_Angeles",
3  "timezone_offset": -8,
4  "timezone_offset_with_dst": -8,
5  "date": "2024-11-06",
6  "date_time": "2024-11-06 23:45:05",
7  "date_time_txt": "Wednesday, November 06, 2024 23:45:05",
8  "date_time_wti": "Wed, 06 Nov 2024 23:45:05 -0800",
9  "date_time_ymd": "2024-11-06T23:45:05-0800",
10  "date_time_unix": 1730965505.596,
11  "time_24": "23:45:05",
12  "time_12": "11:45:05 PM",
13  "week": 45,
14  "month": 11,
15  "year": 2024,
16  "year_abbr": "24",
17  "is_dst": false,
18  "dst_savings": 0,
19  "dst_exists": true,
20  "dst_start": {
21    "utc_time": "2024-03-10 TIME 10",
22    "duration": "+1H",
23    "gap": true,
24    "dateTimeAfter": "2024-03-10 TIME 03",
25    "dateTimeBefore": "2024-03-10 TIME 02",
26    "overlap": false
27  },
28  "dst_end": {
29    "utc_time": "2024-11-03 TIME 09",
30    "duration": "-1H",
31    "gap": false,
32    "dateTimeAfter": "2024-11-03 TIME 01",
33    "dateTimeBefore": "2024-11-03 TIME 02",
34    "overlap": true
35  }
36}

Geo Location Module

When Time Zone API is called without any parameter, with the IP address or with the location address, it returns geolocation information for the concered location, along with the Time Zone Data.

Response

1"geo": {
2  "continent_code": "NA",
3  "continent_name": "North America",
4  "country_code2": "US",
5  "country_code3": "USA",
6  "country_name": "United States",
7  "country_name_official": "United States of America",
8  "is_eu": false,
9  "state_prov": "California",
10  "state_code": "US-CA",
11  "district": "Santa Clara",
12  "city": "Mountain View",
13  "zipcode": "94043-1351",
14  "latitude": "37.42240",
15  "longitude": "-122.08421"
16}

Get Airport details from IATA or ICAO codes

The Time Zone API can retrieve detailed airport information along with time zone data using IATA or ICAO codes. The response includes the airport type, name, geo coordinates, elevation, continent, country and state codes, municipality, and IATA, ICAO, and FAA codes (if available), providing a complete profile of the airport's location and time zone.

Response

1"airportDetails": {
2  "type": "large_airport",
3  "name": "London Heathrow Airport",
4  "latitude": "51.47060",
5  "longitude": "-0.46194",
6  "elevation_ft": 83,
7  "continent_code": "EU",
8  "country_code": "GB",
9  "state_code": "GB-ENG",
10  "municipality": "London",
11  "iata_code": "LHR",
12  "icao_code": "EGLL",
13  "faa_code": ""
14}

Get City Level Information from LO Code

Our Time Zone API can be queried with an LO Code to provides city-level information, including the LO Code, location type, and geographic coordinates, along with relevant time zone data.

Response

1"loCodeDetails": {
2  "locode": "USNYC",
3  "city_name": "New York",
4  "state_code": "NY",
5  "country_code": "US",
6  "administrative_country": "",
7  "location_type": "Port, Rail Terminal, Road Terminal, Airport, Postal Exchange",
8  "latitude": "40.70000",
9  "longitude": "-74.00000"
10}

Convert Time / Calculate Time Difference

Our Time Zone API sub-feature can calculate the time difference between two locations based on their time zone names, geo coordinates, or city address locations.

Response

1{
2  "original_time": "2024-03-11 14:47:32",
3  "converted_time": "2024-03-11 02:47:32",
4  "diff_hour": 12,
5  "diff_min": 720
6}

Response in Multiple Languages

You can retrieve the geolocation information in the following languages:

English

German

Russian

Japanese

French

Chinese Simplified ES Flag

Spanish

Czech

Italian

Korean

Persian

Use Cases

New Timezone During Traveling

Build an application for Travellers who move a lot between different timezones! Use the timezone API to keep them up-to-date and up-to-time always, no matter how many time zones they have skip over.

Ecommerce

Make sure you know which part of the world your buyers are coming from and show them the right message at the(ir) right time.

Global Communication

For teams that work from all over the globe, make communications a piece of cake using our free time zone API.

Flight Management

Airline platforms can build systems that facilitate users to show the accurate flight departure and arival time in the passengers' time zones, helping them avoid any confusion and better plan their travel.

Ready to get started?Get Started with IP Intelligence API Today

Get Started

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.

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:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&tz=America/Los_Angeles'

Response

1{
2  "timezone": "America/Los_Angeles",
3  "timezone_offset": -8,
4  "timezone_offset_with_dst": -8,
5  "date": "2024-11-07",
6  "date_time": "2024-11-07 07:07:35",
7  "date_time_txt": "Thursday, November 07, 2024 07:07:35",
8  "date_time_wti": "Thu, 07 Nov 2024 07:07:35 -0800",
9  "date_time_ymd": "2024-11-07T07:07:35-0800",
10  "date_time_unix": 1730992055.998,
11  "time_24": "07:07:35",
12  "time_12": "07:07:35 AM",
13  "week": 45,
14  "month": 11,
15  "year": 2024,
16  "year_abbr": "24",
17  "is_dst": false,
18  "dst_savings": 0,
19  "dst_exists": true,
20  "dst_start": {
21    "utc_time": "2024-03-10 TIME 10",
22    "duration": "+1H",
23    "gap": true,
24    "dateTimeAfter": "2024-03-10 TIME 03",
25    "dateTimeBefore": "2024-03-10 TIME 02",
26    "overlap": false
27  },
28  "dst_end": {
29    "utc_time": "2024-11-03 TIME 09",
30    "duration": "-1H",
31    "gap": false,
32    "dateTimeAfter": "2024-11-03 TIME 01",
33    "dateTimeBefore": "2024-11-03 TIME 02",
34    "overlap": true
35  }
36}

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':

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&location=London,%20UK'

Response

1{
2  "geo": {
3    "location": "London, UK",
4    "country": "United Kingdom",
5    "state": "England",
6    "city": "London",
7    "locality": "",
8    "latitude": "51.50002",
9    "longitude": "-0.19244"
10  },
11  "timezone": "Europe/London",
12  "timezone_offset": 0,
13  "timezone_offset_with_dst": 0,
14  "date": "2024-11-07",
15  "date_time": "2024-11-07 15:30:15",
16  "date_time_txt": "Thursday, November 07, 2024 15:30:15",
17  "date_time_wti": "Thu, 07 Nov 2024 15:30:15 +0000",
18  "date_time_ymd": "2024-11-07T15:30:15+0000",
19  "date_time_unix": 1730993415.244,
20  "time_24": "15:30:15",
21  "time_12": "03:30:15 PM",
22  "week": 45,
23  "month": 11,
24  "year": 2024,
25  "year_abbr": "24",
26  "is_dst": false,
27  "dst_savings": 0,
28  "dst_exists": true,
29  "dst_start": {
30    "utc_time": "2024-03-31 TIME 01",
31    "duration": "+1H",
32    "gap": true,
33    "dateTimeAfter": "2024-03-31 TIME 02",
34    "dateTimeBefore": "2024-03-31 TIME 01",
35    "overlap": false
36  },
37  "dst_end": {
38    "utc_time": "2024-10-27 TIME 01",
39    "duration": "-1H",
40    "gap": false,
41    "dateTimeAfter": "2024-10-27 TIME 01",
42    "dateTimeBefore": "2024-10-27 TIME 02",
43    "overlap": true
44  }
45}

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:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&lat=-27.4748&long=153.017'

Response

1{
2  "timezone": "Australia/Brisbane",
3  "timezone_offset": 10,
4  "timezone_offset_with_dst": 10,
5  "date": "2024-11-08",
6  "date_time": "2024-11-08 01:59:01",
7  "date_time_txt": "Friday, November 08, 2024 01:59:01",
8  "date_time_wti": "Fri, 08 Nov 2024 01:59:01 +1000",
9  "date_time_ymd": "2024-11-08T01:59:01+1000",
10  "date_time_unix": 1730995141.391,
11  "time_24": "01:59:01",
12  "time_12": "01:59:01 AM",
13  "week": 45,
14  "month": 11,
15  "year": 2024,
16  "year_abbr": "24",
17  "is_dst": false,
18  "dst_savings": 0,
19  "dst_exists": false,
20  "dst_start": "",
21  "dst_end": ""
22}

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':

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&ip=1.1.1.1'

Response

1{
2  "geo": {
3    "continent_code": "OC",
4    "continent_name": "Oceania",
5    "country_code2": "AU",
6    "country_code3": "AUS",
7    "country_name": "Australia",
8    "country_name_official": "Commonwealth of Australia",
9    "is_eu": false,
10    "state_prov": "Queensland",
11    "state_code": "AU-QLD",
12    "district": "South Brisbane",
13    "city": "Brisbane",
14    "zipcode": "4101",
15    "latitude": "-27.47306",
16    "longitude": "153.01421"
17  },
18  "timezone": "Australia/Brisbane",
19  "timezone_offset": 10,
20  "timezone_offset_with_dst": 10,
21  "date": "2024-11-08",
22  "date_time": "2024-11-08 05:26:04",
23  "date_time_txt": "Friday, November 08, 2024 05:26:04",
24  "date_time_wti": "Fri, 08 Nov 2024 05:26:04 +1000",
25  "date_time_ymd": "2024-11-08T05:26:04+1000",
26  "date_time_unix": 1731007564.746,
27  "time_24": "05:26:04",
28  "time_12": "05:26:04 AM",
29  "week": 45,
30  "month": 11,
31  "year": 2024,
32  "year_abbr": "24",
33  "is_dst": false,
34  "dst_savings": 0,
35  "dst_exists": false,
36  "dst_start": "",
37  "dst_end": ""
38}

Note: When you get the time zone information through an IP address, API will also return the 'geo' 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:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY'

This variation is widely used on embedded hardware and IoT devices to get current time after reboot.

Note:In above examples, we used API Key everywhere. Time zone API can be called from client side JavaScript with Request Origin authentication as well on paid plans.

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':

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&iata_code=DXB'

Response

1{
2  "airportDetails": {
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    "municipality": "Dubai",
12    "iata_code": "DXB",
13    "icao_code": "OMDB",
14    "faa_code": ""
15  },
16  "timezone": "Asia/Dubai",
17  "timezone_offset": 4,
18  "timezone_offset_with_dst": 4,
19  "date": "2024-11-08",
20  "date_time": "2024-11-08 12:37:20",
21  "date_time_txt": "Friday, November 08, 2024 12:37:20",
22  "date_time_wti": "Fri, 08 Nov 2024 12:37:20 +0400",
23  "date_time_ymd": "2024-11-08T12:37:20+0400",
24  "date_time_unix": 1731055040.671,
25  "time_24": "12:37:20",
26  "time_12": "12:37:20 PM",
27  "week": 45,
28  "month": 11,
29  "year": 2024,
30  "year_abbr": "24",
31  "is_dst": false,
32  "dst_savings": 0,
33  "dst_exists": false,
34  "dst_start": "",
35  "dst_end": ""
36}

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':

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&icao_code=KATL'

Response

1{
2  "airportDetails": {
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    "municipality": "Atlanta",
12    "iata_code": "ATL",
13    "icao_code": "KATL",
14    "faa_code": ""
15  },
16  "timezone": "America/New_York",
17  "timezone_offset": -5,
18  "timezone_offset_with_dst": -5,
19  "date": "2024-11-08",
20  "date_time": "2024-11-08 05:26:18",
21  "date_time_txt": "Friday, November 08, 2024 05:26:18",
22  "date_time_wti": "Fri, 08 Nov 2024 05:26:18 -0500",
23  "date_time_ymd": "2024-11-08T05:26:18-0500",
24  "date_time_unix": 1731061578.272,
25  "time_24": "05:26:18",
26  "time_12": "05:26:18 AM",
27  "week": 45,
28  "month": 11,
29  "year": 2024,
30  "year_abbr": "24",
31  "is_dst": false,
32  "dst_savings": 0,
33  "dst_exists": true,
34  "dst_start": {
35    "utc_time": "2024-03-10 TIME 07",
36    "duration": "+1H",
37    "gap": true,
38    "dateTimeAfter": "2024-03-10 TIME 03",
39    "dateTimeBefore": "2024-03-10 TIME 02",
40    "overlap": false
41  },
42  "dst_end": {
43    "utc_time": "2024-11-03 TIME 06",
44    "duration": "-1H",
45    "gap": false,
46    "dateTimeAfter": "2024-11-03 TIME 01",
47    "dateTimeBefore": "2024-11-03 TIME 02",
48    "overlap": true
49  }
50}

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':

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&lo_code=DEBER'

Response

1{
2  "loCodeDetails": {
3    "locode": "DEBER",
4    "city_name": "Berlin",
5    "state_code": "BE",
6    "country_code": "DE",
7    "administrative_country": "",
8    "location_type": "Port, Rail Terminal, Road Terminal, Airport, Postal Exchange",
9    "latitude": "52.51667",
10    "longitude": "13.38333"
11  },
12  "timezone": "Europe/Berlin",
13  "timezone_offset": 1,
14  "timezone_offset_with_dst": 1,
15  "date": "2024-11-08",
16  "date_time": "2024-11-08 11:45:06",
17  "date_time_txt": "Friday, November 08, 2024 11:45:06",
18  "date_time_wti": "Fri, 08 Nov 2024 11:45:06 +0100",
19  "date_time_ymd": "2024-11-08T11:45:06+0100",
20  "date_time_unix": 1731062706.441,
21  "time_24": "11:45:06",
22  "time_12": "11:45:06 AM",
23  "week": 45,
24  "month": 11,
25  "year": 2024,
26  "year_abbr": "24",
27  "is_dst": false,
28  "dst_savings": 0,
29  "dst_exists": true,
30  "dst_start": {
31    "utc_time": "2024-03-31 TIME 01",
32    "duration": "+1H",
33    "gap": true,
34    "dateTimeAfter": "2024-03-31 TIME 03",
35    "dateTimeBefore": "2024-03-31 TIME 02",
36    "overlap": false
37  },
38  "dst_end": {
39    "utc_time": "2024-10-27 TIME 01",
40    "duration": "-1H",
41    "gap": false,
42    "dateTimeAfter": "2024-10-27 TIME 02",
43    "dateTimeBefore": "2024-10-27 TIME 03",
44    "overlap": true
45  }
46}

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)
Persian (fa)
Korean (ko)

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:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&ip=1.1.1.1&lang=cn'

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 three 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:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone/convert?apiKey=API_KEY&tz_from=America/Argentina/Catamarca&tz_to=Asia/Kabul&time=2024-12-08%2011:00'

Response

1{
2    "original_time": "2024-12-08 11:00",
3    "converted_time": "2024-12-08 18:30:00",
4    "diff_hour": 7.5,
5    "diff_min": 450
6  }

• 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:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone/convert?apiKey=API_KEY&lat_from=34.0207305&long_from=-118.6919163&lat_to=53.4736827&long_to=-77.3977062&time=2024-12-08%2006:00'

Response

1{
2    "original_time": "2024-12-08 06:00",
3    "converted_time": "2024-12-08 09:00:00",
4    "diff_hour": 3,
5    "diff_min": 180
6  }

• 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:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/timezone/convert?apiKey=API_KEY&location_from=New%20York,%20USA&location_to=Lahore,%20Pakistan&time=2024-12-08%2006:00'

Response

1{
2    "original_time": "2024-12-08 06:00",
3    "converted_time": "2024-12-08 16:00:00",
4    "diff_hour": 10,
5    "diff_min": 600
6  }

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 or locations.

Reference to Time Zone API Response

Field	Type	Description	Can be empty?
timezone	string	The IANA timezone name/identifier for the location.	No
timezone_offset	number	The Standard time zone offset from UTC in hours.	No
timezone_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	Whether Daylight Saving Time (DST) is observed in the region.	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.dateTimeAfter	string	The local date and time that immediately follows the start of DST.	Yes
dst_start.dateTimeBefore	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.dateTimeAfter	string	The local date and time that immediately follows the ends of DST.	Yes
dst_end.dateTimeBefore	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
geo.location	string	The provided location paramter as `location`.	Yes
geo.continent_code	string	The two-letter code of the continent (e.g., "NA" for North America).	Yes
geo.continent_name	string	The full name of the continent (e.g., "North America").	Yes
geo.country_code2	string	The ISO 3166-1 alpha-2 two-letter country code (e.g., "US").	Yes
geo.country_code3	string	The ISO 3166-1 alpha-3 three-letter country code (e.g., "USA").	Yes
geo.country_name	string	The common name of the country (e.g., "United States").	Yes
geo.country_name_official	string	The official full name of the country (e.g., "United States of America").	Yes
geo.country	string	The common name of the country (e.g., "United States"). It is returned in case of `location` search.	Yes
geo.is_eu	boolean	Is the country belong to European Union?	Yes
geo.state_prov	string	Name of the state/province/region.	Yes
geo.state	string	Name of the state/province/region. It is returned in case of `location` search.	Yes
geo.state_code	string	Code of the state/province/region.	Yes
geo.district	string	Name of the district or county.	Yes
geo.city	string	Name of the city.	Yes
geo.locality	string	Smaller area, part or region of a city.	Yes
geo.zipcode	string	ZIP/Postal code of the place.	Yes
geo.latitude	string	The geographic latitude of the location.	Yes
geo.longitude	string	The geographic longitude of the location.	Yes
airportDetails.type	string	Classification of the airport based on size and traffic, such as "large_airport", "medium_airport", or "small_airport".	Yes
airportDetails.name	string	The full name of the airport.	Yes
airportDetails.latitude	string	The latitude coordinate of the airport.	Yes
airportDetails.longitude	string	The longitude coordinate of the airport.	Yes
airportDetails.elevation_ft	number	The elevation of the airport above sea level, measured in feet.	Yes
airportDetails.continent_code	string	The two-letter code of the continent.	Yes
airportDetails.country_code	string	The ISO 3166-1 alpha-2 code for the country where the airport is located.	Yes
airportDetails.state_code	string	Code of the state/province/region where the airport is located.	Yes
airportDetails.city	string	The city or administrative region that the airport serves to.	Yes
airportDetails.iata_code	string	The three-letter IATA airport code (e.g., "LHR" for London Heathrow Airport).	Yes
airportDetails.icao_code	string	The four-letter ICAO airport code (e.g., "EGLL" for London Heathrow Airport).	Yes
airportDetails.faa_code	string	The FAA location identifier, used primarily in the United States. May be empty if not applicable.	Yes
loCodeDetails.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
loCodeDetails.city_name	string	The name of the city or location associated with the `locode`.	Yes
loCodeDetails.state_code	string	The code for the state, province or region.	Yes
loCodeDetails.country_code	string	The ISO 3166-1 alpha-2 country code (e.g., "US" for the United States).	Yes
loCodeDetails.administrative_country	string	The name of the country in an administrative context.	Yes
loCodeDetails.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
loCodeDetails.latitude	string	The latitude coordinate of the location.	Yes
loCodeDetails.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: If the provided IPv4, IPv6 address, or domain name is invalid. If special character(s) ( ) [ ] { } \| ^ ` is passed in the API URL either as paramter or its value. Specially in case of API key. If the provided IATA code to the request paramter `iata_code` is not in the format as three letter code AAA. If the provided ICAO code to the request paramter `icao_code` is not in the format as four letter code AAAA. If the provided UN/LOCODE to the request paramter `lo_code` is not in format as first two characters of country code, followed by the three alphanumeric characters of the city/region. If the provided values to the request parameters `lat` and`long` are not numbers, or the values fall outside the acceptable latitude and longitude ranges. The valid range for latitude is between -90 and 90, and for longitude, it is between -180 and 180. If the bogon or private IP address is provided to query the Time Zone information. If the provided time zone name to the query paramter `tz` is wrong or not registered in the IANA time zone database. If one of the query paramters `tz_from` and `tz_to` is provided and other is missing, for time conversion. If one of the query paramters `location_from` and `location_to` is provided and other is missing, for time conversion. If one of the query paramters `lat_from`, `long_from`, `lat_to`, and `long_to` is provided and other(s) is/are missing, for time conversion. If the location address provided to one of the paramters `location_from` and `location_to` is invalid, for time conversion. City or state level address must be provided. If the geographic coordinates provided to one of the paramters `lat_from`, `long_from`, `lat_to`, and `long_to` is/are not numbers, or the values fall outside the acceptable latitude and longitude ranges. The valid range for latitude is between -90 and 90, and for longitude, it is between -180 and 180. If the time zone names provided to one of the paramters `tz_from` and `tz_to` is/are wrong or not registered in the IANA time zone database. If none of the query parameter combination is provided for time conversion. `tz_from` and `tz_to` or `location_from` and `location_to` or `lat_from`, `long_from`, `lat_to`, `long_to` combination must be provided.
401 Unauthorized	It is returned for one of the following reasons: If API key (as `apiKey` URL parameter) is missing from the request to IP Geolocation API. If an invalid (a random value) API key is provided. If the API request is made from an unverified ipgeolocation.io account. If your account has been disabled or locked to use by the admin due to abuse or illegal activity. When the request to IP Geolocation API is made using API key for a database subscription When the request to IP Geolocation API is made on the 'paused' subscription. If you’re making API requests after your subscription trial has been expired. If your active until date has passed and you need to upgrade your account.
404 Not Found	It is returned for one of the following reasons: If the IPv4, IPv6, or domain name does not not exists in our database. If the IPv4, IPv6, or domain name is passed as a path variable, instead of url parameter as `ip=`. If the location address provided to the request paramters `location` is invalid. City or state level address must be provided. If the provided UN/LOCODE, IATA code or ICAO code to the query paramters `lo_code`, `iata_code`, or `icao_code` does not exists in our database. If the wrong endpoint is called, that does not exists in our API.
405 Method Not Allowed	If wrong HTTP request method is used for calling the endpoints. Only GET method is allowed for both endpoints `/timezone` and `/timezone/convert`.
429 Too Many Requests	It is returned for one of the following reasons: If the API usage limit has reached for the free subscriptions, or paid subscriptions with the status 'past due', 'deleted' or 'trial expired'. If the surcharge API usage limit has reached against the subscribed plan.
499 Client Closed Request	If the client has set the very short request or connection timeout, leading to the server closing the request prematurely.
5XX Server Side Error	If a `500` (Internal Server Error), `502` (Bad Gateway), `503` (Service Unavailable), `504` (Gateway Timeout), or `505` (HTTP Version Not Supported) status code is returned, it indicates an issue on our end. Please contact us with your request at support@ipgeolocation.io for further assistance.

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:

Overview
Time Zone Info from a Time Zone Name
Time Zone Info from any Address
Time Zone Info from Location Coordinates
Time Zone Info from IP Address
Using Client or Machine IP Address
Airport Details from IATA Code
Airport Details from ICAO Code
City Details from UN/LOCODE
Response in Multiple Languages
Convert Time between Time Zones
• Convert Time using Time Zone Names
• Convert Time using Coordinates
• Convert Time using Location address
Reference to Time Zone API Response
Reference to Time Conversion API Response
Error Codes
API SDKS