タイムゾーンのリクエストとレスポンス

タイムゾーン

Time Zone API リクエストは、URL 文字列として作成されます。この API は、緯度と経度のペアで指定された地球上の地点のタイムゾーン データを返します。 なお、海などの水上の場所ではタイムゾーン データが利用できない場合があります。

タイムゾーン リクエストの形式は次のとおりです。

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

outputFormat には次のいずれかの値を指定できます。

• json（推奨）: JavaScript Object Notation（JSON）で出力します。
• xml：XML で出力し、 ノードでラップします。<TimeZoneResponse>

注: URL は有効にするために適切にエンコード する必要があります。また、すべてのウェブサービスで 16,384 文字に制限されています。URL を作成する際は、この制限に注意してください。ブラウザ、プロキシ、サーバーによって URL の文字数制限が異なる場合もあります。

必須パラメータ

• ロケーション

  検索する場所を表す、緯度と経度のカンマ区切りタプル location=39.6034810,-119.6822510。

• timestamp

  目的の時刻（1970 年 1 月 1 日午前 0 時（UTC）からの経過秒数）。Time Zone API は、timestamp を使用して、夏時間を適用するかどうかを判断します。これは、location のタイムゾーンに基づきます。

  この API は過去のタイムゾーンを考慮しないことに注意してください。つまり、過去のタイムスタンプを指定した場合、その場所が以前は別のタイムゾーンに属していた可能性は考慮されません。

オプション パラメータ

• language

  結果を返す言語。

  • サポートされている言語の 一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
  • language が指定されていない場合、API は Accept-Language ヘッダーで指定された優先言語を使用しようとします。
  • API は、ユーザーと地域住民の両方が読める番地を提供できるよう 最善を尽くします。そのため、優先言語に従って、必要に応じてユーザーが読める文字に音訳された番地を現地の言語で返します。その他の 住所はすべて優先言語で返されます。住所の構成要素は すべて同じ言語で返されます。この言語は最初の 構成要素から選択されます。
  • 優先言語で名前が使用できない場合、API は最も近い一致を使用します。
  • 優先言語は、API が返す結果のセットと、結果が返される順序にわずかな影響を与えます。ジオコーダは、言語によって略語の解釈が異なります。たとえば、通りの種類の略語や、ある言語では有効でも別の言語では有効でない同義語などです。たとえば、ハンガリー語では utca と tér は通りの同義語です。

タイムゾーンの例

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

次のクエリは、米国ネバダ州のタイムゾーン リクエストを実行します。タイムスタンプは 2024 年 12 月 5 日に設定されています。

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

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY'

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

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

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

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

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY'

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

<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 つの例と似ていますが、言語パラメータを設定しています。レスポンスはスペイン語にローカライズされます。

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

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&language=es&key=YOUR_API_KEY'

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

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

タイムゾーン レスポンス

有効なリクエストごとに、Time Zone はリクエスト URL 内に示された 形式でレスポンスを返します。

TimeZoneResponse

TimeZoneStatus

タイムゾーン レスポンス オブジェクトの status フィールドには リクエストのステータスが含まれます。status フィールドには次の値を指定できます。

• OK は、リクエストが成功したことを示します。

• INVALID_REQUEST は、リクエストの形式が正しくないことを示します。

• OVER_DAILY_LIMIT は、次のいずれかを示します。

  • API キーがないか、無効である。
  • アカウントで課金が有効になっていない。
  • ご自身で設定した使用量の上限を超えている。
  • 設定したお支払い方法が無効になっている（クレジット カードの期限切れなど）。

• OVER_QUERY_LIMIT は、リクエストが割り当て量を超えたことを示します。

• REQUEST_DENIED は、API がリクエストを完了しなかったことを示します。リクエストが HTTP ではなく HTTPS で送信されたことを確認します。

• UNKNOWN_ERROR は、不明なエラーが発生したことを示します。

• ZERO_RESULTS は、指定された位置または時刻のタイムゾーン データが見つからなかったことを示します。リクエストが水上ではなく陸上の場所に対するものであることを確認します。

現地時間の計算

特定の場所の現地時間は、 timestamp パラメータと、dstOffset と rawOffset フィールドの合計です。