ガイドv3.2 API Referencev3.1 API Reference
ガイド
  1. 開発者ガイド
  2. 地図をカスタマイズする

GPXデータを表示する

 HERE Maps API for JavaScript version 3.2

GPX (GPS Exchange Format) は、GPSデバイスやアプリケーションによって記録された経由地、ルート、トラックを交換するためのXMLスキーマです。HERE Maps API for JavaScriptは、データモジュール (mapsjs-data.js) を通じてGPX 1.0および1.1ドキュメントをサポートしています。

H.data.gpx.Readerクラスは、GPXコンテンツを取得して解析し、それをマップオブジェクトに変換して、マップに直接追加できるレイヤーとして公開します。解析された各マップオブジェクトは、通常のマップイベントを受け取り、dataプロパティに元のGPX属性を保持するため、標高、時刻、速度、進行方向、シンボルなどの値は実行時に引き続きアクセス可能です。

📘

注

ドメインがクロスオリジンリソース共有 (CORS) をサポートしている場合は、別のドメインからGPXファイルを読み込むことができます。

クイックスタート

// Create a GPX reader bound to a URL:
const reader = new H.data.gpx.Reader('path/to/file.gpx');

// Start asynchronous parsing of the document:
reader.parse();

// Add the layer that holds the parsed GPX content to the map:
map.addLayer(reader.getLayer());

リーダーを使用する前に、HTMLファイルの<head>でデータモジュールをインポートすることを忘れないでください。

<script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-data.js"></script>

サポートされるGPX要素

経由地 (<wpt>)

<wpt>要素は、名前が付けられた地理上の地点を表し、H.map.Markerとしてレンダリングされます。

マーカーのdataには、解析された属性が公開されます。data内のfeatureTypeプロパティはwaypointです。

ルート (<rte>)

<rte>要素は、順序付けられた<rtept>個のルートポイントのリストを表し、単一のH.map.Polylineとしてレンダリングされます。

ルートメタデータ (name、descなど) はポリラインのdataに添付され、解析されたルートポイントのリストはpointsMetaInfoとして公開されます。これは、経由地と同じフィールドを持つオブジェクトの配列です。data内のfeatureTypeプロパティはrouteです。

トラック (<trk>および<trkseg>)

<trk>要素は、1つ以上の<trkseg>セグメントを含むことができる記録されたパスを表します。トラックは常にH.map.Groupとしてレンダリングされます。

トラックレベルのメタデータ (name、descなど) は、グループのdataに添付されています。data内のfeatureTypeプロパティはtrackです。

すべての<trkseg>セグメントは、リーダーの設定に応じて、1つ以上のH.map.Polylineオブジェクトとしてレンダリングされます。

オプションジオメトリーポリラインデータ
enableIndividualTrackSegmentStyling: false (デフォルト)トラックごとに1つのH.map.Polyline。各<trkseg>を結合したMultiLineStringを使用します。{ featureType: 'track_segment', pointsMetaInfo: [...] }。ここでは、pointsMetaInfoはセグメントごとの点配列の配列です (<trkseg>ごとに1つの内部配列)。
enableIndividualTrackSegmentStyling: true<trkseg>ごとに1つのH.map.Polyline。LineStringを使用します。{ featureType: 'track_segment', pointsMetaInfo: [...] }。ここでは、pointsMetaInfoは解析済みの<trkpt>オブジェクトのフラットな配列です。

最小限のマップオブジェクト数でトラック全体を均一にスタイル設定する場合は、デフォルトモードを使用してください。セグメントごとに異なるスタイルを設定する場合は、個別セグメントモードに切り替えてください。

各ポリラインについて、data内のfeatureTypeプロパティはtrack_segmentです。

メタデータ (<metadata>)

