以上で完了です。

開発を始めるには、デベロッパー ドキュメント をご覧下さい。

Google Maps Time Zone API をアクティベートする

まず初めに Google Developers Console で次の作業を行います。

  1. プロジェクトを作成または選択する
  2. Google Maps Time Zone API をアクティベートする
  3. 適切なキーを作成する
続ける

デベロッパー ガイド

Google Maps Time Zone API は地球上のある地点のタイムゾーンと、その地点の UTC からのタイム オフセットをリクエストするシンプルなインターフェースを提供します。

このサービスは、Java Client、Python Client、Go Client、および Node.js Client for Google Maps Servicesでも使用することができます。

このドキュメントは、Google Maps API のいずれかが提供するマップにタイムデータを含めるウェブサイトやモバイル端末のデベロッパーを対象としています。また、API の使用の概要や使用可能なパラメータに関するリファレンス マテリアルを示しています。

はじめに

Google Maps Time Zone API は、地表のさまざまな地点のタイム オフセット データを提供します。特定の緯度と経度のペアと、日付におけるタイムゾーン情報をリクエストすると、API はタイムゾーンの名前、UTC からのタイム オフセット、夏時間のオフセットを返します。

Google Maps Time Zone API には HTTPS インターフェースを使用してアクセスします。

Time Zone API を使用した開発を始める前に、認証要件(API キーが必要です)と API の使用制限について確認してください。

タイムゾーン リクエスト

Google Maps Time Zone API リクエストは URL 文字列として構成されます。API は、緯度と経度のペアで指定された地球上のある地点のタイムゾーン データを返します。タイムゾーン データは、海などの水上では取得できない可能性があることに注意してください。

Google Maps Time Zone API リクエストの形式は次のとおりです。

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

outputFormat には次のいずれかの値を設定します。

  • json(推奨): 出力が JSON(JavaScript Object Notation)であることを示します。
  • xml: 出力が XML であることを示します(<TimeZoneResponse> ノード内にラップされます)。

重要: リクエストを送信する際は、http ではなく https を使用してください。

注: URL は、すべてのウェブサービスで対応できるように適切にエンコーディングされた有効な文字である必要があります。また、8192 文字以内という制限があります。URL を構成する際は、この制限に注意してください。別のブラウザ、プロキシ、サーバーでも同様に別の URL 文字制限がある可能性があります。

リクエスト パラメータ

すべての URL の標準と同様に、パラメータはアンパサンド(&)文字を使用して区切ります。各パラメータと有効な値のリストを次に示します。

必須パラメータ

  • location: 探す地点を示すコンマ区切りの緯度と経度のペア(例: location=-33.86,151.20)。
  • timestamp: 1970 年 1 月 1 日深夜 0 時からの経過秒数(UTC)で希望時刻を指定します。Google Maps Time Zone API は timestamp を使用して、夏時間を適用する必要があるかどうかを判断します。1970 年より前の時刻は負の値で表すことができます。
  • key: アプリケーションの API キーです。このキーを使ってアプリケーションを識別し、割り当て量を管理します。詳細については、キーの取得をご覧ください。

    注: Google Maps APIs Premium Plan ユーザーは、Time Zone リクエストで、API キー、または有効なクライアント ID とデジタル署名を使用できます。詳細については、Premium Plan ユーザーの認証パラメータをご確認ください。

省略可能なパラメータ

  • language: 結果を返すときの言語を示します。サポートされるドメイン言語のリストをご覧ください。サポートされる言語は頻繁に更新されるため、このリストがすべてのサポート言語を網羅しているとは限りません。デフォルト値は en です。

タイムゾーン レスポンス

タイムゾーン サービスは、有効なリクエストごとにリクエスト URL 内で指定した形式でレスポンスを返します。各レスポンスに含まれる要素は次のとおりです。

  • dstOffset: 夏時間のオフセット(秒単位)。指定された timestamp 時にタイムゾーンが夏時間でない場合、これはゼロになります。
  • rawOffset: 指定された地点の UTC からのオフセット(秒単位)。これには夏時間は考慮されません。
  • timeZoneId: タイムゾーンの「tz」ID を含む文字列(「America/Los_Angeles」や「Australia/Sydney」など)。これらの ID は IANA タイムゾーン データベースで定義されます。また、Wikipedia の List of tz database time zones の検索可能な形式で使用することもできます。
  • timeZoneName: 長いフォームのタイムゾーン名を含む文字列。このフィールドは、language パラメータが設定されている場合はローカライズされます(「Pacific Daylight Time」や「Australian Eastern Daylight Time」など)。
  • status: レスポンスのステータスを示す文字列。
    • OK は、リクエストが成功したことを示します。
    • INVALID_REQUEST は、リクエストが不適切な形式であることを示します。
    • OVER_QUERY_LIMIT は、リクエストが割り当て量を超えたことを示します。
    • REQUEST_DENIED は、API がリクエストを処理できなかったことを示します。リクエストが HTTP ではなく HTTPS で送信されたことを確認してください。
    • UNKNOWN_ERROR は、原因不明のエラーを示します。
    • ZERO_RESULTS は、指定された地点や時刻のタイムゾーン データが見つからなかったことを示します。リクエストした地点が水上ではなく陸地であることを確認してください。
  • error_message: 返されたステータス コード(OK 以外の場合)の原因に関する詳細情報。

    注: このフィールドは必ずしも存在するわけではなく、その内容も随時変更される可能性があります。

現地時間の計算

指定された地点の現地時間は、timestamp パラメータと、結果の dstOffset フィールドと rawOffset フィールドを合計したものになります。

リクエストの例

このセクションでは、API の機能を説明するいくつかのクエリの例を示します。

次のクエリでは、米国のネバダ州のタイムゾーン リクエストを実行します。2012 年 3 月 8 日にタイムスタンプを設定します。

JSON

リクエスト:

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

レスポンス:

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

リクエスト:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

レスポンス:

<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>

次のクエリでは、米国のネバダ州のタイムゾーン リクエストを実行します。この地点は上記のリクエストと同じですが、タイムスタンプが 2012 年 3 月 15 日に設定されています。このレスポンスには夏時間のオフセットが含まれます。

JSON

リクエスト:

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

レスポンス:

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

リクエスト:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&key=YOUR_API_KEY

レスポンス:

<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>

この例は、上記の 2 つの例と類似していますが、language パラメータが設定されています。このレスポンスはスペイン語にローカライズされます。

JSON

リクエスト:

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

レスポンス:

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

リクエスト:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&key=YOUR_API_KEY

レスポンス:

<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>

sensor パラメータ

Google Maps API では、以前はユーザーの位置情報の検出にアプリケーションでセンサーを使用するかどうかを示すため sensor パラメータを含める必要がありましたが、このパラメータは必要なくなりました。

フィードバックを送信...

Google Maps Time Zone API
Google Maps Time Zone API
ご不明な点がありましたら、Google のサポートページをご覧ください。