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

タイムゾーン

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

結果を返す言語。
- サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
- 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%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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

フィールド	必須	タイプ	説明
`status`	required	TimeZoneStatus	詳しくは、TimeZoneStatus をご覧ください。
`dstOffset`	省略可	数値	夏時間のオフセット（秒単位）。指定された `timestamp` の期間にタイムゾーンが夏時間でない場合は、ゼロになります。
`errorMessage`	省略可	文字列	指定されたステータスコードの理由に関する詳細情報。ステータスが `Ok` 以外の場合に含まれます。
`rawOffset`	省略可	数値	指定された場所の UTC からのオフセット（秒単位）。この期間では夏時間が考慮されません。
`timeZoneId`	省略可	文字列	タイムゾーンの ID を含む文字列（例: America/Los_Angeles、Australia/Sydney）。これらの ID は、Unicode 共通ロケールデータリポジトリ（CLDR）プロジェクトで定義されており、現在は timezone.xml ファイルで利用できます。タイムゾーンに複数の ID がある場合は、正規の ID が返されます。XML レスポンスでは、これは各タイムゾーンの最初のエイリアスです。たとえば、「Asia/Kolkata」ではなく「Asia/Calcutta」が返されます。
`timeZoneName`	省略可	文字列	タイムゾーンの正式名称。言語パラメータが設定されている場合、このフィールドはローカライズされます。例:`Pacific Daylight Time` または `Australian Eastern Daylight Time`。

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 フィールドの合計です。

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