ジオコーディング サービス

概要

ジオコーディングとは、住所(たとえば「東京都港区六本木 6-10-1」)を地理的座標(たとえば、緯度 35.6604282、経度 139.7269877)に変換するプロセスです。変換した座標は、マップ上に場所の目印を付ける場合や、位置指定を行う場合に使用できます。

リバース ジオコーディングとは、地理的位置を人間が判別可能な住所に変換するプロセスです。リバース ジオコーディング サービスでは、指定したプレイス ID の住所を探すこともできます。

Google Maps API に含まれるジオコーダのクラスを使用すると、ユーザーの入力に応じて動的にジオコーディングやリバース ジオコーディングができます。API を最初にロードした際には、ジオコーディング リクエストの初期割り当て量が付与されます。この割り当て量を使い果たした後に、追加でリクエストをすると、1 秒あたりのレート制限がかかります。静止した既知の住所に対してジオコーディングを行いたい場合は、ジオコーディング ウェブサービスのドキュメントをご覧ください。

ジオコーディング リクエスト

ジオコーディング サービスにアクセスすると、Google Maps API は外部サーバーに対して呼び出しを行うので、処理が非同期になります。そのため、リクエストの完了時に実行されるコールバック メソッドを渡して、結果を処理させる必要があります。なお、ジオコーダは複数の結果を返すこともあるので注意してください。

コード内で Google Maps API ジオコーディング サービスにアクセスするには、google.maps.Geocoder オブジェクトを使います。Geocoder.geocode() メソッドはジオコーディング サービスへのリクエストを開始し、入力したデータを含む GeocodeRequest オブジェクト リテラルと、レスポンスを受信したときに実行するコールバック メソッドを渡します。

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

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

必須パラメータ:以下のフィールドの中から、必ず 1 つだけ指定します。

  • address — ジオコードしたい住所。
  • location — 最も近い、判読可能な住所を取得したい場所の LatLng(または LatLngLiteral)。ジオコーダはリバースジオコーディングを行います。詳細については、リバースジオコーディングをご覧ください。
  • location — 最も近い、判読可能な住所を取得したい場所のプレイス ID。プレイス ID は、Google の他の API で使用できるユニークな識別子です。たとえば、Google Maps Roads API から返される placeId を使用してスナップ ポイントの住所を取得できます。プレイス ID の詳細については、プレイス ID の概要をご覧ください。placeId を渡すと、ジオコーダはリバースジオコーディングを行います。詳細については、リバースジオコーディングをご覧ください。

省略可能なパラメータ:

  • boundsLatLngBounds 内で、ジオコーディングの結果に極端なバイアスをかけます。bounds パラメータは、ジオコーダから返される結果に影響を与えますが、完全に制限するわけではありません。(詳細については、後述のビューポートのバイアスをご覧ください)
  • componentRestrictions — 指定した領域に結果を制限するのに使います。(詳細については、後述のコンポーネントのフィルタリングをご覧ください)
  • regionIANA 言語の region サブタグとして指定される地域コードです。多くの場合、これらのタグはよく使用される ccTLD(「トップレベル ドメイン」)の 2 文字の値に直接マッピングされますregion パラメータは、ジオコーダから返される結果に影響を与えますが、完全に制限するわけではありません。(詳細については、後述の地域コードのバイアスをご覧ください)

ジオコーディングのレスポンス

ジオコーディング サービスには、ジオコーダの結果を取得する際に実行されるコールバック メソッドが必要です。このコールバックは resultsstatus コードをこの順序で保持する 2 つのパラメータを渡す必要があります。

ジオコーディングの結果

