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.

  • objectObject,
    • fieldoriginal_time:"",
    • fieldconverted_time:"",
    • fielddiff_hour:,
    • fielddiff_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:

US FlagEnglish DE FlagGerman RU FlagRussian JP FlagJapanese FR FlagFrench CN FlagChinese Simplified ES FlagSpanish CZ FlagCzech IT FlagItalian KO FlagKorean FA FlagPersian

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.

iplocation

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.

geoip

Global Communication

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

iplook-up

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.

geoip

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

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