高度サービス

概要

高度サービスを使うと、地表のさまざまな地点の高度データを取得できます（海底のような深い場所にも対応しており、その場合は高度が負の値になります）。リクエストした正確な地点の高度データが Google にない場合は、サービス側でその地点から最も近い 4 地点のデータを補間して平均値を返します。

ElevationService オブジェクトが提供するシンプルなインターフェースにより、地球上の地点の高度データをクエリできます。さらに、任意のパス上で高度データをサンプリングするようリクエストを行い、そのパスに沿った高度値の変化を等間隔で計算することもできます。ElevationService オブジェクトは、高度リクエストを受信して高度データを送信する Google Maps API の高度サービスと通信します。

高度サービスを利用すると、ハイキング用およびサイクリング用のアプリ、モバイル用の測位アプリ、低解像度の測量アプリを開発できます。

ご利用にあたって

Maps JavaScript API で高度サービスを使用するにはまず、Maps JavaScript API を設定した同じプロジェクトで Elevation API が有効になっていることを Google Cloud コンソールで確認します。

有効な API のリストを表示するには:

  1. Google Cloud コンソール に移動します。
  2. [プロジェクトを選択] ボタンをクリックし、Maps JavaScript API を設定した同じプロジェクトを選択して、[開く] をクリックします。
  3. [ダッシュボード] の API のリストから、Elevation API を探します。
  4. リストに API が表示されていれば、準備は完了です。API がリストに表示されていない場合は、次の手順で有効にします。
    1. ページの上部で、[API を有効にする] を選択して [ライブラリ] タブを表示します。または、左側のサイドメニューで [ライブラリ] を選択します。
    2. Elevation API を検索し、結果のリストから選択します。
    3. [有効にする] を選択します。このプロセスを完了すると、[ダッシュボード] の API のリストに Elevation API が表示されます。

料金とポリシー

料金

2018 年 7 月 16 日に、マップ、ルート、プレイスに対して従量課金制の新しい料金プランが適用されました。JavaScript 高度サービスの新しい料金と使用量上限については、Elevation API の使用量と請求額をご覧ください。

ポリシー

高度サービスは、Elevation API を対象とするポリシーに従って使用する必要があります。

高度をリクエストする

高度サービスにアクセスすると、Google Maps API は外部サーバーに対して呼び出しを行うので、処理が非同期になります。このため、コールバック メソッドを渡してリクエストの完了時に実行し、このコールバック メソッドで結果を処理する必要があります。なお、高度サービスはステータス コード（ElevationStatus）と各 ElevationResult オブジェクトの配列を返します。

ElevationService は次の 2 種類のリクエストを処理します。

  • 独立した不連続の地点における高度のリクエスト。リクエスト時は、LocationElevationRequest オブジェクトを使って、getElevationForLocations() メソッドに、1 つ以上の地点を含むリストを渡します。
  • パス上にある一連の連結した地点における高度のリクエスト。リクエスト時は、PathElevationRequest オブジェクトに格納したパス順に整列した頂点のセットを getElevationAlongPath() メソッドに渡します。パス上の高度をリクエストする際は、取得したいサンプル数をパラメータとして指定し、それをともに渡す必要があります。

上記の各メソッドは、コールバック メソッドも渡し、返された ElevationResult と ElevationStatus オブジェクトを処理します。

地点の高度をリクエストする

LocationElevationRequest オブジェクト リテラルには、次のフィールドがあります:

{
  locations[]: LatLng
}

locations（必須）は、高度データを返す地球上の地点を定義します。このパラメータは、LatLng の配列を受け取ります。

サービスの割り当て量を超えない限りは、この配列内で座標をいくつ渡してもかまいません。ただし複数の座標を渡すと、1 つの座標に対するデータをリクエストしたときよりも、返されるデータの精度が落ち、低解像度になることがあるので注意してください。

パス上でサンプリングした高度をリクエストする

PathElevationRequest オブジェクト リテラルには次のフィールドがあります。

{
  path[]: LatLng,
  samples: Number
}

以下はフィールドの説明です。

  • path（必須）は、高度データを返す地球上のパスを定義します。この path パラメータは、2 つ以上の LatLng オブジェクト配列を使用して、順番に並んだ 2 つ以上の {latitude,longitude} のセットを定義します。
  • samples（必須）は、パス上で高度データをサンプリングする地点の数を指定します。この samples パラメータは、指定された path を、パス上に等間隔で並ぶ順序付きの点のセットに分割します。

位置リクエストと同様に、path パラメータは緯度と経度の値のセットを指定します。ただし、位置リクエストとは異なり、path で指定するのは順番に並んだ頂点のセットです。パス上の高度をリクエストすると、頂点の高度データが返される代わりに、ルートの端から端まで（始点と終点を含めて）等間隔で並んだ地点においてサンプリングしたデータが返されます。

