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 | 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.: 2024-12-11 20:46:38 |
| 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>EST</abbreviation> <gmtOffset>-18000</gmtOffset> <dst>0</dst> <zoneStart>1730613600</zoneStart> <zoneEnd>1741503600</zoneEnd> <nextAbbreviation>EDT</nextAbbreviation> <timestamp>1733931998</timestamp> <formatted>2024-12-11 15:46:38</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": "EST",
"gmtOffset": -18000,
"dst": "0",
"zoneStart": 1730613600,
"zoneEnd": 1741503600,
"nextAbbreviation": "EDT",
"timestamp": 1733931999,
"formatted": "2024-12-11 15:46:39"
}
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>CST</abbreviation> <gmtOffset>-21600</gmtOffset> <dst>0</dst> <zoneStart>1730617200</zoneStart> <zoneEnd>1741507199</zoneEnd> <nextAbbreviation>CDT</nextAbbreviation> <timestamp>1733928399</timestamp> <formatted>2024-12-11 14:46:39</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": "CST",
"gmtOffset": -21600,
"dst": "0",
"zoneStart": 1730617200,
"zoneEnd": 1741507199,
"nextAbbreviation": "CDT",
"timestamp": 1733928399,
"formatted": "2024-12-11 14:46:39"
}
Get current local time in Taipei, Taiwan when UTC is 11 December, 2024 08:46:39 PM
Query
http://api.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=xml&by=zone&zone=Asia/Taipei&time=1733949999
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>1733978799</timestamp> <formatted>2024-12-12 04:46:39</formatted> </result>
Query
http://api.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=json&by=zone&zone=Asia/Taipei&time=1733949999
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": 1733978799,
"formatted": "2024-12-12 04:46:39"
}
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=18.117.71.213&fields=countryCode,cityName,gmtOffset,dst
Response
<?xml version="1.0" encoding="UTF-8"?> <result> <status>OK</status> <message/> <countryCode>US</countryCode> <cityName>Columbus</cityName> <gmtOffset>-18000</gmtOffset> <dst>0</dst> </result>
Query
http://vip.timezonedb.com/v2.1/get-time-zone?key=YOUR_API_KEY&format=json&by=ip&ip=18.117.71.213&fields=countryCode,cityName,gmtOffset,dst
Response
{
"status": "OK",
"message": "",
"countryCode": "US",
"cityName": "Columbus",
"gmtOffset": -18000,
"dst": "0"
}