以上で完了です。

開発を始めるには、デベロッパー ドキュメント をご覧下さい。

Google Places API Web Service をアクティベートする

まず初めに Google Developers Console で次の作業を行います。

  1. プロジェクトを作成または選択する
  2. Google Places API Web Service をアクティベートする
  3. 適切なキーを作成する
続ける

プレイス オートコンプリート

プレイス オートコンプリート サービスは、HTTP リクエストに基づいてプレイスの予測を返すウェブサービスです。リクエストでは、テキスト表記の検索文字列を指定します。また、必要に応じて地域を指定することもできます。このサービスを使用すれば、テキストベースの場所検索用のオートコンプリート機能を活用して、ユーザーの入力に応じてお店やサービス、住所、スポットなどのプレイスを返すことができます。

プレイス オートコンプリート リクエスト

プレイス オートコンプリート サービスは Google Places API Web Service の一部として、API キーと割り当て量を Google Places API Web Service と共有します。

プレイス オートコンプリート サービスでは文字列の完全一致と部分一致が可能です。したがって、アプリケーションはユーザーの入力に応じてクエリを送信し、プレイスの予測を即座に提供できます。

目的のプレイスを選択しやすい形式で予測が表示されます。返されたプレイスの詳細情報が必要な場合は、プレイス詳細リクエストを送信できます。

プレイス オートコンプリート リクエストは、次の形式の HTTP URL です。

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

output には次のいずれかの値を設定します。

  • json(推奨)は、出力が JSON(JavaScript Object Notation)であることを示します。
  • xml は、出力が XML であることを示します。

プレイス オートコンプリート リクエストを開始するには、必須のパラメータがいくつかあります。URL の標準と同様に、パラメータはすべてアンパサンド(&)文字を使用して区切ります。各パラメータと有効な値のリストを次に示します。

必須パラメータ

  • input: 検索するテキスト文字列。プレイス オートコンプリート サービスはこの文字列と一致する候補を、関連性の高い順に並べて結果として返します。
  • key: アプリケーションの API キーです。このキーを使ってアプリケーションを識別し、割り当て量を管理します。詳細については、キーの取得をご覧ください。Google Maps APIs Premium Plan のユーザーは、Premium Plan 購入の一環として作成される専用の API プロジェクトを使用する必要があります。

省略可能なパラメータ

  • offset: input キーワード内で、サービスが予測の照合に使用する最後の文字の位置を示します。たとえば、input が「Google」で、offset が 3 の場合、サービスは「Goo」と照合します。offset によって決定される文字列は、input キーワード内の最初の単語のみと照合されます。たとえば、input キーワードが「Google abc」で、offset が 3 の場合、サービスは「Goo abc」と照合します。offset を指定しない場合、サービスは input の文字列全体を使用します。通常、offset はテキストの挿入位置に設定します。
  • location: プレイス情報を取得したい位置を示します。緯度経度の形式で指定してください。
  • radius: 検索の結果を返す場所の範囲(メートル単位)を示します。radius を設定すると、指定した場所を優先した結果が返されます(ただし、指定場所のみに限定されるわけではありません)。以下の場所のバイアス場所の制限をご覧ください。
  • language: 検索結果を返すときに使用する言語を示す言語コードです(指定できる場合)。また、検索では選択された言語が優先されます。選択された言語での結果は、より上位に表示されます。サポートされる言語とそのコードのリストをご覧ください。サポートされる言語は頻繁に更新されるため、このリストがすべてのサポート言語を網羅しているとは限りません。言語を指定しないと、プレイス オートコンプリート サービスではリクエストの送信元のドメインの言語が使用されます。
  • types: 返されるプレイス結果のタイプです。下記のプレイスタイプをご覧ください。タイプを指定しないと、すべてのタイプが返されます。
  • components: 検索結果を限定したいプレイスのグループです。現時点では、components を使って国を基準にフィルタリングできます。国は ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。たとえば、components=country:fr では、検索結果がフランス国内のプレイスに限定されます。
  • strictbounds: locationradius で定義された地域内のプレイスのみを返します。これはバイアスではなく制限です。つまり、この地域外の結果は、ユーザー入力に一致する場合でも返されません。

