Reference: Get Time Zone

http://api.timezonedb.com/v2.1/get-time-zone

Get local time of a city by its name, time zone, latitude & longtiude, or IP address.

Other End Points

Parameters

Parameter Description
key
REQUIRED
Your unique API key you get after register your account.
format
OPTIONAL
The response format from API. It can be either xml or json.

DEFAULT: xml
callback
OPTIONAL
Use for JavaScript JSON callback.
fields
OPTIONAL
Customize the field to display in response. Use commas ("," without spaces) to separate the field names.

FIELDS: countryCode, countryName, regionName, cityName, zoneName, abbreviation, gmtOffset, dst, zoneStart, zoneEnd, nextAbbreviation, timestamp, formatted
DEFAULT: all
by
REQUIRED
The method of lookup.
  • zone - Lookup local time by using a time zone name.
  • position - Lookup local time by using latitude & longitude of a city.
  • PREMIUM
    city - Lookup time zone by searching city name.
  • PREMIUM
    ip - Lookup time zone based on visitor IP address.
zone
REQUIRED
A time zone abbreviation or time zone name. Required if lookup by zone method.
lat
REQUIRED
Latitude of a city. Required if lookup by position method.
lng
REQUIRED
Longitude of a city. Required if lookup by position method.
country
REQUIRED
A valid ISO 3166 country code. Required if lookup by city method.
region
OPTIONAL
A valid region code of United States. Optional when lookup by city method to limit the search result.
city
REQUIRED
The name of a city. Use asterisk (*) for wildcard search. Required if lookup by city method.
page
OPTIONAL
Navigate to other page when result is more than 10 records.
time
OPTIONAL
Unix time in UTC.

DEFAULT: Current UTC time.

Responses

Field Description
status Status of the API query. Either OK or FAILED.
message Error message. Empty if no error.
countryCode Country code of the time zone.
countryName Country name of the time zone.
regionName
PREMIUM
Region / State name of the time zone.
cityName
PREMIUM
City / Place name of the time zone.
zoneName The time zone name.
abbreviation Abbreviation of the time zone.
gmtOffset The time offset in seconds based on UTC time.
dst Whether Daylight Saving Time (DST) is used. Either 0 (No) or 1 (Yes).
zoneStart The Unix time in UTC when current time zone start.
zoneEnd The Unix time in UTC when current time zone end.
timestamp Current local time in Unix time. Minus the value with gmtOffset to get UTC time.
formatted Formatted timestamp in Y-m-d h:i:s format. E.g.: 2023-10-04 04:16:45
totalPage The total page of result when exceed 25 records.
currentPage Current page when navigating.

Usage Examples

Get current local time at Statue of Liberty using latitude & longitude

Query
http://api.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=xml&by=position&lat=40.689247&lng=-74.044502
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>OK</status>
  <message/>
  <countryCode>US</countryCode>
  <countryName>United States</countryName>
  <regionName>New Jersey</regionName>
  <cityName>Jersey City</cityName>
  <zoneName>America/New_York</zoneName>
  <abbreviation>EDT</abbreviation>
  <gmtOffset>-14400</gmtOffset>
  <dst>1</dst>
  <zoneStart>1678604400</zoneStart>
  <zoneEnd>1699164000</zoneEnd>
  <nextAbbreviation>EST</nextAbbreviation>
  <timestamp>1696378605</timestamp>
  <formatted>2023-10-04 00:16:45</formatted>
</result>
Query
http://api.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=json&by=position&lat=40.689247&lng=-74.044502
Response
{
    "status": "OK",
    "message": "",
    "countryCode": "US",
    "countryName": "United States",
    "regionName": "New Jersey",
    "cityName": "Jersey City",
    "zoneName": "America\/New_York",
    "abbreviation": "EDT",
    "gmtOffset": -14400,
    "dst": "1",
    "zoneStart": 1678604400,
    "zoneEnd": 1699164000,
    "nextAbbreviation": "EST",
    "timestamp": 1696378605,
    "formatted": "2023-10-04 00:16:45"
}

 

