My Geocode

ガイド

任意の緯度と経度のタイムゾーンを調べる

· 3分で読めます · My Geocode · #タイムゾーン#座標#検索

座標だけでは、地図上のある地点が今何時なのかはわかりません。タイムゾーンエンドポイントは緯度と経度を受け取り、タイムゾーン名、現在のUTCオフセット、略称を返します。

リクエストを送る

GET /v1/timezone?lat=52.3676&lon=4.9041
{
  "status": "ok",
  "timezone": "Europe/Amsterdam",
  "utc_offset": "+02:00",
  "abbreviation": "CEST"
}

timezoneフィールドは標準的な識別子で、ほとんどの日付・時刻ライブラリにそのまま渡せます。utc_offsetとabbreviationのフィールドは、識別子の文字列よりもなじみのある表示を読み手に見せたいときに役立ちます。

日付変更線の反対側にある2つ目の例

オフセットは必ずしも小さくきりのよい数値とは限らず、世界の人口の大半とは日付変更線の反対側にある場所もあります。

GET /v1/timezone?lat=-17.7333&lon=168.3273
{
  "status": "ok",
  "timezone": "Pacific/Efate",
  "utc_offset": "+11:00",
  "abbreviation": "VUT"
}

返された識別子は、自分のサーバーの時計からどれだけ離れていても同じように扱ってください。日付ライブラリは11時間のオフセットを正しく扱う方法をすでに知っているため、自分のタイムゾーンから遠く離れた場所のために特別な処理を書く必要はありません。

ジオコーディングと組み合わせる

このエンドポイントに必要なのは座標だけなので、ジオコーディングや逆ジオコーディングと自然に組み合わせられます。まず住所をジオコーディングして緯度と経度を取得し、それをそのまま/v1/timezoneに渡せば、ユーザーにタイムゾーンについて直接何も尋ねることなく、その場所がどのタイムゾーンにあるかがわかります。

ジオコーディングした住所ではなく訪問者のIPアドレスがすでにある場合は、/v1/ipエンドポイントが自身のレスポンスにtimezoneフィールドを直接含めて返すため、このエンドポイントを別途呼び出す必要はまったくありません。顧客の配送先プロフィールにある住所など、IP検索と関連付いていない座標がすでにある場合に、/v1/timezoneを直接使ってください。

夏時間を考慮する

utc_offsetとabbreviationは、問い合わせた時点で有効なオフセットを反映しています。現在ではなく特定の日付が必要な場合は、timeパラメーターでUNIXタイムスタンプを渡してください。そうすれば、レスポンスには今日のオフセットではなく、その日付に適用されていたオフセットが反映されます。

GET /v1/timezone?lat=52.3676&lon=4.9041&time=1731000000

避けるべき間違い

このエンドポイントを一度呼び出してutc_offsetの値を長期間キャッシュするのはよくある近道ですが、夏時間を実施している地域では年に2回破綻します。タイムゾーン識別子そのものは安定しており、キャッシュしても安全です。一方、オフセットと略称はカレンダーとともに変わるため安全ではありません。識別子と一緒に保存するのではなく、表示の時点で計算し直してください。

コスト

タイムゾーン検索は1回につき1件のリクエストです。登録や購入手続きのフローの一部としてすでに住所をジオコーディングしている場合、同じ場所のタイムゾーン検索を追加すると、そのフローのリクエスト数は1件から2件へと倍になります。それでも、すべてのキーに含まれる1日あたりの無料リクエスト2,500件と比べれば、ごくわずかな量です。

タイムゾーンのデータは、特に夏時間の切り替わりの前後で、手作業では間違えやすいものです。そのため、独自のオフセット表を管理するよりも、単一の情報源から取得する価値があります。すべてのパラメーターの一覧はタイムゾーン検索のドキュメントに記載されています。

ガイドのその他の記事

· 4分で読めます

住所と郵便番号を照合する

住所と郵便番号をそれぞれ個別に解決して実際に示す内容を比較することで、注文の発送前に番地と郵便番号の不一致を見つけます。