Time zone API provides current time, date, and time zone related information. It can be consumed with the foloowing input variations:
In each variation of the time zone API, response remains same. Here are the details to consume each variation of the time zone API.
You can pass a valid time zone name as a query parameter tz to get the time zone information. Here is a curl exmaple:
# Get 'America/Los_Angeles' timezone information
$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&tz=America/Los_Angeles'
{
"timezone": "America/Los_Angeles",
"timezone_offset": -8,
"date": "2018-12-06",
"date_time": "2018-12-06 02:02:09",
"date_time_txt": "Thursday, December 06, 2018 02:02:09",
"date_time_wti": "Thu, 06 Dec 2018 02:02:09 -0800",
"date_time_ymd": "2018-12-06T02:02:09-0800",
"date_time_unix": 1544090529.989,
"time_24": "02:02:09",
"time_12": "02:02:09 AM",
"week": "49",
"month": "12",
"year": "2018",
"year_abbr": "18",
"is_dst": false,
"dst_savings": 1
}
You can pass any address of a location as the query parameter to get the time zone information. Here is a curl example:
# Get time zone information for the address 'London, UK'
$ curl --location --request GET 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&location=London,%20UK'
{
"geo": {
"country": "United Kingdom",
"state": "England",
"city": "London",
"latitude": 51.505182,
"longitude": -0.0999387
},
"timezone": "Europe/London",
"timezone_offset": 0,
"date": "2020-12-21",
"date_time": "2020-12-21 13:17:59",
"date_time_txt": "Monday, December 21, 2020 13:17:59",
"date_time_wti": "Mon, 21 Dec 2020 13:17:59 +0000",
"date_time_ymd": "2020-12-21T13:17:59+0000",
"date_time_unix": 1608556679.524,
"time_24": "13:17:59",
"time_12": "01:17:59 PM",
"week": "52",
"month": "12",
"year": "2020",
"year_abbr": "20",
"is_dst": false,
"dst_savings": 1
}
You can pass the latitude and longitude of a location as query parameters to get the time zone information. Here is a curl example:
# 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'
{
"timezone": "Australia/Brisbane",
"timezone_offset": 10,
"date": "2020-12-21",
"date_time": "2020-12-21 23:49:16",
"date_time_txt": "Monday, December 21, 2020 23:49:16",
"date_time_wti": "Mon, 21 Dec 2020 23:49:16 +1000",
"date_time_ymd": "2020-12-21T23:49:16+1000",
"date_time_unix": 1608558556.584,
"time_24": "23:49:16",
"time_12": "11:49:16 PM",
"week": "52",
"month": "12",
"year": "2020",
"year_abbr": "20",
"is_dst": false,
"dst_savings": 0
}
You can pass any IPv4 or IPv6 address as a query parameter to get the regional timezone information. Here is a curl example:
# Get time zone information for IP address '1.1.1.1'
$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&ip=1.1.1.1'
{
"geo": {
"ip": "1.1.1.1",
"country_code2": "AU",
"country_code3": "AUS",
"country_name": "Australia",
"state_prov": "Queensland",
"district": "South Brisbane",
"city": "Brisbane",
"zipcode": "4101",
"latitude": "-27.47561",
"longitude": "153.01537"
},
"timezone": "Australia/Brisbane",
"timezone_offset": 10,
"date": "2020-12-21",
"date_time": "2020-12-21 23:49:42",
"date_time_txt": "Monday, December 21, 2020 23:49:42",
"date_time_wti": "Mon, 21 Dec 2020 23:49:42 +1000",
"date_time_ymd": "2020-12-21T23:49:42+1000",
"date_time_unix": 1608558582.413,
"time_24": "23:49:42",
"time_12": "11:49:42 PM",
"week": "52",
"month": "12",
"year": "2020",
"year_abbr": "20",
"is_dst": false,
"dst_savings": 0
}
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.
You can call the time zone API without passing any time zone, coordinates or IP address as well. It will use the calling machine's IP address to return the regional time zone information. Here is a curl example:
$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY'
This variation is widely used on embedded hardware and IoT 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.
The geolocation information in the response from Time zone API when called using an IP address, can be retreived in the following languages:
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 a few curl examples:
# Get geolocation 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.
You can convert a provided timestamp from one time zone to another time zone. You can convert the provided timestamp in two ways:
# Convert timestamp between time zones using the time zone names
$ curl --location --request GET 'https://api.ipgeolocation.io/timezone/convert?apiKey=API_KEY&tz_from=America/Argentina/Catamarca&tz_to=Asia/Kabul&time=2020-12-08%2011:00'
{
"original_time": "2020-12-08 11:00",
"converted_time": "2020-12-08 18:30",
"diff_hour": 7.5,
"diff_min": 450
}
# Convert timestamp between time zones using coordinates of the locations
$ curl --location --request GET '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=2020-12-08%2006:00'
{
"original_time": "2020-12-08 11:00",
"converted_time": "2020-12-08 18:30",
"diff_hour": 7.5,
"diff_min": 450
}
# Convert timestamp between time zones by location addresses
$ curl --location --request GET 'https://api.ipgeolocation.io/timezone/convert?apiKey=API_KEY&location_from=New%20York,%20USA&location_to=Lahore,%20Pakistan&time=2020-12-08%2006:00'
{
"original_time": "2020-12-08 06:00",
"converted_time": "2020-12-08 16:00",
"diff_hour": 9,
"diff_min": 540
}
Note: time=2020-12-08%2006:00 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 or locations.