Timezone Lookup API - Get Timezone from IP and More

The Timezone Lookup API allows you to retrieve timezone from IP address, location address, coordinates, or timezone name. This API delivers a wide range of date and time information, including the current time, date in multiple formats, week, month, year, and Unix timestamp.

Get the time zone information by following ways:

From time zone name
From address (preferably city and country)
From location coordinates (latitude and longtitude)
From IP address

When requesting information using an IP address with the time zone API, the response will also include "geo" field for geolocation information. In this scenario, you can also specify an additional "lang" parameter to receive geolocation information in multiple languages.

10K Free Credits, No Credit Card Required

Features

Real-Time Data

Get up-to-the-second timezone offset between two locations. Users always receive the most current and accurate time details.

Diverse Input Options

Use timezone name, location address, or location coordinates to perform time conversion making the api suitable for a wide range of applications.

Documentation

API Endpoint

GET

https://api.apifreaks.com/v1.0/geolocation/timezone

Test

LANGUAGE

Python

PHP

Java

Node

Ruby

$ pip install requests

API Request

Parameter	Required	Type	Default	Description
ip	No	String	request ip	IPv4 or IPv6 address to extract time zone informatin using IP address
tz	No	String		Extract time zone information using timezone name
location	No	String		Extract time zone information using location (preferably city and country)
lat	No	Number		Latitude to extract time zone informatin using location coordinates
long	No	Number		Longitude to extract time zone informatin using location coordinates
lang	No	String	en	response language of "geo" field in case of lookup through IP address / location address. Possible values are: (1) en (English) (2) de (German) (3) ru (Russian) (4) ja (Japanese) (5) fr (French) (6) cn (Chinese Simplifed) (7) es (Spanish) (8) cs (Czech) (9) it (Italian)

API Response

Below are the response fields when performing a lookup using geographical coordinates or a time-zone name:

Field	Type	Requirement	Description
timezone	String	Mandatory	The name of the time zone, e.g., "America/New_York"
timezone_offset	Number	Mandatory	The time difference in hours from UTC for the specified time zone without considering DST
timezoneoffsetwith_dst	Number	Mandatory	The time difference in hours from UTC for the specified time zone, including DST
date	String	Mandatory	The current date in the specified time zone in YYYY-MM-DD format
date_time	String	Mandatory	The current date and time in the specified time zone in ISO 8601 format
datetimetxt	String	Mandatory	The current date and time in a human-readable format, e.g., "Wednesday, July 26, 2024, 15:00:00"
datetimewti	String	Mandatory	The current date and time in the specified time zone in "Weekday, Time" format
datetimeymd	String	Mandatory	The current date and time in "YYYY-MM-DD HH:MM:SS" format
datetimeunix	Float	Mandatory	The current date and time as a Unix timestamp (seconds since Jan 1, 1970)
time_24	String	Mandatory	The current time in 24-hour format, e.g., "15:00:00"
time_12	String	Mandatory	The current time in 12-hour format with AM/PM, e.g., "03:00:00 PM"
week	Number	Mandatory	The current week number of the year in the specified time zone
month	Number	Mandatory	The current month number in the specified time zone
year	Number	Mandatory	The current year in the specified time zone
year_abbr	String	Mandatory	The abbreviated current year in the specified time zone, e.g., "24" for 2024
is_dst	Boolean	Mandatory	Indicates whether Daylight Saving Time (DST) is currently in effect in the specified time zone
dst_savings	Number	Mandatory	The amount of time (in hours) by which clocks are adjusted for DST
dst_exists	Boolean	Mandatory	Indicates whether DST is observed in the specified time zone
dst_start	String	Optional	The start date of the DST period in the specified time zone
dst_end	String	Optional	The end date of the DST period in the specified time zone
dststart.utctime	String	Mandatory	The UTC time of the DST start date
dst_start.duration	String	Mandatory	The duration of the DST start transition
dst_start.gap	Boolean	Mandatory	Indicates whether there is a time gap at the start of DST
dst_start.datetimeAfter	String	Mandatory	The date and time after the start of DST
dst_start.datetimeBefore	String	Mandatory	The date and time before the start of DST
dst_start.overlap	Boolean	Mandatory	Indicates whether there is an overlap period at the start of DST
dstend.utctime	String	Mandatory	The UTC time of the DST end date
dst_end.duration	String	Mandatory	The duration of the DST end transition
dst_end.gap	Boolean	Mandatory	Indicates whether there is a time gap at the end of DST
dst_end.datetimeAfter	String	Mandatory	The date and time after the end of DST
dst_end.datetimeBefore	String	Mandatory	The date and time before the end of DST
dst_end.overlap	Boolean	Mandatory	Indicates whether there is an overlap period at the end of DST

