Does the Google Directions API use UTC or Local Time? - google-maps

Question

I am developing a transit navigation app using the Google Directions API.
The API requires me to submit a departure time (departure_time) for transit queries.
Is it necessary to convert the local time to UTC time for this parameter?
I could not validate it through the API's response, as there is no accurate time returned in it.

Answer 1

That Doc Was In Error
Apparently the Google team writing that doc page made an error and later fixed it.
The number you report 1343605500 is no longer found on that page. Today the number on that page is 1343641500. I suspect you did indeed see that number on that page previously. Googling (ironically enough) for site:https://developers.google.com 1343605500 does list that page as a hit. Apparently the hit is based on a cached copy of the old erroneous page. Even Google cannot escape the reach of Google.
Work in UTC/GMT
Is it necessary to convert the local time to UTC time for this parameter?
Yes.
The API works with GMT/UTC (no time zone offset), which only makes sense when you think about it. Almost always, the best practice for handling date-time is to perform your business logic, serialization, database records, and so on in UTC, then convert to local time only for presentation to the user.
Just looking at the example URL itself suggests it is in UTC. The only possible reference to a local time zone would be the word "Brooklyn" which is certainly not a clear unique identifier for a time zone.
http://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&sensor=false&departure_time=1343641500&mode=transit
And of course the doc says the API uses UTC/GMT:
the desired time of departure as seconds since midnight, January 1, 1970 UTC
Poor Writing
The confusion stems from the poor writing in that documentation page. They need to append a crucial "UTC" or "GMT" to that "9:45 am". Mentioning New York and 9:45 in the same breath implies local time, whereas that example is truly 5:45 in the morning local time in Brooklyn.
The below request searches for Transit Directions from Brooklyn, New York to Queens, New York. When requesting transit directions, be sure to specify either a departure_time or arrival_time.
Note that in this example the departure time is specified as July 30, 2012 at 09:45 am. Update the parameter to a point in the future before submitting the request.
Old Versus New Numbers
Old number: 1343605500 (reported in the answer by davidg, and by googling)
New number: 1343641500 (found 2013-12)
Number if they had actually meant 9:45 in New York: 1343655900.
Example Code
I don't do JavaScript. So instead, I present some Java code using the sophisticated Joda-Time 2.3 date-time handling library running in Java 7. I use both the old (erroneous) and new (correct) numbers to show the date-time in both UTC and New York time zones. Furthermore, I calculate the number of seconds since epoch would have been used to get to 9:45 am July 30 2012 in New York, to produce a third number of seconds.
The Google API uses seconds, while Joda-Time uses milliseconds, so I multiply or divide by a thousand.
// © 2013 Basil Bourque. This source code may be used freely forever by anyone taking full responsibility for doing so.
// import org.joda.time.*;
DateTimeZone timeZone_NewYork = DateTimeZone.forID( "America/New_York" );
// On this page:
// https://developers.google.com/maps/documentation/directions/#ExampleRequests
// …look for the following two paragraphs…
// --
// The below request searches for Transit Directions from Brooklyn, New York to Queens, New York. When requesting transit directions, be sure to specify either a departure_time or arrival_time.
// Note that in this example the departure time is specified as July 30, 2012 at 09:45 am. Update the parameter to a point in the future before submitting the request.
// --
// Below that text, find this URL:
// http://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&sensor=false&departure_time=1343641500&mode=transit
// Extract that departure time of 1,343,641,500 seconds since the Unix Epoch of beginning of 1970 UTC.
// Apparently in the past that page erroneously used the number 1343605500 where today it uses 1343641500.
// Use the correct number found on that page today, 2013-12-25: 1343641500.
DateTime dateTimeInUtcWithNewNumber = new DateTime ( ( 1343641500L * 1000L ), DateTimeZone.UTC );
DateTime dateTimeInNewYorkWithNewNumber = dateTimeInUtcWithNewNumber.toDateTime( timeZone_NewYork );
System.out.println( "dateTimeInUtcWithNewNumber: " + dateTimeInUtcWithNewNumber );
System.out.println( "dateTimeInNewYorkWithNewNumber: " + dateTimeInNewYorkWithNewNumber );
// Use the old erroneous number previously found on that page: 1343605500.
DateTime dateTimeInUtcWithOldNumber = new DateTime ( ( 1343605500L * 1000L ), DateTimeZone.UTC );
DateTime dateTimeInNewYorkWithOldNumber = dateTimeInUtcWithOldNumber.toDateTime( timeZone_NewYork );
System.out.println( "dateTimeInUtcWithOldNumber: " + dateTimeInUtcWithOldNumber );
System.out.println( "dateTimeInNewYorkWithOldNumber: " + dateTimeInNewYorkWithOldNumber );
// Calculating the number that should have been used if the Google team had actually meant 9:45 AM local time in New York: 1343655900.
DateTime dateTimeInNewYork_2012_07_30_09_45 = new DateTime ( 2012, 7, 30, 9, 45, 0, timeZone_NewYork );
System.out.println( "dateTimeInNewYork_2012_07_30_09_45: " + dateTimeInNewYork_2012_07_30_09_45 );
System.out.println( "dateTimeInNewYork_2012_07_30_09_45 in seconds since Unix epoch: " + ( dateTimeInNewYork_2012_07_30_09_45.getMillis() / 1000L ) );
When run…
dateTimeInUtcWithNewNumber: 2012-07-30T09:45:00.000Z
dateTimeInNewYorkWithNewNumber: 2012-07-30T05:45:00.000-04:00
dateTimeInUtcWithOldNumber: 2012-07-29T23:45:00.000Z
dateTimeInNewYorkWithOldNumber: 2012-07-29T19:45:00.000-04:00
dateTimeInNewYork_2012_07_30_09_45: 2012-07-30T09:45:00.000-04:00
dateTimeInNewYork_2012_07_30_09_45 in seconds since Unix epoch: 1343655900