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

タイムゾーン

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

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

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

ここで、outputFormat は次のいずれかの値になります。

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

必須パラメータ

ロケーション

検索する場所を表す、カンマ区切りの緯度と経度のタプル（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 日に設定されています。

URL

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

curl

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

JSON

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

XML

<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 日に設定されています。レスポンスに夏時間のオフセットが含まれるようになりました。

URL

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

curl

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

JSON

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

XML

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

URL

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

curl

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'

JSON

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

XML

<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

フィールド 必須 タイプ 説明
required TimeZoneStatus 詳細については、TimeZoneStatus をご覧ください。
省略可 数値

夏時間のオフセット（秒単位）。指定された timestamp の期間中にタイムゾーンが夏時間でない場合、この値は 0 になります。
省略可 文字列

指定されたステータス コードの理由に関する詳細情報。ステータスが Ok 以外の場合に含まれます。

省略可 数値

指定された場所の UTC からのオフセット（秒単位）。夏時間は考慮されません。
省略可 文字列

タイムゾーンの ID（「America/Los_Angeles」や「Australia/Sydney」など）を含む文字列。これらの ID は、Unicode Common Locale Data Repository（CLDR）プロジェクトによって定義されており、現在は timezone.xml ファイルで使用できます。タイムゾーンに複数の ID がある場合は、正規の ID が返されます。XML レスポンスでは、これは各タイムゾーンの最初のエイリアスです。たとえば、「Asia/Kolkata」ではなく「Asia/Calcutta」が返されます。
省略可 文字列

タイムゾーンの正式名称。このフィールドは、言語パラメータが設定されている場合にローカライズされます。例:Pacific Daylight Time または Australian Eastern Daylight Time。

TimeZoneStatus

Time Zone レスポンス オブジェクト内の status フィールドには、リクエストのステータスが含まれます。status フィールドには次の値が含まれます。

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

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

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

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

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

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

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

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

現地時間の計算

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