API Access

TimeZoneDB provides simple RESTful interface API and returns structured XML or JSON responses. Our API converts latitude & longitude to time zone data. You also able to retrieve time zone information for a specific zone. You need to register a free API key to start using our services. Please consider to donate if you like our free service.

If you use this API for commercial purposes, please upgrade to premium service for more reliable and stable access.

References

  • Free API
  • Premium API

Endpoint

http://api.timezonedb.com

Parameters

Parameter Description
key Required. Your unique API key you get after register your account.
zone Required. Zone name of an area. You can refer the name from time zone list.
lat Required if zone not specified. Latitude of a city.
lng Required if zone not specified. Longitude of a city.
time Optional. Unix time. Default value: Current timestamp in Unix.
format Optional. xml or json format for the result. Default value: xml
callback Optional. Use for JavaScript JSON callback.

Response

Field Description
status Status of the API query. Either OK or FAIL.
message Error message if any parameters missing or invalid. Empty if no error.
countryCode ISO 3166 country code of the country.
zoneName The name of the time zone. Refer to time zone list.
abbreviation The abbreviation of time zone.
gmtOffset The time offset in seconds based on UTC time.
dst Whether Daylight Savinig Time (DST) is used. 1=Yes, 0=No
timestamp Current local time in Unix timestamp.

Examples

Get result for "Australia/Melbourne" in XML format:

http://api.timezonedb.com/?zone=Australia/Melbourne&key=YOUR_API_KEY
Output:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>OK</status>
	<message></message>
	<countryCode>AU</countryCode>
	<zoneName>Australia/Melbourne</zoneName>
	<abbreviation>EST</abbreviation>
	<gmtOffset>39600</gmtOffset>
	<dst>1</dst>
	<timestamp>1321217345</timestamp>
</result>

Get result using latitude and longitude in XML format:
http://api.timezonedb.com/?lat=53.7833&lng=-1.75&key=YOUR_API_KEY
Output:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>OK</status>
	<message></message>
	<countryCode>GB</countryCode>
	<zoneName>Europe/London</zoneName>
	<abbreviation>GMT</abbreviation>
	<gmtOffset>0</gmtOffset>
	<dst>0</dst>
	<timestamp>1321177965</timestamp>
</result>

Get result for "America/Toronto" in JSON format:
http://api.timezonedb.com/?zone=America/Toronto&format=json&key=YOUR_API_KEY
Output:
{"status":"OK","message":"","countryCode":"CA","zoneName":"America\/Toronto","abbreviation":"EST","gmtOffset":"-18000","dst":"0","timestamp":1321160245}

Time Zone Convertion (PHP)
To convert date/time between difference time zones, you may refer to following codes:
<?php
/* Description : Converts date/time from Europe/Paris to Asia/Tokyo
   Source      : http://timezonedb.com
   Date        : 23 December, 2011 */

$date = '25-12-2011 07:52:12'; // Current time in Europe/Paris

// Set system time as UTC
date_default_timezone_set('UTC');

// Get Europe/Paris GMT offset
$source = getGmtOffset('Europe/Paris');

// Get Asia/Tokyo GMT offset
$target = getGmtOffset('Asia/Tokyo');

// Difference
$diff = $target - $source;

// Convert date into Unix time
$unix = strtotime($date);

// Show date/time in Tokyo
echo date('d-m-Y H:i:s', $unix+$diff);

function getGmtOffset($zone){
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, 'http://api.timezonedb.com/?key=YOUR_API_KEY&zone=' . $zone . '&format=json');
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	$json = curl_exec($ch);
	curl_close($ch);
	$data = json_decode($json);
	return (int)$data->gmtOffset;
}
?>

Accessing TimeZoneDB API using JavaScript

Note: Using TimeZone API with JavaScript will expose your API key to public. Please avoid using this method for security concerns.

<html>
<head>
	<title>TimeZoneDB JSON Demo</title>
	<script src="//cdn.timezonedb.com/js/timezonedb.min.js" type="text/javascript"></script>
	<script type="text/javascript">
	<!--
	function displayZone(lat, lng){
		var tz = new TimeZoneDB;
		tz.getJSON({
			key: "YOUR_API_KEY",
			lat: lat,
			lng: lng
		}, function(data){
			alert(data.zoneName);
		});
	}
	//-->
	</script>
</head>
<body>
<button onclick="displayZone('53.7833', '-1.75');">Show Time Zone</button>
</body>
</html>

Third Party Libraries

Endpoint

http://vip.timezonedb.com/v2/

List All Time Zone

Get a list of time zone name supported by TimeZoneDB API.

Parameters

Parameter Description
key Required. Your unique API key you get after register your account.
format Optional. xml or json format for the result. Default value: xml
callback Optional. Use for JavaScript JSON callback.

Response

Field Description
status Status of the API query. Either OK or FAIL.
message Error message if any parameters missing or invalid. Empty if no error.
zones A list of supported time zone name.

Examples

Get a list of time zone name supported by TimeZoneDB API

