Wednesday, October 10, 2012

Sleepy Colleagues and Sydney in Summer: Time Zone functionality in the Maps API

Working in Google’s Sydney office gives a person a particular appreciation for the time zones of the world.  The time difference between Sydney and our headquarters in Mountain View, California can make it difficult to connect with teams and find suitable meeting times.  More often than not, we Sydney engineers have been woken by 2am calendar reminders and email notifications sent from colleagues from around the world.  Sleep deprivation has just been a part of the job!  

Fortunately, help is at hand (especially for our sleep-patterns) with the release of time zone functionality in the Google Maps API.

The API returns information about (you guessed it) the time zone of a particular location on Earth at a particular point in time. The response contains information such as the IANA Time Zone ID, long form name, offset from UTC and any offset due to daylight savings.

For example, here’s a request for time zone information for Sydney on the 5th of January, 2013:

https://maps.googleapis.com/maps/api/timezone/json?location=-33.86,151.20&timestamp=1357347600.0&sensor=false

The response is as follows:

{
  "dstOffset" : 3600.0,
  "rawOffset" : 36000.0,
  "status" : "OK",
  "timeZoneId" : "Australia/Sydney",
  "timeZoneName" : "Australian Eastern Daylight Time"
}


As you can see, we’re in Australian Eastern Daylight Time with a base offset of 10 hours from UTC. We also have an extra hour of evening light (as shown by dstOffset), perfect for the wonderful time Sydneysiders are having at the Sydney Festival opening night.

Regarding usage, developers have access to the API for up to 2,500 requests per day, while Google Maps API for Business customers receive 100,000 requests.  Full documentation is available here: http://developers.google.com/maps/documentation/timezone.

We hope that you find this new functionality useful, and that your colleagues elsewhere in the world, wherever they happen to be, can get a night of peaceful, undisturbed sleep.

Posted by Jez Fletcher, Software Engineer, Google Maps APIs