タイムゾーン情報を含める

HERE Geocoding and Search API v7は、結果項目のタイムゾーン情報を返します。これは、ユーザーの位置と対象の結果との間の時差を表示するなど、現地時間を後処理する必要があるアプリケーションで役立ちます。

📘

注

HERE Geocoding and Searchは、リクエストが行われた時点で場所が営業中かどうかを示すisOpenフィールドを提供しています。場所のタイムゾーンは、ユーザーのタイムゾーンと異なる場合があります。

タイムゾーンデータは、世界各地の標準時の定義における業界標準の情報源であるIANA tzデータベース(Olsonデータベースとも呼ばれます)に基づいています。

タイムゾーン情報のリクエスト

レスポンスにタイムゾーン情報を含めるには、リクエストにshow=tzを追加します。このパラメーターは、/autocompleteエンドポイントを除くすべてのエンドポイントでサポートされています。showパラメーターの使用方法の詳細については、「レスポンスの強化」を参照してください。

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Kurfürstendamm+1,+Berlin
    &show=tz
    &apiKey={YOUR_API_KEY}

レスポンスには、各結果項目にtimeZoneオブジェクトが含まれます。

{
  "items": [
    {
      "title": "Kurfürstendamm 1, 10719 Berlin, Germany",
      "id": "here:af:streetsection:yYCvdpwmBNB0FoOW0SWGUB:EAIaAzEwMQ",
      "resultType": "houseNumber",
      "address": {
        "label": "Kurfürstendamm 1, 10719 Berlin, Germany"
      },
      "position": {
        "lat": 52.50213,
        "lng": 13.33181
      },
      "timeZone": {
        "name": "Europe/Berlin",
        "utcOffset": "+02:00"
      }
    }
  ]
}

タイムゾーンのレスポンスフィールド

timeZoneオブジェクトには、次のフィールドが含まれます。

フィールド型説明
namestringIANAタイムゾーン名。例:Europe/Berlin、America/New_York。
utcOffsetstringリクエスト時点での現在のUTCオフセット。該当する場合は夏時間(DST)を考慮します。形式:+HH:MMまたは-HH:MM。utcOffsetを将来または過去のオフセットとして使用しないでください。対象の日時に合わせて再計算してください。

utcOffsetの値は、リクエストが行われた時点で有効なオフセットを反映します。つまり、標準時と夏時間(サマータイム)の季節による切り替えが自動的に考慮されます。

📘

タイムゾーンの定義

HERE Geocoding and Searchは、IANA tzデータベースに準拠した以下の用語を使用しています。

  • タイムゾーン:同じUTCオフセットと夏時間ルールに従う地域。各タイムゾーンには、Area/Locationという形式で一意の名前があります(例:America/Chicago)。
  • 夏時間(DST):地域によってはサマータイムとも呼ばれます。1年のうち温暖な季節に時計を進める慣行のことです。
  • 標準時:冬時間とも呼ばれます。DSTの期間を除いた基準となるUTCオフセットのことです。

紛争地域におけるタイムゾーン

政治的見解の対象となる地域では、リクエストで使用するpoliticalViewパラメーターによってタイムゾーン情報が異なる場合があります。例:

  • 紛争地域であるRincon de Artigas (-31.01747,-55.96375)は、クエリにpoliticalView=URYパラメーターが含まれる場合、タイムゾーンAmerica/Montevideoに属します。それ以外の場合は、タイムゾーンAmerica/Sao_Pauloに属します。
  • 同様に、紛争地域であるHalaib Triangle (22.24593,36.01012)は、クエリにpoliticalView=SDNパラメーターが含まれる場合、タイムゾーンAfrica/Khartoumに属します。それ以外の場合は、タイムゾーンAfrica/Cairoに属します。

特定の政治的見解に対応したタイムゾーン情報を取得するには、リクエストでshow=tzとpoliticalViewパラメーターを組み合わせて使用してください。

タイムゾーンの精度

タイムゾーン名はHERE Map Dataから取得されます。結果項目にマップデータ上のタイムゾーン名が設定されていない場合、APIは実行時に結果の地理座標からタイムゾーンを導出します。

タイムゾーンルールは急に変更される可能性があるため(例:政府による夏時間の廃止や変更)、ルールの変更が発表されても、基盤となるデータにまだ反映されていない場合、報告されるUTCオフセットが実際の現地のオフセットと一時的に異なることがあります。こうした変更に対応するため、IANA tzデータベースは年に数回更新されます。

座標を現地時間に変換する

/revgeocodeエンドポイントをshow=tzとともに使用することで、車両の現在の座標を現地時間に変換できます。これは、車両がタイムゾーンの境界を越える際に、ヘッドユニットの時計を正確に保つ必要がある場合に役立ちます。

リクエスト例(車両の現在位置)

GET https://revgeocode.search.hereapi.com/v1/
    revgeocode
    ?at=41.686109,-86.527986
    &show=tz
    &apiKey={YOUR_API_KEY}

レスポンスを適用するには、timeZone.name (例:America/Chicago)をその座標の正規のタイムゾーンとして読み取ります。次に、timeZone.utcOffset (例:-05:00)をリクエスト時点での有効なオフセットとして読み取り、そのオフセットを適用してUTCから現在の現地時間を計算します(localTime = utcNow + utcOffset)。

ヘッドユニットの時計を更新するには、プラットフォームがIANAタイムゾーンをサポートしている場合、システムのタイムゾーンをtimeZone.nameに設定し、OSにDSTの切り替えを自動的に処理させます。
プラットフォームが固定のUTCオフセットのみをサポートしている場合は、DSTの変更や国境の通過時にも正確な時刻を維持できるよう、オフセットを定期的に(および大幅な位置変更の後に)更新してください。
州や国だけでタイムゾーンを推測しないでください。行政区域やタイムゾーンの境界付近では、必ず正確な座標に対するAPIの結果を参照してください。

レスポンスの例(抜粋)

{
  "items": [
    {
      "position": {
        "lat": 41.686109,
        "lng": -86.527986
      },
      "timeZone": {
        "name": "America/Chicago",
        "utcOffset": "-05:00"
      }
    }
  ]
}

このページは役に立ちましたか?