GPXドキュメントのメタデータは、ルートグループのdataで公開されます。reader.getParsedObjects()[0].getData()を呼び出すと、name、desc、time、keywords、author、copyright、links、bounds ({ minlat, minlon, maxlat, maxlon }) といったフィールドや、<gpx>ルート要素のversion属性およびcreator属性にアクセスできます。GPX 1.1ドキュメント (これらを<metadata>内にネストする形式) と、GPX 1.0ドキュメント (これらを<gpx>の直接の子要素として公開する形式、urlおよびurlnameを含む) のどちらもサポートされています。

📘

注

<wpt>、<rtept>、<trkpt>内のメタデータのlatフィールドおよびlonフィールドは、マップオブジェクトdataの一部ではありません。この情報には、それぞれのマップオブジェクトのジオメトリーからアクセスできます。

<extension>フィールドは解析されず、オブジェクトのメタデータの一部としても存在しません。

出力階層

リーダーは、GPXドキュメントの構造を反映した単一のH.map.Groupツリーを生成します。getParsedObjects()はこのルートグループを配列内の唯一のエントリーとして返し、getLayer()によって返されるレイヤーがそれを表示します。GPXドキュメントに経由地、ルート、トラックが一切含まれていない場合でも、ルートグループは常に作成され、実質的に空のGPXドキュメントを表現することになります。

Root GPX                     (H.map.Group)
├── Waypoints                (H.map.Group)
│   └── Waypoint             (H.map.Marker)
│   └── Waypoint             (H.map.Marker)
├── Routes                   (H.map.Group)
│   └── Route                (H.map.Polyline)
│   └── Route                (H.map.Polyline)
└── Tracks                   (H.map.Group)
    └── Track                (H.map.Group)
        └── Track Segment    (H.map.Polyline)
        └── Track Segment    (H.map.Polyline)
    └── Track                (H.map.Group)
        └── Track Segment    (H.map.Polyline)

waypoints、routes、tracksのいずれかのサブグループは、ドキュメントにその種類の要素が少なくとも1つ含まれている場合にのみ追加されます。ツリー内の任意のオブジェクトに対してgetData()を使用することで、解析された属性にアクセスできます。ソースドキュメントに対応するGPX要素または属性が存在しないプロパティは、返されるデータオブジェクトから省略されるため、利用者は真実性チェックまたはhasOwnPropertyチェックを使用して、欠落しているフィールドを検出できます。リーダーは、元のDOMノードへの参照を保持しません。

ノードマップオブジェクトマップオブジェクトデータ
GPXルートH.map.Group{ featureType: 'gpx', ...parsed <gpx> data }
経由地H.map.Group{ featureType: 'waypoints' }
経由地H.map.Marker{ featureType: 'waypoint', ...parsed <wpt> data }
ルートH.map.Group{ featureType: 'routes' }
ルートH.map.Polyline{ featureType: 'route', pointsMetaInfo: [...], ...parsed <rte> data }
トラックH.map.Group{ featureType: 'tracks' }
トラックH.map.Group{ featureType: 'track', ...parsed <trk> data }
トラックセグメントH.map.Polyline{ featureType: 'track_segment', pointsMetaInfo: [...] } - 各モードでのpointsMetaInfoの構成については、トラック (<trk>および<trkseg>) を参照してください。

例：HEREマップでGPXコンテンツをレンダリングする

次の例では、GPXファイルを読み込み、その経由地、ルート、トラックを表示します。これは、「HERE Maps API for Javascriptの使用を開始する」で説明されているベースマップを基に作成されています。

  1. HTMLファイルの<head>要素内で、データモジュールをインポートします。

    <script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-data.js"></script>

  2. リーダーを作成し、ドキュメントを解析して、結果として得られたレイヤーをマップに追加します。statechangeをリッスンして、解析が完了または失敗した際に反応するようにします。

    const reader = new H.data.gpx.Reader('path/to/file.gpx');

reader.addEventListener('statechange', function (evt) {
  if (evt.state === H.data.AbstractReader.State.READY) {
    // Auto-fit the view to the parsed content.
    map.getViewModel().setLookAtData({
      bounds: reader.getLayer().getProvider().getRootGroup().getBoundingBox()
    });
  } else if (evt.state === H.data.AbstractReader.State.ERROR) {
    console.error('Failed to parse GPX document:', evt.message);
  }
});

