This service is also available in the Java Client, Python Client, Go Client and Node.js Client for Google Maps Services.
Introduction
The Time Zone API provides a simple interface to request the time zone for locations on the surface of the earth, as well as the time offset from UTC for each of those locations. You request the time zone information for a specific latitude/longitude pair and date. The API returns the name of that time zone, the time offset from UTC, and the daylight savings offset.
Before you begin
This document is intended for website and mobile developers who want to include time data on maps provided by one of the Google Maps Platform APIs. It provides an introduction to using the API and reference material on the available parameters.
Before you start developing with the Time Zone API, review the authentication requirements (you need an API key) and the API usage and billing information (you need to enable billing on your project).
Time zone requests
Time Zone API requests are constructed as a URL string. The API returns time zone data for a point on the earth, specified by a latitude/longitude pair. Note that time zone data may not be available for locations over water, such as oceans or seas.
A Time Zone API request takes the following form:
https://maps.googleapis.com/maps/api/timezone/outputFormat?parameters
where outputFormat
may be either of the following values:
json
(recommended), indicates output in JavaScript Object Notation (JSON); orxml
, indicates output in XML, wrapped within a<TimeZoneResponse>
node.
Important: You must submit requests via
https
, not http
.
Note: URLs must be properly encoded to be valid and are limited to 8192 characters for all web services. Be aware of this limit when constructing your URLs. Note that different browsers, proxies, and servers may have different URL character limits as well.
Request parameters
As is standard in all URLs, parameters are separated
using the ampersand (&
) character. The list of parameters
and their possible values are denoted below.
Required parameters
location
: a comma-separated lat,lng tuple (eg.location=-33.86,151.20
), representing the location to look up.timestamp
specifies the desired time as seconds since midnight, January 1, 1970 UTC. The Time Zone API uses thetimestamp
to determine whether or not Daylight Savings should be applied, based on the time zone of thelocation
. Note that the API does not take historical time zones into account. That is, if you specify a pasttimestamp
, the API does not take into account the possibility that thelocation
was previously in a different time zone.key
— Your application's API key. This key identifies your application for purposes of quota management. Learn how to get a key.Note: Google Maps Platform Premium Plan customers may use either an API key, or a valid client ID and digital signature, in your Time Zone requests. Get more information on authentication parameters for Premium Plan customers.
Optional parameters
language
— The language in which to return results. See the list of supported domain languages. Note that we often update supported languages so this list may not be exhaustive. Defaults toen
.
Time Zone Responses
For each valid request, the time zone service will return a response in the format indicated within the request URL. Each response will contain the following elements:
dstOffset
: the offset for daylight-savings time in seconds. This will be zero if the time zone is not in Daylight Savings Time during the specifiedtimestamp
.rawOffset
: the offset from UTC (in seconds) for the given location. This does not take into effect daylight savings.timeZoneId
: a string containing the ID of the time zone, such as "America/Los_Angeles" or "Australia/Sydney". These IDs are defined by Unicode Common Locale Data Repository (CLDR) project, and currently available in file timezone.xml. When a timezone has several IDs, the canonical one is returned. In timezone.xml, this is the first alias of each timezone. For example, "Asia/Calcutta" is returned, not "Asia/Kolkata".timeZoneName
: a string containing the long form name of the time zone. This field will be localized if the language parameter is set. eg. "Pacific Daylight Time" or "Australian Eastern Daylight Time"status
: a string indicating the status of the response.OK
indicates that the request was successful.INVALID_REQUEST
indicates that the request was malformed.OVER_DAILY_LIMIT
indicates any of the following:- The API key is missing or invalid.
- Billing has not been enabled on your account.
- A self-imposed usage cap has been exceeded.
- The provided method of payment is no longer valid (for example, a credit card has expired).
See the Maps FAQ to learn how to fix this.
OVER_QUERY_LIMIT
indicates the requestor has exceeded quota.REQUEST_DENIED
indicates that the API did not complete the request. Confirm that the request was sent over HTTPS instead of HTTP.UNKNOWN_ERROR
indicates an unknown error.ZERO_RESULTS
indicates that no time zone data could be found for the specified position or time. Confirm that the request is for a location on land, and not over water.
errorMessage
: more detailed information about the reasons behind the given status code, if other thanOK
.Note: This field is not guaranteed to be always present, and its content is subject to change.
Calculating the local time
The local time of a given location is the sum of the
timestamp
parameter, and the dstOffset
and
rawOffset
fields from the result.
Example requests
This section includes some sample queries that demonstrate features of the API.
The below query performs a time zone request for Nevada, USA. The timestamp is set to March 8th, 2012.
Request:
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510×tamp=1331161200&key=YOUR_API_KEY
Response:
{ "dstOffset" : 0, "rawOffset" : -28800, "status" : "OK", "timeZoneId" : "America/Los_Angeles", "timeZoneName" : "Pacific Standard Time" }
Request:
https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510×tamp=1331161200&key=YOUR_API_KEY
Response:
<TimeZoneResponse> <status>OK</status> <raw_offset>-28800.0000000</raw_offset> <dst_offset>0.0000000</dst_offset> <time_zone_id>America/Los_Angeles</time_zone_id> <time_zone_name>Pacific Standard Time</time_zone_name> </TimeZoneResponse>
The below query performs a time zone request for Nevada, USA. The location is the same as the above request, but the timestamp is set to March 15th, 2012. The response now includes a Daylight Savings Time offset.
Request:
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510×tamp=1331766000&key=YOUR_API_KEY
Response:
{ "dstOffset" : 3600, "rawOffset" : -28800, "status" : "OK", "timeZoneId" : "America/Los_Angeles", "timeZoneName" : "Pacific Daylight Time" }
Request:
https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510×tamp=1331766000&key=YOUR_API_KEY
Response:
<TimeZoneResponse> <status>OK</status> <raw_offset>-28800.0000000</raw_offset> <dst_offset>3600.0000000</dst_offset> <time_zone_id>America/Los_Angeles</time_zone_id> <time_zone_name>Pacific Daylight Time</time_zone_name> </TimeZoneResponse>
This example is similar to the above two, but sets a language parameter. The response will now be localized to Spanish.
Request:
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510×tamp=1331766000&language=es&key=YOUR_API_KEY
Response:
{ "dstOffset" : 3600, "rawOffset" : -28800, "status" : "OK", "timeZoneId" : "America/Los_Angeles", "timeZoneName" : "Hora de verano del Pacífico" }
Request:
https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510×tamp=1331766000&language=es&key=YOUR_API_KEY
Response:
<TimeZoneResponse> <status>OK</status> <raw_offset>-28800.0000000</raw_offset> <dst_offset>3600.0000000</dst_offset> <time_zone_id>America/Los_Angeles</time_zone_id> <time_zone_name>Hora de verano del Pacífico</time_zone_name> </TimeZoneResponse>
The sensor
parameter
The Google Maps API previously required that you include the
sensor
parameter to indicate whether your application used a
sensor to determine the user's location. This parameter is no longer
required.