Timezone API

Timezone API provides current date, time and time zone related information. You can call the Timezone API in three ways which are following:

  • For a Time Zone
  • For Location Coordinates (latitude & longitude)
  • For any IP address

Here is the full response from Timezone API:

{
    "geo": {
        "country_code2": "AU",
        "country_code3": "AUS",
        "country_name": "Australia",
        "state_prov": "Queensland",
        "district": "Brisbane",
        "city": "South Brisbane",
        "zipcode": "4101",
        "latitude": "-27.4748",
        "longitude": "153.017"
    },
    "timezone": "Australia/Brisbane",
    "timezone_offset": 10,
    "date": "2018-07-27",
    "date_time": "2018-07-27 07:57:25",
    "date_time_txt": "Friday, July 27, 2018 07:57:25",
    "date_time_wti": "Fri, 27 Jul 2018 07:57:25 +0000",
    "date_time_ymd": "2018-07-27T07:57:25+0000",
    "time_24": "07:57:25",
    "time_12": "07:57:25 AM",
    "week": "30",
    "month": "07",
    "year": "2018",
    "year_abbr": "18",
    "is_dst": false,
    "dst_savings": 0
}

Response in Multiple Languages

The geolocation information in the response from Timezone API 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)

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'

Only the paid plan subscriptions can get the response in languages other than English. All the other users will only get the response in English.

Timezone API has four different variations. Here is the detail for each. The response in each variation remains the same, however, the different input source is passed in each variation.

Getting Time Zone Information for a Time Zone

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' time zone 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
}

Getting Time Zone Information for Location Coordinates

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": "Asia/Tokyo",
    "timezone_offset": 9,
    "date": "2018-12-06",
    "date_time": "2018-12-06 19:03:52",
    "date_time_txt": "Thursday, December 06, 2018 19:03:52",
    "date_time_wti": "Thu, 06 Dec 2018 19:03:52 +0900",
    "date_time_ymd": "2018-12-06T19:03:52+0900",
    "date_time_unix": 1544090632.434,
    "time_24": "19:03:52",
    "time_12": "07:03:52 PM",
    "week": "49",
    "month": "12",
    "year": "2018",
    "year_abbr": "18",
    "is_dst": false,
    "dst_savings": 0
}

Getting Time Zone Information for an IPv4 or IPv6 Address

You can pass any IPv4 or IPv6 address as a query parameter to get the regional time zone 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": {
        "country_code2": "AU",
        "country_code3": "AUS",
        "country_name": "Australia",
        "state_prov": "Queensland",
        "district": "South Brisbane",
        "city": "South Brisbane",
        "zipcode": "4101",
        "latitude": "-27.4748",
        "longitude": "153.017"
    },
    "timezone": "Australia/Brisbane",
    "timezone_offset": 10,
    "date": "2018-12-06",
    "date_time": "2018-12-06 20:06:30",
    "date_time_txt": "Thursday, December 06, 2018 20:06:30",
    "date_time_wti": "Thu, 06 Dec 2018 20:06:30 +1000",
    "date_time_ymd": "2018-12-06T20:06:30+1000",
    "date_time_unix": 1544090790.407,
    "time_24": "20:06:30",
    "time_12": "08:06:30 PM",
    "week": "49",
    "month": "12",
    "year": "2018",
    "year_abbr": "18",
    "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.

Using Client or Machine IP Address

You can call the timezone 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 in IoT to get current time after reboot.

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