GeocoderResults オブジェクトは、1 件のジオコーディングの結果を表します。なお、1 件のジオコード リクエストで、結果として複数のオブジェクトが返される場合もあります。

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

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

  • types[] は、返された結果のタイプを示す配列です。この配列には、結果として返された地物のタイプを表す 0 個以上のタグのセットが含まれています。たとえば「シカゴ」をジオコーディングすると、「シカゴ」が都市であること示す「locality」に加え、行政上のエンティティであることを示す「political」が返されます。
  • formatted_address は、このプレイスの住所が人の読める形式で含まれる文字列です。ほとんどの場合、この住所は「郵便の宛先」と同一ですが、国によっては異なる場合があります。(イギリスなど一部の国では、ライセンス上の制限があるため実際の郵便の宛先は配信できません)。通常、この住所は 1 つ以上の住所コンポーネントで構成されます。たとえば、「111 8th Avenue, New York, NY」という住所には、「111 8th Avenue」(通り)、「New York」(市)、「NY」(米国の州)という独立した住所コンポーネントが含まれています。これらの住所コンポーネントについては以下で説明します(タイプの詳細は、後述のタイプをご覧ください)。
  • address_components[] は上記のように、個別の住所コンポーネントを含む配列です。
  • partial_match は、元のリクエストに完全一致する住所は見つからなかったものの、部分一致する住所は見つかったことを示します。元のリクエストで住所の表記が間違っていたり、不完全である可能性があります。

    多くの場合、リクエストで渡された地域に番地が存在しないために部分一致が発生します。また、同じ地域内に複数の場所があるリクエストを行った場合も部分一致が返されます。たとえば、「21 Henr St, Bristol, UK」には、「Henry Street」と「Henrietta Street」の両方への部分一致が返されます。リクエストに表記が間違った住所コンポーネントが含まれている場合、ジオコーディング サービスが別の住所を提示することもある点に注意してください。この場合も、部分一致として結果が返されます。

  • place_id は、他の Google API と一緒に使用できるプレイス固有の識別子です。たとえば、place_idGoogle Places API ライブラリを一緒に使うと、電話番号や営業時間、ユーザーの口コミなどのローカル ビジネスの詳細情報を取得できます。詳しくは、プレイス ID の概要をご覧ください。
  • postcode_localities[] は、郵便番号に含まれるすべての地域を示す配列です。このフィールドは、結果の郵便番号に複数の地域が含まれる場合のみ存在します。
  • geometry には、次の情報が含まれます。

    • location には、ジオコーディングされた緯度と経度の値が含まれます。これは、フォーマットされた文字列ではなく、LatLng オブジェクトとして返されることに注意してください。
    • location_type には特定の地域に関する補足データが含まれます。現在サポートされている値は、以下のとおりです。

      • google.maps.GeocoderLocationType.ROOFTOP は、返された結果が正確なジオコーディングを反映していることを示します。
      • google.maps.GeocoderLocationType.RANGE_INTERPOLATED は、返された結果が(交差点などの)正確な 2 地点間で補間された近似値(通常は道路上)を反映していることを示します。補間された結果が返されるのは、番地に対してルーフトップ ジオコーディングが使用できない場合が一般的です。
      • google.maps.GeocoderLocationType.GEOMETRIC_CENTER は、返された結果がポリライン(道路など)やポリゴン(地域)などの幾何学的な中心であることを示します。
      • google.maps.GeocoderLocationType.APPROXIMATE は、返された結果が近似値であることを示します。

    • viewport には、返された結果に推奨されるビューポートが保存されます。
    • bounds(オプションで返される)には、返された結果をすべて含むことができる LatLngBounds が保存されます。これらの境界は、推奨されるビューポートと一致するとは限りません(たとえば、サンフランシスコのファラロン諸島は、厳密には市の一部ですが、ビューポートには含まれません)。

ジオコーダから返される住所は、ブラウザの言語設定か、API JavaScript をロードしたときに language パラメータで指定した言語で表示されます。(詳細については、ローカライズをご覧ください)。

住所コンポーネントのタイプ

返された結果には、住所タイプを示す types[] 配列が含まれます。これらのタイプは、特定の住所コンポーネントのタイプを示す address_components[] 配列内で返されることもあります。ジオコーダ内の住所には、タイプが複数あることもあります。タイプは「タグ」のようなもので、たとえば、大半の都市には politicallocality というタイプのタグが付いています。