高度リクエストのレスポンス

リクエストが有効な場合、高度サービスは ElevationResult オブジェクトと ElevationStatus オブジェクトを定義されたコールバックに返します。

高度リクエストのステータス

高度をリクエストすると、コールバック関数内の ElevationStatus コードを返します。status コードは、次の値のうちのいずれかです。

  • OK は、サービス リクエストが成功したことを示します。
  • INVALID_REQUEST は、はサービス リクエストの形式が正しくないことを示します。
  • OVER_QUERY_LIMIT は、リクエストが割り当て量を超えたことを示します。
  • REQUEST_DENIED は、パラメータが無効であるなどの原因により、サービス側でリクエストを処理できなかったことを示します。
  • UNKNOWN_ERROR は、不明なエラーが発生したことを示します。

コールバックが正しく動作しているかどうかを、このステータス コード（OK）で確認してください。

高度リクエストの結果

リクエストに成功すると、コールバック関数の引数 results には ElevationResult オブジェクトのセットが含まれます。これらのオブジェクトに含まれる要素は、以下のとおりです。

  • location 要素（LatLng オブジェクトを含む）は、高度データを計算する地点を示します。なお、パス上のリクエストの場合は、location 要素のセットに、パス上のサンプリング地点が含まれています。
  • elevation 要素は、その地点の高度をメートル単位で表します。
  • resolution 値は、高度の補間に使われたデータ地点間の最長距離をメートル単位で表します。解像度が不明の場合は、このプロパティは存在しません。なお、複数の地点が渡された場合は、高度データがより粗く（resolution の値が大きくなる）なります。各地点の最も正確な高度値を取得するには、個別にクエリを行う必要があります。

高度リクエストのコードサンプル

以下のコードサンプルは、LocationElevationRequest オブジェクトを使用して、マップ上でクリックした地点の高度をリクエストします。

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 63.333, lng: -150.5 }, // Denali.
      mapTypeId: "terrain",
    }
  );
  const elevator = new google.maps.ElevationService();
  const infowindow = new google.maps.InfoWindow({});

  infowindow.open(map);

  // Add a listener for the click event. Display the elevation for the LatLng of
  // the click inside the infowindow.
  map.addListener("click", (event) => {
    displayLocationElevation(event.latLng, elevator, infowindow);
  });
}

function displayLocationElevation(
  location: google.maps.LatLng,
  elevator: google.maps.ElevationService,
  infowindow: google.maps.InfoWindow
) {
  // Initiate the location request
  elevator
    .getElevationForLocations({
      locations: [location],
    })
    .then(({ results }) => {
      infowindow.setPosition(location);

      // Retrieve the first result
      if (results[0]) {
        // Open the infowindow indicating the elevation at the clicked position.
        infowindow.setContent(
          "The elevation at this point <br>is " +
            results[0].elevation +
            " meters."
        );
      } else {
        infowindow.setContent("No results found");
      }
    })
    .catch((e) =>
      infowindow.setContent("Elevation service failed due to: " + e)
    );
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 63.333, lng: -150.5 }, // Denali.
    mapTypeId: "terrain",
  });
  const elevator = new google.maps.ElevationService();
  const infowindow = new google.maps.InfoWindow({});

  infowindow.open(map);
  // Add a listener for the click event. Display the elevation for the LatLng of
  // the click inside the infowindow.
  map.addListener("click", (event) => {
    displayLocationElevation(event.latLng, elevator, infowindow);
  });
}

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator
    .getElevationForLocations({
      locations: [location],
    })
    .then(({ results }) => {
      infowindow.setPosition(location);
      // Retrieve the first result
      if (results[0]) {
        // Open the infowindow indicating the elevation at the clicked position.
        infowindow.setContent(
          "The elevation at this point <br>is " +
            results[0].elevation +
            " meters.",
        );
      } else {
        infowindow.setContent("No results found");
      }
    })
    .catch((e) =>
      infowindow.setContent("Elevation service failed due to: " + e),
    );
}

window.initMap = initMap;
index.js
サンプルを表示

サンプルを試す

以下のサンプルは、指定された座標のセットからポリラインを作成し、Google Visualization API を使って、そのパス上の高度データを表示します（Google の共通ローダーを使って、この API を読み込む必要があります）。高度リクエストは、PathElevationRequest を使って作成しています。

TypeScript

// Load the Visualization API and the columnchart package.
// @ts-ignore TODO update to newest visualization library
google.load("visualization", "1", { packages: ["columnchart"] });

