Google Maps API Web Services

The Google Time Zone API

The Google Time Zone API provides a simple interface to request the time zone for a location on the earth, as well as that location's time offset from UTC.

  1. Introduction
  2. Audience
  3. API Key
  4. Usage Limits
  5. Time Zone Requests
    1. Output Formats
    2. Parameter Usage
  6. Time Zone Responses
  7. Example Requests

Introduction

The Time Zone API provides time offset data for locations on the surface of the earth. Requesting the time zone information for a specific Latitude/Longitude pair will return the name of that time zone, the time offset from UTC, and the Daylight Savings offset.

You access the Google Time Zone API through an HTTPS interface.

Audience

This document is intended for website and mobile developers who want to include time data on maps provided by one of the Google Maps APIs. It provides an introduction to using the API and reference material on the available parameters.

API Key

Note: Maps for Business users must include client and signature parameters with their requests instead of a key.

All Time Zone API applications should use an API key. Including a key in your request:

  • Allows you to monitor your application's API usage in the APIs Console.
  • Enables per-key instead of per-IP-address quota limits.
  • Ensures that Google can contact you about your application if necessary.

The Time Zone API uses an API key to identify your application. API keys are managed through the Google APIs console. To create your key:

  1. Visit the APIs console at https://code.google.com/apis/console and log in with your Google Account.
  2. Click the Services link from the left-hand menu in the APIs Console, then activate the Time Zone API service.
  3. Once the service has been activated, your API key is available from the API Access page, in the Simple API Access section. Time Zone API applications use the Key for server apps.

To specify a key in your request, include it as the value of a key parameter.

Note: By default, a key can be used from any server. We strongly recommend that you restrict the use of your key by IP address to servers that you administer. You can specify which IP addresses are allowed to use your API key by clicking the Edit allowed referers... link in the API console.

Note: HTTPS is enforced for requests that include an API key.

Usage Limits

The Google Time Zone API has the following limits in place:

Users of the free API:
  • 2,500 requests per 24 hour period.
Maps for Business customers:
  • 100,000 requests per 24 hour period.

This limit is enforced to prevent abuse and/or repurposing of the Time Zone API, and the limit may be changed in the future without notice. Additionally, we enforce a request rate limit to prevent abuse of the service. If you exceed the 24-hour limit or otherwise abuse the service, the Time Zone API may stop working for you temporarily. If you continue to exceed this limit, your access to the Time Zone API may be blocked.

For complete details on allowed usage, consult the Maps API Terms of Service License Restrictions.

Time Zone Requests

The Time Zone 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 Google Time Zone API URL must be of the following form:

https://maps.googleapis.com/maps/api/timezone/outputFormat?parameters

Important: You must submit requests via https, not http.

Output Formats

Outputs formats are specified using the trailing service flag in the request URL. The Time Zone API supports the following output formats:

  • /json returns results in JavaScript Object Notation (JSON).
  • /xml returns results in XML, wrapped within a <TimeZoneResponse> node.

Parameter Usage

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 the timestamp to determine whether or not Daylight Savings should be applied. Times before 1970 can be expressed as negative values.
  • sensor specifies whether the application requesting data is using a sensor (such as a GPS device) to determine the user's location. Accepts true or false.

Maps API for Business users must include valid client and signature parameters with their requests. Please refer to Maps API for Business Web Services for more information.

Optional Parameters

  • key — Your application's API key. This key identifies your application for purposes of quota management. Learn how to get a key from the APIs Console.
  • 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 to en.

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 specified timestamp.
  • 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".
  • 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_QUERY_LIMIT indicates the requestor has exceeded quota.
    • REQUEST_DENIED indicates that the 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.
  • error_message: more detailed information about the reasons behind the given status code, if other than OK.

    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.

JSON

Request:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&sensor=true_or_false&key=API_KEY

Response:

{
   "dstOffset" : 0.0,
   "rawOffset" : -28800.0,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Standard Time"
}
    
XML

Request:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331161200&sensor=true_or_false&key=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.

JSON

Request:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331766000&sensor=true_or_false&key=API_KEY

Response:

{
   "dstOffset" : 3600.0,
   "rawOffset" : -28800.0,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Daylight Time"
}
    
XML

Request:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&sensor=true_or_false&key=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.

JSON

Request:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&sensor=true_or_false&key=API_KEY

Response:

{
   "dstOffset" : 3600.0,
   "rawOffset" : -28800.0,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Hora de verano del Pacífico"
}
    
XML

Request:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&sensor=true_or_false&key=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>

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.