http://vip.timezonedb.com/v2/list-time-zone?key=YOUR_API_KEY
Output:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>OK</status>
	<message/>
	<zones>
		<zone>
			<countryCode>AD</countryCode>
			<countryName>Andorra</countryName>
			<zoneName>Europe/Andorra</zoneName>
		</zone>
		<zone>
			<countryCode>AE</countryCode>
			<countryName>United Arab Emirates</countryName>
			<zoneName>Asia/Dubai</zoneName>
		</zone>
		<zone>
			<countryCode>AF</countryCode>
			<countryName>Afghanistan</countryName>
			<zoneName>Asia/Kabul</zoneName>
		</zone>
		<zone>
			<countryCode>AG</countryCode>
			<countryName>Antigua and Barbuda</countryName>
			<zoneName>America/Antigua</zoneName>
		</zone>
		<zone>
			<countryCode>AI</countryCode>
			<countryName>Anguilla</countryName>
			<zoneName>America/Anguilla</zoneName>
		</zone>
		<zone>
			<countryCode>AL</countryCode>
			<countryName>Albania</countryName>
			<zoneName>Europe/Tirane</zoneName>
		</zone>
		.
		.
		.
	</zones>
</result>

Get Time Zone by Zone Name, City Name, Latitude & Longitude, or IP Address

Get current timestamp and time zone by time zone name, city name, latitude & longitude, or IP address.

Parameters

Parameter Description
key Required. Your unique API key you get after register your account.
format Optional. xml or json format for the result. Default value: xml
callback Optional. Use for JavaScript JSON callback.
by Required. Method to get time zone details.
  • zone - Lookup time zone using time zone name.
  • position - Lookup time zone using latitude & longitude of a city.
  • city - Lookup time zone using a city name.
  • ip - Lookup time zone by IP address.
zone Required if lookup by zone. Zone name of an area. You can refer the name from time zone list.
lat Required if lookup by position. Latitude of a city.
lng Required if lookup by position. Longitude of a city.
city Required if lookup by city. A city name.
country Required if lookup by city. A ISO 3166-2 country code of the city.
ip Required if lookup by ip. A valid IPv4 address.
time Optional. Unix time. Default value: Current timestamp in Unix.

Response

Field Description
status Status of the API query. Either OK or FAIL.
message Error message if any parameters missing or invalid. Empty if no error.
countryCode ISO 3166 country code of the country.
countryName Country name.
regionName The name of state/region of the city.
cityName City name.
zoneName The name of the time zone. Refer to time zone list.
abbreviation The abbreviation of time zone.
gmtOffset The time offset in seconds based on UTC time.
dst Whether Daylight Savinig Time (DST) is used. 1=Yes, 0=No
timestamp Current local time in Unix timestamp.

Examples

Get time zone by zone name.

http://vip.timezonedb.com/v2/get-time-zone?key=YOUR_API_KEY&by=zone&zone=America/Los_Angeles
Output:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>OK</status>
	<message/>
	<countryCode>US</countryCode>
	<countryName>United States</countryName>
	<regionName/>
	<cityName/>
	<zoneName>America/Los_Angeles</zoneName>
	<abbreviation>PDT</abbreviation>
	<gmtOffset>-25200</gmtOffset>
	<dst>1</dst>
	<timestamp>1459730161</timestamp>
</result>

Get time zone by latitude & longitude.

http://vip.timezonedb.com/v2/get-time-zone?key=YOUR_API_KEY&by=position&lat=48.8583654&lng=2.2960654
Output:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>OK</status>
	<message/>
	<countryCode>FR</countryCode>
	<countryName>France</countryName>
	<regionName>Ile-de-France</regionName>
	<cityName>Tour Eiffel</cityName>
	<zoneName>Europe/Paris</zoneName>
	<abbreviation>CEST</abbreviation>
	<gmtOffset>7200</gmtOffset>
	<dst>1</dst>
	<timestamp>1459872882</timestamp>
</result>

Get time zone by city name.

http://vip.timezonedb.com/v2/get-time-zone?key=YOUR_API_KEY&by=city&country=IN&city=Kolkata
Output:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>OK</status>
	<message/>
	<countryCode>IN</countryCode>
	<countryName>India</countryName>
	<regionName>Bengal</regionName>
	<cityName>Kolkata</cityName>
	<zoneName>Asia/Kolkata</zoneName>
	<abbreviation>IST</abbreviation>
	<gmtOffset>19800</gmtOffset>
	<dst>0</dst>
	<timestamp>1456166395</timestamp>
</result>

Get time zone by IP address.

http://vip.timezonedb.com/v2/get-time-zone?key=YOUR_API_KEY&by=ip&ip=216.58.199.46
Output:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>OK</status>
	<message/>
	<countryCode>US</countryCode>
	<countryName>United States</countryName>
	<regionName>California</regionName>
	<cityName>Mountain View</cityName>
	<zoneName>America/Los_Angeles</zoneName>
	<abbreviation>PST</abbreviation>
	<gmtOffset>-28800</gmtOffset>
	<dst>0</dst>
	<timestamp>1362691163</timestamp>
</result>