Get current local time in Chicago, USA

Query
http://api.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=xml&by=zone&zone=America/Chicago
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>OK</status>
  <message/>
  <countryCode>US</countryCode>
  <countryName>United States</countryName>
  <regionName/>
  <cityName/>
  <zoneName>America/Chicago</zoneName>
  <abbreviation>CDT</abbreviation>
  <gmtOffset>-18000</gmtOffset>
  <dst>1</dst>
  <zoneStart>1678608000</zoneStart>
  <zoneEnd>1699167599</zoneEnd>
  <nextAbbreviation>CST</nextAbbreviation>
  <timestamp>1696375005</timestamp>
  <formatted>2023-10-03 23:16:45</formatted>
</result>
Query
http://api.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=json&by=zone&zone=America/Chicago
Response
{
    "status": "OK",
    "message": "",
    "countryCode": "US",
    "countryName": "United States",
    "regionName": "",
    "cityName": "",
    "zoneName": "America\/Chicago",
    "abbreviation": "CDT",
    "gmtOffset": -18000,
    "dst": "1",
    "zoneStart": 1678608000,
    "zoneEnd": 1699167599,
    "nextAbbreviation": "CST",
    "timestamp": 1696375005,
    "formatted": "2023-10-03 23:16:45"
}

 

Get current local time in Taipei, Taiwan when UTC is 04 October, 2023 04:16:45 AM

Query
http://api.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=xml&by=zone&zone=Asia/Taipei&time=1696393005
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>OK</status>
  <message/>
  <countryCode>TW</countryCode>
  <countryName>Taiwan</countryName>
  <regionName/>
  <cityName/>
  <zoneName>Asia/Taipei</zoneName>
  <abbreviation>CST</abbreviation>
  <gmtOffset>28800</gmtOffset>
  <dst>0</dst>
  <zoneStart>307551600</zoneStart>
  <zoneEnd/>
  <nextAbbreviation/>
  <timestamp>1696421805</timestamp>
  <formatted>2023-10-04 12:16:45</formatted>
</result>
Query
http://api.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=json&by=zone&zone=Asia/Taipei&time=1696393005
Response
{
    "status": "OK",
    "message": "",
    "countryCode": "TW",
    "countryName": "Taiwan",
    "regionName": "",
    "cityName": "",
    "zoneName": "Asia\/Taipei",
    "abbreviation": "CST",
    "gmtOffset": 28800,
    "dst": "0",
    "zoneStart": 307551600,
    "zoneEnd": null,
    "nextAbbreviation": null,
    "timestamp": 1696421805,
    "formatted": "2023-10-04 12:16:45"
}

 

Get local time zone for City of Buffalo in US (Premium Subscription Only)

Query
http://vip.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=xml&by=city&city=City+of+Buffalo&country=US
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>FAILED</status>
  <message>Record not found.</message>
  <totalPage>1</totalPage>
  <currentPage>1</currentPage>
  <zones/>
</result>
Query
http://vip.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=json&by=city&city=City+of+Buffalo&country=US
Response
{
    "status": "FAILED",
    "message": "Record not found.",
    "totalPage": 1,
    "currentPage": 1,
    "zones": []
}

 

Get time zone by IP address with custom fields (Premium Subscription Only)

Query
http://vip.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=xml&by=ip&ip=3.214.184.223&fields=countryCode,cityName,gmtOffset,dst
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>OK</status>
  <message/>
  <countryCode>US</countryCode>
  <cityName>Ashburn</cityName>
  <gmtOffset>-14400</gmtOffset>
  <dst>1</dst>
</result>
Query
http://vip.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=json&by=ip&ip=3.214.184.223&fields=countryCode,cityName,gmtOffset,dst
Response
{
    "status": "OK",
    "message": "",
    "countryCode": "US",
    "cityName": "Ashburn",
    "gmtOffset": -14400,
    "dst": "1"
}