Google Maps JavaScript API v3

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

  1. 概要
  2. ジオコーディング リクエスト
  3. ジオコーディング レスポンス
    1. ジオコーディングの結果
    2. 住所コンポーネントのタイプ
    3. ステータス コード
  4. 逆ジオコーディング
  5. ビューポートのバイアス
  6. 地域コードのバイアス

概要

ジオコーディングとは、住所(「1600 Amphitheatre Parkway, Mountain View, CA」など)を地理座標(緯度 37.423021、経度 -122.083739 など)に変換する処理のことをいいます。地理座標を使用して、マーカーを配置したり地図の位置決めを行ったりできます。

Google Maps API は、ユーザーの入力から動的に住所をジオコーディングするジオコーダ クラスを備えています。サービスの不正使用を防ぐために、単位時間あたりのリクエスト数には制限があります。動的にではなく、既知の住所を静的にジオコーディングしたい場合は、ジオコーディング ウェブ サービスのドキュメントをご覧ください。

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

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

コード内で Google Maps API ジオコーディング サービスにアクセスするには、google.maps.Geocoder オブジェクトを使用します。Geocoder.geocode() メソッドはジオコーディング サービスへのリクエストを開始し、入力文字列を含む GeocodeRequest オブジェクト リテラルと、回答の受け取り時に実行するコールバック メソッドを渡します。

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

{
 address: string,
 latLng: LatLng,
 bounds: LatLngBounds,
 region: string
}

各フィールドの概要は次のとおりです。

  • address(必須*): ジオコーディングする住所。
  • latLng(必須*): この LatLng に最も近い、人間が読み取れる住所を取得します。
  • bounds(省略可能): この LatLngBounds の内部では、ジオコーディングの結果に大きくバイアスをかけます。(詳細については、下記のビューポートのバイアスをご覧ください。)
  • region(省略可能): IANA 言語の region サブタグで指定される地域コード。このタグは多くの場合、よく使用される ccTLD(「トップレベル ドメイン」)の 2 文字の値に直接対応します。(詳細については、下記の地域コードのバイアスをご覧ください。)

* 注: 検索のために address または latLng を渡します。(latLng を渡すと、ジオコーダによって「逆ジオコーディング」が行われます。詳細については、逆ジオコーディングをご覧ください。)

bounds パラメータと region パラメータは、ジオコーダからの結果に影響を与えますが、厳密に制限することはありません。

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

ジオコーディング サービスでは、ジオコーダの結果が取得されたときに実行するコールバック メソッドが必要です。このコールバックでは、2 つのパラメータを渡して、resultsstatus コードをこの順序で保持するようにします。ジオコーダから複数のエントリが返されることがあるため、GeocoderResults オブジェクト リテラルは配列を格納します。

ジオコーディングの結果

GeocoderResults オブジェクト リテラルは、1 つのジオコーディング結果を示します。オブジェクトの形式は次のとおりです:

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

