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.

 

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.

 

Responses

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
<html>
<head>
	<title>TimeZoneDB JSON Demo</title>
	<script src="https://timezonedb.googlecode.com/files/timezonedb.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>

 

Free timezone database of world countries.