Date, Time and Time zone API

Time zone API provides current time, date, and time zone related information. It can be consumed with the foloowing input variations:

For a Time Zone Name
For any Address (preferrably, city address)
For Location Coordinates (latitude & longitude)
For any IP address

In each variation of the time zone API, response remains same. 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 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
}

Time Zone Information from any Address

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
}

Time Zone Information from 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": "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
}

IP to Time Zone

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.

Using Client or Machine IP Address

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.

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)

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.

Convert Time between Time Zones

You can convert a provided timestamp from one time zone to another time zone. You can convert the provided timestamp in two ways:

Convert Time using Time Zone Names

# 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 Time using Location Coordinates

# 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 Time using Location Addresses

# 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.