google-maps - Google Directions API 使用 UTC 还是本地时间？

Question

我正在使用 Google Directions API 开发一个交通导航应用程序.

API 要求我提交出发时间 (departure_time) 以进行公交查询。

该参数是否需要将本地时间转换为UTC时间？

我无法通过 API 的响应验证它，因为其中没有返回准确的时间。

Answer 1

该文档有错误

显然是 Google 团队写的 that doc page犯了一个错误，后来改正了。

该页面上已找不到您举报的号码 1343605500。今天该页面上的号码是 1343641500。我怀疑您之前确实在该页面上看到过该号码。谷歌搜索(足够讽刺的是)site:https://developers.google.com 1343605500 确实将该页面列为热门页面。显然，命中是基于旧的错误页面的缓存副本。即使是 Google 也逃不出 Google 的魔掌。

以 UTC/GMT 工作

Is it necessary to convert the local time to UTC time for this parameter?

是的。

该 API 使用 GMT/UTC(无时区偏移)，只有当您仔细考虑时才有意义。几乎总是，处理日期时间的最佳实践是在 UTC 中执行业务逻辑、序列化、数据库记录等。 ，然后转换为本地时间仅用于呈现给用户。

仅查看示例 URL 本身就表明它采用 UTC 格式。对本地时区的唯一可能引用是“布鲁克林”一词，这当然不是时区的明确唯一标识符。

http://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&sensor=false&departure_time=1343641500&mode=transit

当然，文档说 API 使用 UTC/GMT:

the desired time of departure as seconds since midnight, January 1, 1970 UTC

写得不好

这种困惑源于 documentation page 中的糟糕写作。 。他们需要在“9:45 am”后面附加一个关键的“UTC”或“GMT”。将纽约和 9:45 同时提及意味着本地时间，而该示例实际上是布鲁克林本地时间早上 5:45。

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.

旧数字与新数字

旧号码:1343605500(在 answer by davidg 中报告，并通过谷歌搜索)

新号码:1343641500(2013-12发现)

数字(如果他们实际上指的是纽约的 9:45):1343655900。

示例代码

我不做 JavaScript。因此，我使用复杂的 Joda-Time 来呈现一些 Java 代码。 2.3 在 Java 7 中运行的日期时间处理库。我使用旧的(错误的)和新的(正确的)数字来显示 UTC 和纽约时区的日期时间。此外，我计算了自纪元以来到纽约 2012 年 7 月 30 日上午 9:45 的秒数，以产生第三个秒数。

Google API 使用秒，而 Joda-Time 使用毫秒，因此我乘以或除以一千。

// © 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 ) );

运行时...

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