reader.parse();
map.addLayer(reader.getLayer());

  3. レンダリングされた各オブジェクトに付随するGPX属性を確認するには、レイヤーのプロバイダーにtapリスナーを添付し、dataプロパティを読み取ります。

    reader.getLayer().getProvider().addEventListener('tap', function (evt) {
  console.log(evt.target.getData()); // parsed GPX attributes for the tapped object
});

レンダリングスタイルをカスタマイズする

Readerコンストラクタは、styleコールバックを含むオプションオブジェクトを受け付けます。このコールバックは、レンダリングされたマップオブジェクト (中間グループではなく、マーカーやポリライン) ごとに1回呼び出され、そのオブジェクトを唯一の引数として受け取ります。mapObject.getData().featureTypeを読み取ることでフィーチャーのタイプを判別します。値は'waypoint'、'route'、'track_segment'のいずれかであり、フィーチャーのタイプごとに異なるデフォルト設定を適用するために使用できます。

const reader = new H.data.gpx.Reader('path/to/file.gpx', {
  style: function (mapObject) {
    const featureType = mapObject.getData().featureType;
    if (featureType === 'waypoint') {
      mapObject.setIcon(new H.map.Icon('icons/pin.svg'));
    } else if (featureType === 'route') {
      mapObject.setStyle({ strokeColor: '#1f78b4', lineWidth: 4 });
    } else if (featureType === 'track_segment') {
      mapObject.setStyle({ strokeColor: '#e31a1c', lineWidth: 5 });
    }
  }
});
reader.parse();

文字列からGPXコンテンツを解析する

GPXペイロードがすでにメモリ内にある場合は、parse()の代わりにparseData()を使用します。これにより、余分なHTTPリクエストを回避でき、アプリケーションによって生成されたコンテンツや、カスタムトランスポートを介して取得されたコンテンツを扱う際に便利です。

const gpxString = `<?xml version="1.0"?>
  <gpx version="1.1" xmlns="http://www.topografix.com/GPX/1/1">
  <wpt lat="52.5189" lon="13.4158"><name>Berlin</name></wpt>
  </gpx>`;

const reader = new H.data.gpx.Reader();
reader.parseData(gpxString);

map.addLayer(reader.getLayer());

解析済みのオブジェクトにプログラムからアクセスする

スタイルコールバックに基づくワークフローに加え、リーダーは解析済みのマップオブジェクトを直接公開します。これは、GPXでレンダリングされたオブジェクトを検査、変換、後処理する必要がある場合に役立ちます。

reader.addEventListener('statechange', function (evt) {
  if (evt.state === H.data.AbstractReader.State.READY) {
    const rootGroup = reader.getParsedObjects()[0];

    // print data of top-level GPX feature
    console.log(rootGroup.getData());
    const waypointsGroup = rootGroup.getObjects().find(g => g.getData().featureType === 'waypoints');

    // print data of each waypoint
    waypointsGroup.getObjects().forEach(w => console.log(w.getData()));
  }
});

解析エラーを処理する

入力が処理できない場合 (レスポンス本文が空の場合、XMLが不正な形式である場合、ルート要素が<gpx>でない場合など)、リーダーはERROR状態に移行します。statechangeイベントでは、evt.messageに人間が読める説明が表示されます。

reader.addEventListener('statechange', function (evt) {
  if (evt.state === H.data.AbstractReader.State.ERROR) {
    console.error('GPX parsing failed:', evt.message);
  }
});

次のステップ

  • メソッドおよびオプションの完全な一覧については、APIリファレンスのH.data.gpx.Readerのエントリーを参照してください。
  • 完全な動作サンプルおよび実装の詳細については、Display GPX dataのサンプルページを参照してください。

先月の更新

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