ガイドAPIリファレンス
ガイド
  1. HERE Routing API V8 - 開発者ガイド
  2. 概念

スパンの概要

スパンは、共通の値を持つ属性の共有セットを含むルートセクションの一部です。 スパンをリクエストすると、レスポンスには、計算されたルートに沿ったリクエストされた属性の値が含まれます。 このような情報を使用して、ルート情報を詳細レベルで分析したり、データを使用してルートの詳細な可視化を作成したりできます。

スパンを取得するには、リクエストに以下のパラメーターを含める必要があります。

  • return=polylineパラメーター：スパンの開始地点と終了地点はポリラインから派生します。
  • spans=ATTRIBUTE_LISTパラメーター：スパンを構成する共通値を持つ属性のリストを定義します。

スパンの開始地点は、offset属性によって定義されます。これは、ルートセクションのポリラインから派生した座標のリストのインデックスです。 1つのスパンは次のスパンが開始する地点で終了します。 指定されたスパンがルートセクションの最後のスパンである場合、ルートセクションの終了地点で終了します。

リクエストされた属性のいずれかが変更されると新しいスパンが導入されますが、3つの注目すべき例外 (duration、length、consumption) があります。 これら3つの属性は新しいスパンを誘発せず、他の属性のメタデータとして機能します。

📘

注

Routing APIによって提供されるデータよりも詳細なデータが必要な場合は、spans=segmentRefを使用してHERE Map Contentトポロジーセグメントへの参照をリクエストできます。 これらのセグメント参照は、次の例のようなさまざまなサービスやデータレイヤーから追加情報を取得するために使用できます。

セクション内のスパンの量

セクション内のスパンの量は、ルートに対するリクエストで指定された属性の数によって異なります。 リクエストされた属性が頻繁に変更される場合、スパンはより細かくなり、まれに変更される場合、スパンはより粗くなります。 リクエストする属性が多いほど、それらのいずれかが変更される可能性が高くなり、それによって新しいスパンが生成されます。

2つの極端な例は、countryCodeとdynamicSpeedInfoです。 countryCode属性は、ルートセクションが国境を越えるときに新しいスパンを生成しますが、これはまれにしか発生しません。 dynamicSpeedInfo属性は、予想される走行速度が変化するたびに新しいスパンを生成するため、頻繁に発生する傾向があります。

例

リクエストされた属性が計算されたルートのスパン数に与える影響を示すために、次の例を考えてみましょう。

単一の属性

このリクエストでは、スパンは単一の属である道路名に基づいて追加されます。

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.544816,13.367221&'\
'destination=52.544862,13.365931&'\
'return=polyline&'\
'spans=names&'\
'transportMode=pedestrian&'\
'apiKey=YOUR_API_KEY'

レスポンスには2つのスパンが含まれます。1つはオフセット0から開始し、もう1つはオフセット3から開始します。

"polyline": "BGozinkDq77vZApLwCnfA7aQjL",
"spans": [
  {
    "offset": 0,
    "names": [
      {
        "value": "Gerichtstraße",
        "language": "de"
      }
    ]
  },
  {
    "offset": 3,
    "names": [
      {
        "value": "Gerichtstraße",
        "language": "de"
      },
      {
        "value": "Max-Josef-Metzger-Platz",
        "language": "de"
      }
    ]
  }
]

ポリラインは次のようにデコードされます。

Offset 0: (52.544820, 13.367221)
Offset 1: (52.544820, 13.367040)
Offset 2: (52.544860, 13.366540)
Offset 3: (52.544860, 13.366110)
Offset 4: (52.544868, 13.365932)

2つの属性

リクエストに別の属性を追加すると、スパンの数は2から3に増えますが、ポリラインは同じままです。

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.544816,13.367221&'\
'destination=52.544862,13.365931&'\
'return=polyline&'\
'spans=names,carAttributes&'\
'transportMode=pedestrian&'\
'apiKey=YOUR_API_KEY'

レスポンスには、これまでの2つではなく、3つのスパンが含まれるようになりました。

"polyline": "BGozinkDq77vZApLwCnfA7aQjL",
"spans": [
  {
    "offset": 0,
    "carAttributes": [
      "open"
    ],
    "names": [
      {
        "value": "Gerichtstraße",
        "language": "de"
      }
    ]
  },
  {
    "offset": 1,
    "names": [
      {
        "value": "Gerichtstraße",
        "language": "de"
      }
    ]
  },
  {
    "offset": 3,
    "carAttributes": [
      "open",
      "noThrough"
    ],
    "names": [
      {
        "value": "Gerichtstraße",
        "language": "de"
      },
      {
        "value": "Max-Josef-Metzger-Platz",
        "language": "de"
      }
    ]
  }
]

前のリクエストの最初のスパンは、carAttributesプロパティが途中で変更されたため (オフセット1)、2つに分割されます。ルートの濃い青色の部分 (オフセット1からオフセット3) は車両通行禁止です。

ルートの例

利用可能なスパン属性

セクション内のスパン属性は、セクションのタイプ (PedestrianSection、VehicleSection、TransitSection) によって異なります。 使用可能なスパン属性のリストを取得するには、「HERE Routing API v8 APIリファレンス」を参照してください。次の手順を実行します。

  1. /openapiエンドポイントから完全なAPIリファレンスを取得します。
curl -gX GET "https://router.hereapi.com/v8/openapi"
  1. 目的のセクションタイプのスパンスキーマ定義を探します (PedestrianSpan、VehicleSpan､TransitSpan)。
  2. すべてのスパン属性は、説明とそれぞれのスキーマへのリンクとともに一覧表示されます。
📘

注

または、HEREドキュメントポータルでホストされているAPIリファレンスを使用することもできます。これについては、「HERE Routing API v8 APIリファレンス」を参照してください。

関連コンテンツ

25 日前の更新