My Geocode

ガイド

UTCのタイムスタンプをユーザーの現地時刻に変換する

· 3分で読めます · My Geocode · #タイムゾーン#UTC#ローカライゼーション

データベースではタイムスタンプをUTCで保存するのが正しい判断です。しかし、サポートチケット、注文確認、アクティビティログでユーザーにUTCを見せるのは適切ではなく、製品のインターフェースでよくある小さな不満の1つです。

2ステップでの変換

まず、タイムスタンプをどこを基準に解釈すべきかを把握します。登録済みの住所の座標か、IP検索で得た座標のいずれかです。次に、その座標とUTCタイムスタンプそのものをtimeパラメータを使って/v1/timezoneに渡します。こうすることで、返されるオフセットが現在の時点ではなく、対象となる時点のものになります。

GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1734000000
{
  "status": "ok",
  "timezone": "America/New_York",
  "utc_offset": "-05:00",
  "abbreviation": "EST"
}

保存しているUTCタイムスタンプにutc_offsetを適用するか、タイムゾーン識別子を独自の日付フォーマット処理に渡し、生のUTC値の代わりにその結果を表示します。

2つ目の例：数か月離れた日時

同じ座標でも、渡すタイムスタンプによって異なるオフセットが返されます。timeパラメータが存在する理由はまさにそこにあります。

GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1719000000
{
  "status": "ok",
  "timezone": "America/New_York",
  "utc_offset": "-04:00",
  "abbreviation": "EDT"
}

まったく同じ場所に対する2回の呼び出しの間で、オフセットがマイナス5時間からマイナス4時間に変わっていることに注目してください。これは単に、一方のタイムスタンプが夏時間の期間にあり、もう一方がそうでないためです。これを無視して両方に1つの固定オフセットを適用する表示では、どちらか一方が1時間ずれてしまいます。

timeパラメータが重要な理由

夏時間を採用しているほとんどの地域では、オフセットは1年を通じて変わります。timeパラメータを付けずにエンドポイントを呼び出すだけだと、今日のオフセットが返され、6か月前のタイムスタンプには誤ったものになります。変換するタイムスタンプと現在時刻が夏時間の切り替えをはさんで反対側にある可能性がある場合は、現在時刻ではなく、必ず変換対象のタイムスタンプを渡してください。

キャッシュするのはオフセットではなくタイムゾーン

ある座標に対するタイムゾーン識別子はめったに変わらないため、timezoneの文字列そのものを場所と紐づけてキャッシュしても問題ありません。utc_offsetとabbreviationの値は夏時間によって変わるため、長期間キャッシュするのは安全ではありません。これらは保存せず、表示時に再計算してください。

知っておきたいエッジケース

すべての場所が夏時間を採用しているわけではありません。1年中固定のオフセットのままの場所では、どのタイムスタンプを渡しても同じutc_offsetが返されます。これは想定どおりの動作であり、timeパラメータが無視されたことを示すものではありません。2つの異なるタイムスタンプで同じ結果が返ったからといって、何かが壊れていると考えないでください。

リクエストのコスト

1回の変換は1リクエストです。保存された多数のレコードの時刻を一度に変換するダッシュボードでは、タイムスタンプを1つずつループ処理するのではなく、基になる座標を一括POSTでまとめて送るべきです。1項目あたり1リクエストというコストは同じまま、1回の呼び出しで済みます。

現地時刻を正しく扱うことは、サポートチケットに誤った時刻が表示されるまで、ほとんどのチームが思っている以上に重要です。リクエストとレスポンスのフィールドの詳細はタイムゾーン検索のドキュメントにあります。

ガイドのその他の記事

· 4分で読めます

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

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