場所のバイアス

location パラメータと radius パラメータを使用すると、指定した範囲内を優先するように検索結果にバイアスをかけることができます。プレイス オートコンプリート サービスは、指定した範囲内の結果を優先して表示するようになりますが、指定した範囲外の結果が返されることもあります。components パラメータを使用すれば、指定した国内のプレイスのみが表示されるように結果をフィルタリングできます。

ヒント:通常、お店やサービスの検索結果は掲載順位がそれほど高くないため、検索範囲が広い場合は表示されません。establishment と geocode を組み合わせて検索した結果にお店やサービスを表示するには、狭い範囲を指定するか、types=establishment を使用して検索結果をお店やサービスに限定します。

場所の制限

strictbounds パラメータを追加して、検索結果を location および radius パラメータによって定義された地域に制限することもできます。これにより、プレイス オートコンプリート サービスは、その地域内の検索結果のみを返すようになります。

プレイスタイプ

プレイス オートコンプリート リクエストで特定のタイプに結果を限定するには、types パラメータを指定します。このパラメータには、下記のサポートされるタイプに記載されているタイプやタイプ コレクションを指定します。何も指定しないと、すべてのタイプが返されます。通常、使用できるタイプは 1 つのみです。例外として、geocode タイプと establishment タイプを混在させることもできますが、この場合はタイプを指定しない場合と同じ結果になります。サポートされるタイプは次のとおりです。

  • geocode では、お店やサービスの情報は返されず、ジオコーディングの結果のみが返されます。通常、このリクエストははっきり特定できない場所を明確にするために使用します。
  • address では、ジオコーディングの結果のみが、正確な住所とともに返されます。通常、このリクエストはユーザーが完全な住所を指定して検索することがわかっている場合に使用します。
  • establishment では、お店やサービスの結果のみが返されます。
  • (regions) タイプ コレクションでは次のタイプと一致する結果がすべて返されます。
    • locality(地区)
    • sublocality(下位地区)
    • postal_code(郵便番号)
    • country(国)
    • administrative_area_level_1(行政区画レベル 1)
    • administrative_area_level_2(行政区画レベル 2)
  • (cities) タイプ コレクションでは、locality(地区)または administrative_area_level_3(行政区画レベル 3)と一致する結果が返されます。

オートコンプリート リクエストの例

次のサンプルは、カリフォルニア州サンフランシスコを中心とする地域で、文字列「Amoeba」を含むお店やサービスをリクエストします。

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

次のサンプルは、サンフランシスコのアシュベリー通りとヘイト通りから 500 メートル以内の範囲にある結果のみを返します。

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

次のサンプルは、「Vict」を含む住所をリクエストし、結果をフランス語で返します。

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY

次のサンプルは、「Vict」を含む都市をリクエストし、結果をブラジル ポルトガル語で返します。

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY

これらのサンプルの API キーの値は自分のものに置き換えてください。

プレイス オートコンプリート レスポンス

プレイス オートコンプリート レスポンスは、リクエストの URL パスの output フラグで指定された形式で返されます。下記は、次のパラメータのクエリで返される可能性のある結果の例です。

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
XML
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

JSON レスポンスには、2 つのルート要素が含まれます。

  • status にはリクエストについてのメタデータが含まれます。下記のステータス コードをご覧ください。
  • predictions にはプレイスの配列と各プレイスの情報が含まれます。これらの結果についてはプレイス オートコンプリートの結果をご覧ください。Google Places API Web Service は最大 5 つの結果を返します。

結果の中で特に重要なのが place_id 要素です。この要素は、プレイスの詳細情報を別のクエリでリクエストする際に使用します。プレイス詳細リクエストをご覧ください。

JSON レスポンスの解析方法については、Javascript による JSON の処理をご覧ください。