function initMap(): void {
  // The following path marks a path from Mt. Whitney, the highest point in the
  // continental United States to Badwater, Death Valley, the lowest point.
  const path = [
    { lat: 36.579, lng: -118.292 }, // Mt. Whitney
    { lat: 36.606, lng: -118.0638 }, // Lone Pine
    { lat: 36.433, lng: -117.951 }, // Owens Lake
    { lat: 36.588, lng: -116.943 }, // Beatty Junction
    { lat: 36.34, lng: -117.468 }, // Panama Mint Springs
    { lat: 36.24, lng: -116.832 },
  ]; // Badwater, Death Valley

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: path[1],
      mapTypeId: "terrain",
    }
  );

  // Create an ElevationService.
  const elevator = new google.maps.ElevationService();

  // Draw the path, using the Visualization API and the Elevation service.
  displayPathElevation(path, elevator, map);
}

function displayPathElevation(
  path: google.maps.LatLngLiteral[],
  elevator: google.maps.ElevationService,
  map: google.maps.Map
) {
  // Display a polyline of the elevation path.
  new google.maps.Polyline({
    path: path,
    strokeColor: "#0000CC",
    strokeOpacity: 0.4,
    map: map,
  });

  // Create a PathElevationRequest object using this array.
  // Ask for 256 samples along that path.
  // Initiate the path request.
  elevator
    .getElevationAlongPath({
      path: path,
      samples: 256,
    })
    .then(plotElevation)
    .catch((e) => {
      const chartDiv = document.getElementById(
        "elevation_chart"
      ) as HTMLElement;

      // Show the error code inside the chartDiv.
      chartDiv.innerHTML = "Cannot show elevation: request failed because " + e;
    });
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation({ results }: google.maps.PathElevationResponse) {
  const chartDiv = document.getElementById("elevation_chart") as HTMLElement;

  // Create a new chart in the elevation_chart DIV.
  const chart = new google.visualization.ColumnChart(chartDiv);

  // Extract the data from which to populate the chart.
  // Because the samples are equidistant, the 'Sample'
  // column here does double duty as distance along the
  // X axis.
  const data = new google.visualization.DataTable();

  data.addColumn("string", "Sample");
  data.addColumn("number", "Elevation");

  for (let i = 0; i < results.length; i++) {
    data.addRow(["", results[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: "none",
    // @ts-ignore TODO update to newest visualization library
    titleY: "Elevation (m)",
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// Load the Visualization API and the columnchart package.
// @ts-ignore TODO update to newest visualization library
google.load("visualization", "1", { packages: ["columnchart"] });

function initMap() {
  // The following path marks a path from Mt. Whitney, the highest point in the
  // continental United States to Badwater, Death Valley, the lowest point.
  const path = [
    { lat: 36.579, lng: -118.292 }, // Mt. Whitney
    { lat: 36.606, lng: -118.0638 }, // Lone Pine
    { lat: 36.433, lng: -117.951 }, // Owens Lake
    { lat: 36.588, lng: -116.943 }, // Beatty Junction
    { lat: 36.34, lng: -117.468 }, // Panama Mint Springs
    { lat: 36.24, lng: -116.832 },
  ]; // Badwater, Death Valley
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: path[1],
    mapTypeId: "terrain",
  });
  // Create an ElevationService.
  const elevator = new google.maps.ElevationService();

  // Draw the path, using the Visualization API and the Elevation service.
  displayPathElevation(path, elevator, map);
}

function displayPathElevation(path, elevator, map) {
  // Display a polyline of the elevation path.
  new google.maps.Polyline({
    path: path,
    strokeColor: "#0000CC",
    strokeOpacity: 0.4,
    map: map,
  });
  // Create a PathElevationRequest object using this array.
  // Ask for 256 samples along that path.
  // Initiate the path request.
  elevator
    .getElevationAlongPath({
      path: path,
      samples: 256,
    })
    .then(plotElevation)
    .catch((e) => {
      const chartDiv = document.getElementById("elevation_chart");

      // Show the error code inside the chartDiv.
      chartDiv.innerHTML = "Cannot show elevation: request failed because " + e;
    });
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation({ results }) {
  const chartDiv = document.getElementById("elevation_chart");
  // Create a new chart in the elevation_chart DIV.
  const chart = new google.visualization.ColumnChart(chartDiv);
  // Extract the data from which to populate the chart.
  // Because the samples are equidistant, the 'Sample'
  // column here does double duty as distance along the
  // X axis.
  const data = new google.visualization.DataTable();

  data.addColumn("string", "Sample");
  data.addColumn("number", "Elevation");

  for (let i = 0; i < results.length; i++) {
    data.addRow(["", results[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: "none",
    // @ts-ignore TODO update to newest visualization library
    titleY: "Elevation (m)",
  });
}

window.initMap = initMap;
index.js
サンプルを表示

サンプルを試す