The following fields will be appended to the above response based on the lookup performed using a location address:

Field	Type	Requirement	Description
geo.location	String	Mandatory	The complete geographical location, including country, state, city, and locality
geo.country	String	Optional	The country of the geographical location
geo.state	String	Optional	The state of the geographical location
geo.city	String	Optional	The city of the geographical location
geo.locality	String	Optional	The locality or neighborhood of the geographical location
geo.latitude	Float	Mandatory	The latitude coordinate of the geographical location
geo.longitude	Float	Mandatory	The longitude coordinate of the geographical location

The following fields will be appended to the above response based on the lookup performed using an IP address:

Field	Type	Requirement	Description
geo.country_code2	String	Mandatory	The 2-letter country code (ISO 3166-1 alpha-2)
geo.country_code3	String	Mandatory	The 3-letter country code (ISO 3166-1 alpha-3)
geo.country_name	String	Mandatory	The common name of the country
geo.country_name_official	String	Mandatory	The official name of the country
geo.state_prov	String	Optional	The state or province of the geographical location
geo.state_code	String	Optional	The code for the state or province
geo.district	String	Optional	The district of the geographical location
geo.city	String	Optional	The city of the geographical location
geo.zip_code	String	Optional	The postal code of the geographical location
geo.latitude	String	Optional	The latitude coordinate of the geographical location
geo.longitude	String	Optional	The longitude coordinate of the geographical location

HTTP Error Codes

HTTP Status	Reasons
400	(1) When provided Latitude and Longitude values are not valid (2) When provided timezone is not valid (3) When time zone detail couldn't be found for the provided IP address

How-To-Guides

Timezone Information for an Address

Pass the address using location query parameter to get the timezone information for an address.

$ curl --location --request GET ' https://api.apifreaks.com/v1.0/geolocation/timezone?apiKey=API-KEY&location=London,%20UK'
# Response
{
    "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
}

When getting timezone information using the location address, the response will also contain the geo field for location information.

Timezone Information for Location Coordinates

Pass the latitude and longitude of a location as query parameters lat and long to get the timezone information for provided coordinates.

$ curl 'https://api.apifreaks.com/v1.0/geolocation/timezone?apiKey=API-KEY&lat=-27.4748&long=153.017'
# Response
{
    "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 Timezone API

Get timezone from IPv4 or IPv6 address by passing the ip query parameter to the IP to timezone API. The response will include both timezone and geolocation details. If the ip is not provided, the API will default to using the request's IP address.

$ curl 'https://api.apifreaks.com/v1.0/geolocation/timezone?apiKey=API-KEY&ip=1.1.1.1'
# Response
{
    "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
}

When getting timezone information using the ip address, the response will also contain the geo field for geolocation information for the ip address location. To get the geolocation information in a specific language, provide the language code using the lang parameter. Default geolocation response is in English.

$ curl 'https://api.apifreaks.com/v1.0/geolocation/timezone?apiKey=API-KEY&ip=1.1.1.1&lang=es

The languages supported are:

en (English)
es(Spanish)
de (German)
fr (French)
ja (Japanese)
it (Italian)
cs (Czech)
ru (Russian)
cn (Chinese Simplifed)

Timezone Information for Calling Machine IP

Call the API without passing any location, coordinates, or IP address. It will use the calling machine's IP address to return the ip timezone information.

$ curl 'https://api.apifreaks.com/v1.0/geolocation/timezone?apiKey=API-KEY'

Pricing

To use the TimeZone API, API credits are required. Charges apply only for successful queries, defined by a 2xx status code. If a request results in a 4xx or 5xx status code, no credits will be deducted, and any credits already charged will be refunded.

For each successful request, 1 credit will be charged for time zone lookup. Utilize the Credits Usage API to efficiently monitor your recent consumption of both one-off and subscription credits. This API provides a streamlined way to track and manage your credit usage, ensuring you stay informed about your remaining balance and can optimize your resource allocation effectively.