XML レスポンスは 1 つの <AutocompletionResponse> 要素と 2 種類の子要素で構成されます。

  • 1 つの <status> 要素にはリクエストについてのメタデータが含まれます。下記のステータス コードをご覧ください。
  • <prediction> 要素(ゼロ個以上)にはそれぞれ 1 つのプレイスに関する情報が含まれます。これらの結果についてはプレイス オートコンプリートの結果をご覧ください。Google Places API Web Service は最大 5 つの結果を返します。

別の理由からアプリケーションで xml を使用する必要がない限り、Google では、優先出力フラグとして json を使用することをお勧めしています。XML ツリーの処理では、適切なノードと要素を参照するように、ある程度の配慮が求められます。XML の処理方法については、XPath による XML の処理をご覧ください。

ステータス コード

プレイス オートコンプリート レスポンス オブジェクトの status フィールドには、リクエストのステータスが含まれます。プレイス オートコンプリート リクエストが失敗した原因を追跡できるようにデバッグ情報が含まれることもあります。status フィールドには次の値が含まれます。

  • OK: エラーが発生せず、少なくとも 1 件の結果が返されたことを示します。
  • ZERO_RESULTS: 検索は成功したものの結果が返されなかったことを示します。これは、検索に遠隔地の bounds が渡された場合に発生することがあります。
  • OVER_QUERY_LIMIT: リクエスト数が割り当て量を超えていることを示します。
  • REQUEST_DENIED: リクエストが拒否されたことを示します。通常は、無効な key パラメータが指定されていないことが原因です。
  • INVALID_REQUEST: 通常は、input パラメータが指定されていないことを示します。

エラー メッセージ

プレイス サービスで OK 以外のステータス コードが返された場合、レスポンス オブジェクト内に error_message フィールドが付加されている場合があります。このフィールドには、返されたステータス コードの原因に関する詳細情報が含まれています。

プレイス オートコンプリートの結果

プレイス サービスが JSON 形式で検索結果を返す場合、検索結果は predictions 配列に格納されます。サービスから返す結果がない(たとえば、location が遠く離れている)場合でも、空の predictions 配列が返されます。XML レスポンスは、ゼロ個以上の <prediction> 要素で構成されます。

それぞれの予測結果には、次のフィールドが含まれます。

  • description には、返された結果が人の読める形式で名前として含まれます。establishment の場合、通常は店名やサービス名です。
  • place_id は、プレイスを一意に識別するテキスト表記の ID です。プレイスの情報を取得するには、この ID を Google Places API Web Service リクエストの placeId フィールドに渡します。プレイス ID の詳細については、プレイス ID の概要をご覧ください。
  • reference には、一意のトークンが含まれます。プレイス詳細リクエストでは、このトークンを使ってこのプレイスに関する追加情報を取得できます。このトークンはプレイスを一意に識別しますが、その逆は成り立ちません。プレイスには複数の有効な reference トークンがある場合があります。どのプレイスでも、検索ごとに同じトークンが返されるとは限りません。注: place_id の導入により、reference は廃止されました。このページの廃止予定のお知らせをご覧ください。
  • id には、このプレイスを示す一意で不変の ID が含まれます。この ID を使用してこのプレイスに関する情報を取得することはできませんが、このプレイスに関するデータを統合したり、個々の検索でプレイス ID を確認したりできます。注: place_id の導入により、id は廃止されました。このページの廃止予定のお知らせをご覧ください。
  • terms には、返された description の各セクションを識別するキーワードの配列が含まれます(通常、description のセクションはコンマで区切られます)。配列内の各エントリは、キーワードのテキストを含む value フィールドと、description 内でのこのキーワードの開始位置を示す offset フィールド(Unicode の文字数)で構成されます。
  • types には、このプレイスに適用されるタイプの配列が含まれます。たとえば [ "political", "locality" ][ "establishment", "geocode" ] です。
  • matched_substrings には、offset 値と length を持つ配列が含まれます。これらによって、予測の結果テキストにおける入力キーワードの位置が表され、必要に応じてそのキーワードを強調表示できます。

sensor パラメータ

Google Places API Web Service では、以前はユーザーの位置情報の検出にアプリケーションでセンサーを使用するかどうかを示すため sensor パラメータを含める必要がありましたが、このパラメータは必要なくなりました。

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