HTTP ジオコーダがサポートし、返すタイプは以下のとおりです。

  • street_address は正確な番地を示します。
  • route は(US 101 などの)名前のあるルートを示します。
  • intersection は主要な交差点(主に 2 本の主要道路の交差点)を示します。
  • political は行政上のエンティティを示します。通常、このタイプは民政のポリゴンを示します。
  • country は国家を示し、一般的にはジオコーダから返される最上位のタイプです。
  • administrative_area_level_1 は国レベルの下の 1 次的な行政区画を示します。米国の場合、州がこの行政区画レベルに相当しますが、すべての国でこの行政区画レベルが存在するわけではありません。
  • administrative_area_level_2 は国レベルの下の 2 次的な行政区画を示します。米国の場合、郡がこの行政区画レベルに相当しますが、すべての国でこの行政区画レベルが存在するわけではありません。
  • administrative_area_level_3 は国レベルの下の 3 次的な行政区画を示します。このタイプは小規模な行政区域を示します。すべての国でこの行政区画レベルが存在するわけではありません。
  • administrative_area_level_4 は国レベルの下の 4 次的な行政区画を示します。このタイプは小規模な行政区域を示します。すべての国でこの行政区画レベルが存在するわけではありません。
  • administrative_area_level_5 は国レベルの下の 5 次的な行政区画を示します。このタイプは小規模な行政区域を示します。すべての国でこの行政区画レベルが存在するわけではありません。
  • colloquial_area はエンティティに対して一般に使用されている俗称を示します。
  • locality は市や地方自治体を示します。
  • sublocality は locality の下の 1 次的な下位地区を示します。一部の地域では、sublocality_level_1 から sublocality_level_5 までの追加タイプを受け取ります。各下位地区レベルは行政区画で、数が大きいほど区域は小さくなります。
  • neighborhood は名前のある地域を示します。
  • premise は名前のある場所を示します。通常は建物や共通の名前を持つ建物群です。
  • subpremise は名前のある場所の下のレベルの 1 次的な存在を示します。通常は共通の名前を持つ建物群の中にある 1 つの建物です。
  • postal_code は、国内で郵便物の宛先に使用される郵便番号を示します。
  • natural_feature は著名な地物を示します。
  • airport は空港を示します。
  • park は名前のある公園を示します。

タイプリストが空の場合は、特定の住所コンポーネントに対して既知のタイプが存在しないことを意味します。たとえば、フランスのリュディが、これに相当します。

上記の他に、住所コンポーネントには以下のタイプが表示されることがあります。

  • post_box は特定の郵便ポストを示します。
  • treet_number は正確な番地を示します。
  • floor は建物における階数を示します。
  • room は建物における部屋を示します。

ステータス コード

status コードは以下のいずれかの値を返します。

  • OK: エラーが発生しなかったことを示します。住所の解析が成功し、少なくとも 1 件のジオコードが返されました。
  • ZERO_RESULTS: ジオコーディングは成功したものの結果が返されなかったことを示します。これは、ジオコーダに存在しない address が渡された場合に発生することがあります。
  • OVER_QUERY_LIMIT: クエリ数が割り当て量を超えていることを示します。
  • REQUEST_DENIED: リクエストが拒否されたことを示します。
  • INVALID_REQUEST: 通常、照会条件(addresscomponentslatlngのいずれか)がないことを示します。
  • UNKNOWN_ERROR: サーバー エラーでリクエストが処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

