エレベーションサービス

概要
標高をリクエストする
1. 地点の標高をリクエストする
2. ルート上の標高をリクエストする
標高のレスポンス
1. 標高のステータス
2. 標高の結果
標高の例

概要

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

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

これらのリクエストには、サービスの乱用を防ぐためにレート制限がかけられていますので、ご注意ください。静止した既知の場所における標高を計算したい場合は、エレベーションウェブサービスのドキュメントをご覧ください。

エレベーションサービスを利用すると、ハイキングやサイクリング用のアプリ、モバイル用の測位アプリ、低解像度の測量アプリを開発できます。

標高をリクエストする

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

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

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

上記のどちらのメソッドに対しても、返されるElevationResult と ElevationStatus オブジェクトを処理するために、callback メソッドを渡す必要があります。

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

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

{
  locations[]: LatLng
}

locations（必須）は、標高データを取得する地球上の地点を定義します。このパラメータには LatLng の配列を指定します。

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

ルート上でサンプリングした標高をリクエストする

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

{
  path[]: LatLng,
  samples: Number
}

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

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

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

標高のレスポンス

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

標高のステータス

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

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

このステータスコードが google.maps.ElevationStatus.OK であることを調べて、コールバックが正しく動作することを確認してください。

標高の結果

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

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

標高の例

以下のコード例は、LocationElevationRequest オブジェクトを使用して、マップ上でクリックした地点の標高を求めます。

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

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

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator.getElevationForLocations({
    'locations': [location]
  }, function(results, status) {
    infowindow.setPosition(location);
    if (status === google.maps.ElevationStatus.OK) {
      // 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');
      }
    } else {
      infowindow.setContent('Elevation service failed due to: ' + status);
    }
  });
}

例を見る（elevation-simple.html）

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

// Load the Visualization API and the columnchart package.
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.
  var 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

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

  // Create an ElevationService.
  var 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',
    opacity: 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
  }, plotElevation);
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation(elevations, status) {
  var chartDiv = document.getElementById('elevation_chart');
  if (status !== google.maps.ElevationStatus.OK) {
    // Show the error code inside the chartDiv.
    chartDiv.innerHTML = 'Cannot show elevation: request failed because ' +
        status;
    return;
  }
  // Create a new chart in the elevation_chart DIV.
  var 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.
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Sample');
  data.addColumn('number', 'Elevation');
  for (var i = 0; i < elevations.length; i++) {
    data.addRow(['', elevations[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: 'none',
    titleY: 'Elevation (m)'
  });
}

例を見る（elevation-paths.html）