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

タイムゾーン

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 は、location のタイムゾーンに基づいて、timestamp を使用してサマータイムを適用するかどうかを判断します。

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

オプション パラメータ

• 言語

  結果を返す言語。

  • サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
  • 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>
      

タイムゾーンのレスポンス

リクエストが有効な場合、タイムゾーンはリクエスト 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 フィールドの合計です。