下の例では、住所をジオコードして、返された緯度と経度が示す場所にマーカーを配置します。ここではハンドラを匿名の関数リテラルとして渡していることに注意してください。

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById("map"), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById("address").value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == google.maps.GeocoderStatus.OK) {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert("Geocode was not successful for the following reason: " + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

例を見る(geocoding-simple.html)

リバース ジオコーディング(住所検索)

一般的にジオコーディングとは、人間が読み取れる住所をマップ上の地点に変換することを意味します。逆ジオコーディングはその反対で、地図上の地点を人間が読み取れる住所に変換するプロセスを指します。

Geocoder はリバース ジオコーディングを直接サポートしています。テキストの address を指定する代わりに、location パラメータ内で、カンマで区切られた緯度と経度のセットを指定します。または placeId を指定して、プレイス ID に対応する住所を探すこともできます。

位置によるリバース ジオコーディング

以下の例では、緯度と経度の値をジオコーディングし、その場所に地図の中心を合わせ、フォーマットされた住所が入った情報ウィンドウを表示します。2 番目の結果(この例では地域名)も返されますが、1 番目の結果よりも明確ではありません。

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.731, lng: -73.997}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  var input = document.getElementById('latlng').value;
  var latlngStr = input.split(',', 2);
  var latlng = {lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1])};
  geocoder.geocode({'location': latlng}, function(results, status) {
    if (status === google.maps.GeocoderStatus.OK) {
      if (results[1]) {
        map.setZoom(11);
        var marker = new google.maps.Marker({
          position: latlng,
          map: map
        });
        infowindow.setContent(results[1].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

例を見る(geocoding-reverse.html)

なお、上の例では、(results[1] を選択して)2 番目の結果を示してあります。リバース ジオコーダーは複数の結果を返すこともあるので注意してください。ジオコーディングの「住所」には、郵便の宛て先となる住所だけでなく、その場所の地理的な名称も含まれます。たとえば、シカゴ市のある地点のジオコードを行うと、ジオコードされる地点には番地、都市(シカゴ)、州(イリノイ)、国(米国)などのラベルが付きます。これらは、どれもジオコーダに送られる住所です。また、リバース ジオコーダからは、これらの結果がすべて返されます。

リバース ジオコーダによる検索では、行政上のエンティティ(国、州、都市および周辺地域)、番地、郵便番号を照合します。

以下は、前のクエリから返された住所の全リストです。

results[0].formatted_address: "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
results[1].formatted_address: "Williamsburg, NY, USA",
results[2].formatted_address: "New York 11211, USA",
results[3].formatted_address: "Kings, New York, USA",
results[4].formatted_address: "Brooklyn, New York, USA",
results[5].formatted_address: "New York, New York, USA",
results[6].formatted_address: "New York, USA",
results[7].formatted_address: "United States"

住所は適合度の高い物から順に返されます。一般的には最も正確な住所が最も重要な結果で、それはこのケースにも当てはまります。返される住所のタイプは、最も具体的な番地から、周辺地域、都市、郡、州などの大規模な行政区画まで多岐にわたります。より一般的な住所をヒットさせたい場合は、results[].types フィールドを調べてみてください。

注:リバース ジオコーディングは科学的に厳密な手法ではありません。ジオコーダは許容範囲内で、できる限り近い住所の場所を検索しようとします。

プレイス ID によるリバース ジオコーディング

以下の例では、プレイス ID を受け付けて、該当する住所を検索し、その場所に地図の中心を合わせます。情報ウィンドウも表示されて、関連する場所の住所がフォーマットして示されています。

// Initialize the map.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.72, lng: -73.96}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a reverse geocode.
function geocodePlaceId(geocoder, map, infowindow) {
  var placeId = document.getElementById('place-id').value;
  geocoder.geocode({'placeId': placeId}, function(results, status) {
    if (status === google.maps.GeocoderStatus.OK) {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
          map: map,
          position: results[0].geometry.location
        });
        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

例を見る(geocoding-place-id.html)

ビューポートのバイアス

ジオコーディング サービスでは、(境界ボックスとして表現される)特定のビューポート内の結果を優先するように指定することもできます。そのためには、GeocodeRequest オブジェクト リテラル内で bounds パラメータを設定して、このビューポートの境界を定義します。バイアスをかけると境界内の結果だけが優先されますが、その境界の外により関連性の高いデータがある場合は、それらが結果に含まれることもあります。

たとえば「Winnetka」をジオコードすると、たいていはシカゴの郊外が結果として返されます。

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

ここで、bounds パラメータを指定して、ロサンゼルスのサン フェルナンド バレーを含むように境界ボックスを定義すると、そこの「Winnetka」という地域がこのジオコーディングの結果として返されるようになります。

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

地域コードのバイアス

region パラメータを使って、ジオコーディング サービスが特定の地域を優先して結果を返すよう明示的に設定することもできます。このパラメータには、IANA 言語の region サブタグとして指定される地域コードを使います。これらのタグはたいてい、「co.uk」が「uk」に対応するように、よく使用される ccTLD(「トップレベル ドメイン」)の 2 文字の値に直接マッピングされます。region タグが ISO-3166-1 コードをサポートする場合もありますが、これは ccTLD の値(「Great Britain」の「GB」など)とは異なることがあります。

ジオコーディング リクエストは、Google マップのメイン アプリケーションでジオコーディングを提供する全ドメインに対して送信できます。バイアスをかけると特定のドメインの結果だけが優先されますが、そのドメイン外により関連性の高いデータがある場合は、それらが結果に含まれることもあります。

たとえば、ジオコーディング サービスのデフォルト ドメインは米国に設定されているため、「Toledo」をジオコーディングすると次の結果が得られます。

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

ここで、region フィールドに 'es'(スペイン)を設定して「Toledo」をジオコーディングすると、今度はスペインの都市が返されます。

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

コンポーネントのフィルタリング

ジオコーディング サービスが特定のエリアを優先して結果を返すよう、明示的に設定することもできます。制限を指定するには、componentRestrictions パラメータを使います。フィルタは routelocalityadministrativeAreapostalCodecountry のいずれか、または複数から成ります。結果として返されるのは、すべてのフィルタに適合したものだけです。フィルタの値は、スペル訂正や部分一致など、他のジオコーディングのリクエストと同じメソッドをサポートしています。

例として、以下の関数では componentRestrictions パラメータを使って、countrypostalCode でフィルタをかけています。

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

フィードバックを送信...

Google Maps JavaScript API
Google Maps JavaScript API
ご不明な点がありましたら、Google のサポートページをご覧ください。