各フィールドの概要は次のとおりです:

  • types[] は、返された結果の「タイプ」を示す配列です。この配列には結果で返された対象物のタイプを表す一連のタグが含まれます。たとえば、「Chicago」のジオコードは「Chicago」が市であることを示す「locality」を返します。また、行政上の存在であることを示す「political」を返します。
  • formatted_address: 人が読み取れる、この場所の住所を含む文字列です。多くの場合、この住所は「郵便の宛先」と同一ですが、国によっては異なる場合があります(イギリスなど一部の国では、ライセンス上の制限により、郵便の宛先となる住所そのものを配布することはできません。)通常、この住所は、1 件以上の住所コンポーネントから構成されます。たとえば、「111 8th Avenue, New York, NY」という住所には「111 8th Avenue」(番地)、「New York」(市)、「NY」(州)という別々の住所コンポーネントが含まれています。これらの住所コンポーネントについては、この後で説明します。(タイプの詳細については、下記のタイプをご覧ください。)
  • address_component[]: 前述のとおり、個別の住所コンポーネントを格納した配列です。
  • 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[] 配列内でも返されることがあり、特定の住所コンポーネントのタイプを示します。ジオコーダ内の住所には複数のタイプがあることがあります。タイプは「タグ」として考えることができます。たとえば多くの場合、都市には political タイプと locality タイプのタグが付いています。

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 次行政エンティティを示します。このタイプは、小規模な行政区分を示します。この行政レベルがない国もあります。
  • colloquial_area: 一般的に使用されている通称を示します。
  • locality: 都市や町などの政治的エンティティの地域を示します。
  • sublocality: 地域の下の第 1 次行政エンティティを示します。
  • neighborhood: 指定された場所の周辺地区を示します。
  • premise: 名前のある場所を示します。通常は共通の名前を持つ建物や建物の集合体です。
  • subpremise: 指定された場所の下の第 1 次エンティティを示します。通常は、共通の名前を持つ建物の集合体内の建物 1 棟です。
  • postal_code: 対象の国内で郵便物の宛先として使用される郵便番号を示します。
  • natural_feature: 特徴的な地勢を示します。
  • airport: 空港を示します。
  • park: 名前のある公園を示します。

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

  • post_box: 特定の私書箱を示します。
  • street_number: 正確な番地を示します。
  • floor: 建物の住所の階数を示します。
  • room: 建物の住所の部屋を示します。

ステータス コード

この status コードからは、次の値のいずれかが返されます:

  • google.maps.GeocoderStatus.OK: ジオコーディングが成功したことを示します。
  • google.maps.GeocoderStatus.ZERO_RESULTS: ジオコードは成功しましたが、結果が返されなかったことを示します。遠隔地にある存在しない address または latng がジオコードに渡されると、このような状態になることがあります。
  • google.maps.GeocoderStatus.OVER_QUERY_LIMIT: リクエストが割り当て量を超えていることを示します。
  • google.maps.GeocoderStatus.REQUEST_DENIED: 何らかの理由でリクエストが拒否されたことを示します。
  • google.maps.GeocoderStatus.INVALID_REQUEST: 一般的に、クエリ(address または latLng)が不足していることを示します。

この例では、住所をジオコーディングして、返される緯度と経度の値が示す場所にマーカーを設定します。ハンドラは匿名の関数リテラルとして渡されます。

  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,
      mapTypeId: google.maps.MapTypeId.ROADMAP
    }
    map = new google.maps.Map(document.getElementById("map_canvas"), 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_canvas" 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 を渡すのではなく、緯度と経度のペアをカンマで区切って latLng パラメータで渡します。

次の例では、緯度/経度の値をジオコーディングし、その場所を地図の中央にして、フォーマットした住所を示す情報ウィンドウを表示します。2 番目に返される結果は、最初のもの(この例では周辺地区の名前)よりも具体性が低くなります:

  var geocoder;
  var map;
  var infowindow = new google.maps.InfoWindow();
  var marker;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(40.730885,-73.997383);
    var mapOptions = {
      zoom: 8,
      center: latlng,
      mapTypeId: google.maps.MapTypeId.ROADMAP
    }
    map = new google.maps.Map(document.getElementById("map_canvas"), mapOptions);
  }

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

上記の例では、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 フィールドを調べます。

注: 逆ジオコーディングは科学的に正確というわけではありません。ジオコーダは、一定の許容範囲内で最も近い、住所の特定が可能な場所を探そうとします。

例を表示(geocoding-reverse.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"
  }
}

ただし、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"
  }
}

地域コードのバイアス

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

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

たとえば、「Toledo」をジオコーディングすると、ジオコーディング サービスのデフォルトのドメインが「United States」に設定されているため、次のような結果が返されます:

{
  "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"]
  }]
}

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"]
  }]
}

認証が必要です

この操作には Google+ でのログインが必要です。

ログインしています...

この操作には Google デベロッパーに対する許可が必要です。