このプロダクトまたは機能は、従来版のステータスです。従来版のステータスの詳細については、従来版のサービスと機能をご覧ください。Places API（新規）に移行するには、移行ガイドをご覧ください。

Place Autocomplete（従来版）

欧州経済領域（EEA）のデベロッパー

注: サーバーサイドとクライアントサイドのライブラリ

Places API は、Google マップサービス向け Java クライアント、Python クライアント、Go クライアント、Node.js クライアントでも利用できます。Places API とクライアントライブラリは、サーバーアプリケーションで使用するためのものです。

クライアントサイドアプリケーションを構築する場合は、Places SDK for Android（新版）、Places SDK for iOS（新版）、プレイスライブラリ、Maps JavaScript API をご覧ください。

Place Autocomplete（従来版）は、HTTP リクエストに応じて場所の候補を返すウェブサービスです。リクエストでは、テキスト検索文字列とオプションの地理的境界を指定します。このサービスを使用すると、ユーザーが入力したテキストベースの地理検索に対して、お店やサービス、住所、スポットなどの場所を返すことで、オートコンプリート機能を提供できます。

Place Autocomplete（従来版）リクエスト

Place Autocomplete（以前のバージョン）は Places API の一部であり、Places API と API キーと割り当てを共有します。

Place Autocomplete（従来版）は、完全な単語や部分文字列を照合して、場所の名前や住所、Plus Codes を解決できます。これにより、アプリケーションはユーザーの入力に合わせて随時クエリを送信し、場所の候補をリアルタイムで表示することができます。

プラスコードは正しい形式で入力する必要があります。つまり、プラス記号は %2B に URL エスケープし、スペースは %20 に URL エスケープする必要があります。

グローバルコードは、4 文字のエリアコードと 6 文字以上のローカルコードです。たとえば、URL エスケープのグローバルコード 849VCWC8+R9 は 849VCWC8%2BR9 です。
複合コードは、明示的な場所を含む 6 文字以上のローカルコードです。たとえば、URL エスケープされた複合コード CWC8+R9 Mountain View, CA, USA は CWC8%2BR9%20Mountain%20View%20CA%20USA になります。

返される予測は、ユーザーが希望する場所を選択する際に役立つように、ユーザーに提示されることを想定して設計されています。返された場所の詳細情報が必要な場合は、Place Details（Legacy）リクエストを送信できます。

Place Autocomplete（従来版）リクエストは、次の形式の HTTP URL です。

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

ここで、output には次のいずれかの値を指定できます。

json（推奨）は、JavaScript Object Notation（JSON）形式で出力することを示します。
xml は、出力を XML として示す

Place Autocomplete（従来版）リクエストを開始するには、特定のパラメータが必要です。URL の標準規則と同様に、すべてのパラメータはアンパサンド（&）文字を使用して区切ります。パラメータとその可能な値のリストを以下に示します。

必須パラメータ

入力

検索するテキスト文字列。Place Autocomplete サービスはこの文字列と一致する候補を、関連性の高い順に並べて結果として返します。

オプションパラメータ

#components

検索結果を制限する場所のグループ。コンポーネントを使用して、最大 5 つの国でフィルタできます。国は、ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。たとえば、components=country:fr を指定すると、検索結果はフランス国内の場所に限定されます。複数の国は、複数の country:XX フィルタとして渡す必要があります。区切り文字にはパイプ文字 | を使用します。たとえば、components=country:us|country:pr|country:vi|country:gu|country:mp と指定すると、検索結果は米国およびその未編入組織準州内の場所に限定されます。

注: 国コードを使用して予期しない結果が返される場合は、対象の国や属領、地理的に重要な特別な地域を含むコードを使用しているか確認してください。コードの情報については、Wikipedia の ISO 3166 国コードのリストか、ISO オンライン参照プラットフォームをご覧ください。
language

結果を返す言語。
- サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
- language が指定されていない場合、API は Accept-Language ヘッダーで指定された優先言語を使用しようとします。
- API は、ユーザーと地元住民の両方が読める番地を可能な限り提供します。この目標を達成するため、優先言語を考慮し、必要に応じてユーザーが読める文字に音訳して、現地の言語で住所を返します。その他の住所はすべて、優先言語で返されます。住所コンポーネントはすべて同じ言語で返されます。この言語は最初のコンポーネントから選択されます。
- 優先言語で名前が使用できない場合、API は最も近い一致を使用します。
- 優先言語は、API が返す結果のセットと、それらが返される順序にわずかな影響を与えます。ジオコーダーは、言語によって略語（通りの種類の略語など）の解釈が異なります。また、ある言語では有効でも別の言語では有効でない同義語もあります。たとえば、ハンガリー語では utca と tér は通りの同義語です。
ロケーション

プレイス情報を取得する中心点。これは latitude,longitude として指定する必要があります。ロケーションを指定する場合は、radius パラメータも指定する必要があります。radius が指定されていない場合、location パラメータは無視されます。

テキスト検索 API を使用する場合、`query` に `Market in Barcelona` などの明示的な場所が含まれていると、`location` パラメータがオーバーライドされることがあります。
locationbias

半径と緯度/経度、または長方形の点を表す 2 つの緯度/経度ペアを指定して、指定した地域の検索結果を優先します。このパラメータが指定されていない場合、API はデフォルトで IP アドレスバイアスを使用します。
- IP バイアス: IP アドレスバイアスを使用するように API に指示します。文字列 ipbias を渡します（このオプションには追加のパラメータはありません）。
- 円形: 半径をメートル単位で指定する文字列と、緯度/経度を 10 進数で指定する文字列。形式は次のようにします。circle:radius@lat,lng。
- 矩形: 矩形の南西と北東の点を表す 2 つの緯度 / 経度のペアを 10 進数で指定する文字列。rectangle:south,west|north,east の形式を使用します。東西の値は -180 ～ 180 の範囲にラップされ、南北の値は -90 ～ 90 の範囲にクランプされます。
locationrestriction

半径と緯度/経度、または矩形の点を表す 2 つの緯度/経度のペアを指定して、結果を特定のエリアに制限します。
- 円形: 半径をメートル単位で指定する文字列と、緯度/経度を 10 進数で指定する文字列。形式は次のようにします。circle:radius@lat,lng。
- 矩形: 矩形の南西と北東の点を表す 2 つの緯度 / 経度のペアを 10 進数で指定する文字列。rectangle:south,west|north,east の形式を使用します。東西の値は -180 ～ 180 の範囲にラップされ、南北の値は -90 ～ 90 の範囲にクランプされます。
offset

サービスが予測のマッチングに使用する最後の文字の入力語句内の位置。たとえば、入力が Google でオフセットが 3 の場合、サービスは Goo と一致します。オフセットによって決定された文字列は、入力語句の最初の単語とのみ照合されます。たとえば、入力語句が Google abc でオフセットが 3 の場合、サービスは Goo abc との照合を試みます。オフセットが指定されていない場合、サービスは用語全体を使用します。通常、オフセットはテキストカーソルの位置に設定します。
origin

目的地までの直線距離を計算する起点（distance_meters として返されます）。この値を省略すると、直線距離は返されません。latitude,longitude として指定する必要があります。
半径

場所の結果を返す距離（メートル単位）を定義します。location パラメータと radius パラメータを渡すことで、バイアスを設定し、指定した円の範囲内の結果を優先します。これにより、プレイスサービスが指定した範囲内を優先するように検索結果を絞り込むことができますが、指定した範囲外の結果が返されることもあります。

半径は、検索の種類や他のパラメータに応じて、自動的に最大値にクランプされます。
- 予測入力: 50,000 メートル
- Nearby Search:
  - keyword または name の場合: 50,000 メートル
  - keyword または name がない場合
    - 最大 50,000 メートル。rankby パラメータとは無関係に、エリアの密度に基づいて動的に調整されます。
    - rankby=distance を使用すると、半径パラメータは受け入れられず、INVALID_REQUEST が返されます。
- Query Autocomplete: 50,000 メートル
- テキスト検索: 50,000 メートル
地域

地域コード。ccTLD（「トップレベルドメイン」）の 2 文字の値として指定します。ほとんどの ccTLD コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」（厳密には「グレートブリテンおよび北アイルランド連合王国」のエンティティ用）です。
sessiontoken

課金目的で予測入力セッションを識別するランダムな文字列。

セッションは、ユーザーが検索語句を入力し始めたときに開始され、ユーザーが場所を選択し、Place Details が呼び出されると終了します。セッションによっては、複数の検索語句が入力された後に、1 つの場所が選択される場合もあります。セッション内の各リクエストで使用される API キーは、同じ Google Cloud Console プロジェクトに属している必要があります。セッションが終了すると、トークンは無効になります。アプリでは、セッションごとに新しいトークンを生成する必要があります。sessiontoken パラメータを省略する場合や、セッショントークンを再利用する場合は、セッショントークンが指定されていない場合と同様にセッションが課金されます（各リクエストが個別に課金されます）。

次のガイドラインに従うことをおすすめします。
- すべての予測入力セッションでセッショントークンを使用します。
- セッションごとに新しいトークンを生成します。バージョン 4 の UUID を使用することをおすすめします。
- セッション内のすべての Place Autocomplete リクエストと Place Details リクエストで使用される API キーが、同じ Cloud Console プロジェクトに属していることを確認します。
- 新しいセッションごとに固有のセッショントークンを渡すようにしてください。複数のセッションで同じトークンを使用すると、リクエストごとに課金されます。
strictbounds

location と radius で指定した領域に厳密に含まれる場所のみを返します。これはバイアスではなく制限です。つまり、指定領域外の場所は、たとえユーザー入力と一致していても返されません。
タイプ

Place Autocomplete リクエストで特定のタイプに結果を限定するには、types パラメータを指定します。このパラメータには、プレイスタイプに記載されているタイプまたはタイプのコレクションを指定します。何も指定しないと、すべてのタイプが返されます。

プレイスには、表 1 または表 2に記載されているタイプの単一のプライマリタイプのみを指定できます。たとえば、食事を提供するホテルは types=restaurant ではなく types=lodging のみで返されることがあります。

types パラメータの値には、次のいずれかを指定できます。
- 表 1 または表 2 の値を最大 5 つ。複数の値を指定する場合は、各値を |（縦棒）で区切ります。次に例を示します。
  
  types=book_store|cafe
- 表 3 のサポートされているフィルタのいずれか 1 つ。型コレクションを混在させることはできません。
注: geocode と establishment は表 2 の一部ですが、Place Autocomplete リクエストフィルタで、表 1、2、3 の他のタイプと組み合わせることはできません。

次の場合、リクエストは INVALID_REQUEST エラーで拒否されます。
- 指定したタイプの数が 5 個より多い。
- 認識できないタイプが存在する。
- 表 1 または表 2 のタイプと、表 3 のフィルタが混在している。
注: types パラメータは、場所のプライマリタイプでのみ機能します。場所に関連付けられているすべてのタイプでは機能しません。すべての場所にプライマリタイプがありますが、すべてのプライマリタイプが Places API（New）でサポートされているわけではありません。サポートされているタイプには、表 1 または表 2 に記載されているタイプが含まれます。

Place Autocomplete（従来版）の例

カリフォルニア州サンフランシスコを中心とするエリア内で「Amoeba」という文字列を含む施設をリクエストします。

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

同じリクエストで、サンフランシスコのアシュベリーストリートとハイトストリートから 500 メートル以内の結果に制限した場合:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

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

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

「Vict」を含む都市をリクエストし、ブラジルポルトガル語で結果を取得します。

URL

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

curl

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

これらの例では、API キーをご自身のキーに置き換える必要があります。

Place Autocomplete（従来版）のレスポンス

Place Autocomplete（レガシー）のレスポンスは、リクエストの URL パス内の output フラグで示された形式で返されます。次の結果は、次のパラメータを含むクエリに対して返される可能性のある結果を示しています。

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

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>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <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>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

フィールド	必須	タイプ	説明
`predictions`	required	Array<PlaceAutocompletePrediction>	予測の配列が含まれています。詳しくは、PlaceAutocompletePrediction をご覧ください。
`status`	required	PlacesAutocompleteStatus	リクエストのステータスが格納されます。リクエストが失敗した原因を追跡できるようにデバッグ情報が格納される場合もあります。詳しくは、PlacesAutocompleteStatus をご覧ください。
`error_message`	省略可	文字列	サービスが `OK<` 以外のステータスコードを返す場合、レスポンスオブジェクト内に `error_message` フィールドが追加されることがあります。このフィールドには、指定されたステータスコードの理由に関する詳細情報が含まれます。このフィールドは常に返されるわけではなく、その内容は変更される可能性があります。
`info_messages`	省略可	Array<string>	サービスがリクエスト仕様に関する追加情報を返す場合、レスポンスオブジェクト内に `info_messages` フィールドが追加されることがあります。このフィールドは、リクエストが成功した場合にのみ返されます。常に返されるとは限りません。また、内容は変更される可能性があります。

結果の中で特に重要なのは place_id 要素です。この要素を使用すると、別のクエリで場所に関するより具体的な詳細をリクエストできます。Place Details（以前のバージョン）リクエストをご覧ください。

XML レスポンスは、次の 2 種類の子要素を持つ単一の <AutocompletionResponse> 要素で構成されます。

単一の <status> 要素には、リクエストに関するメタデータが含まれます。下記のステータスコードをご覧ください。
0 個以上の <prediction> 要素。それぞれに 1 つの場所に関する情報が含まれます。これらの結果については、Place Autocomplete（従来版）の結果をご覧ください。Places API は最大 5 件の結果を返します。

アプリケーションで何らかの理由で xml が必要な場合を除き、優先出力フラグとして json を使用することをおすすめします。XML ツリーの処理では、適切なノードと要素を参照するように注意する必要があります。XML の処理については、XPath を使用した XML の処理をご覧ください。

一部の予測入力候補では、プレイス ID の Place Details（Legacy）レスポンスに street_number 住所コンポーネントが存在しない場合があります。多くの場合は、住所を補間できない場所でそのようなことが起こります。その場合は、予測の types 配列に「route」が含まれます。description に数字が含まれる予測入力候補（入力語句が一致）で、プレイス ID の Place Details（Legacy）レスポンスに番地が含まれるのは、その予測の types 配列に次の 1 つ以上が含まれている場合のみです。

street_address（住所）
premise（建物名）
establishment（施設）

PlacesAutocompleteStatus

サービスから返されるステータスコード。

OK は、API リクエストが成功したことを示します。
ZERO_RESULTS。検索は成功したが、結果が返されなかったことを示します。これは、検索に遠隔地の境界が渡された場合に発生することがあります。
INVALID_REQUEST は、API リクエストが不正な形式であることを示します。通常は、input パラメータが欠落していることが原因です。
OVER_QUERY_LIMIT は、次のいずれかを示します。
- QPS の上限を超えています。
- アカウントで課金が有効になっていません。
- 1 か月 $200 のクレジットまたはご自身で設定した使用量の上限を超えている。
- 設定したお支払い方法が無効になっている（クレジットカードの期限切れなど）。
このエラーの解決方法について詳しくは、マップのよくある質問をご覧ください。
REQUEST_DENIED は、リクエストが拒否されたことを示します。通常、次の理由が考えられます。
- リクエストに API キーがありません。
- key パラメータが無効です。
UNKNOWN_ERROR は、不明なエラーが発生したことを示します。

Places サービスが検索結果を JSON で返す場合、それらは predictions 配列内に配置されます。サービスが結果を返さない場合（location がリモートの場合など）でも、空の predictions 配列が返されます。XML レスポンスは、0 個以上の <prediction> 要素で構成されます。

PlaceAutocompletePrediction

フィールド	必須	タイプ	説明
`description`	required	文字列	返された結果の人が読める形式の名前が含まれます。`establishment` の結果の場合、通常はビジネス名です。このコンテンツはそのまま読み取られます。フォーマット済み住所をプログラムで解析しないでください。
`matched_substrings`	required	Array<PlaceAutocompleteMatchedSubstring>	入力された単語が予測結果のテキスト内のどこにあるかを示す部分文字列のリスト。このリストを使用すると、単語が選択された場合にハイライト表示できます。詳しくは、PlaceAutocompleteMatchedSubstring をご覧ください。
`structured_formatting`	required	PlaceAutocompleteStructuredFormat	予測入力の結果に表示できる、事前フォーマット済みのテキストを提供します。このコンテンツはそのまま読み取られます。フォーマット済み住所をプログラムで解析しないでください。詳細については、PlaceAutocompleteStructuredFormat をご覧ください。
`terms`	required	Array<PlaceAutocompleteTerm>	返された説明の各セクションを識別する用語の配列が含まれます（説明のセクションは通常、カンマで終わります）。配列内の各エントリには、用語のテキストを含む `value` フィールドと、説明内のこの用語の開始位置を Unicode 文字数で定義する `offset` フィールドがあります。詳細については、PlaceAutocompleteTerm をご覧ください。
`distance_meters`	省略可	integer	原点からの直線距離（メートル単位）。このフィールドは、`origin` を使用して行われたリクエストに対してのみ返されます。
`place_id`	省略可	文字列	場所を一意に識別するテキスト表記の ID。場所に関する情報を取得するには、この ID を Places API リクエストの placeId フィールドに渡します。プレイス ID について詳しくは、プレイス ID の概要をご覧ください。
`reference`	省略可	文字列	`reference` は非推奨になりました。 place_id をご覧ください。
`types`	省略可	Array<string>	この場所に適用されるタイプの配列が含まれます。たとえば、`[ "political", "locality" ]` や `[ "establishment", "geocode", "beauty_salon" ]` です。配列には複数の値を含めることができます。詳しくは、プレイスタイプをご覧ください。

PlaceAutocompleteMatchedSubstring

フィールド	必須	タイプ	説明
`length`	required	数値	予測結果のテキスト内の一致した部分文字列の長さ。
`offset`	required	数値	予測結果のテキスト内で一致した部分文字列の開始位置。

PlaceAutocompleteStructuredFormat

フィールド	必須	タイプ	説明
`main_text`	required	文字列	予測のメインテキスト（通常は場所の名前）が含まれます。
`main_text_matched_substrings`	required	Array<PlaceAutocompleteMatchedSubstring>	`offset` 値と `length` を含む配列が含まれます。これらは、入力された用語が予測結果のテキスト内のどこにあるかを記述します。これにより、用語が選択された場合にハイライト表示できます。詳しくは、PlaceAutocompleteMatchedSubstring をご覧ください。
`secondary_text`	省略可	文字列	予測のセカンダリテキスト（通常は場所の位置）が含まれます。
`secondary_text_matched_substrings`	省略可	Array<PlaceAutocompleteMatchedSubstring>	`offset` 値と `length` を含む配列が含まれます。これらは、入力された用語が予測結果のテキスト内のどこにあるかを記述します。これにより、用語が選択された場合にハイライト表示できます。詳しくは、PlaceAutocompleteMatchedSubstring をご覧ください。

PlaceAutocompleteTerm

フィールド	必須	タイプ	説明
`offset`	required	数値	説明内のこの用語の開始位置を定義します（Unicode 文字数で測定）。
`value`	required	文字列	用語のテキスト。

Place Autocomplete（従来版）の最適化

このセクションでは、Place Autocomplete（以前のバージョン）サービスを最大限に活用するためのヒントを紹介します。

概要は次のとおりです。

機能的なユーザーインターフェースを最も手早く作成するには、Maps JavaScript API Place Autocomplete（以前のバージョン）ウィジェット、Places SDK for Android Place Autocomplete（以前のバージョン）ウィジェット、または Places SDK for iOS Place Autocomplete（以前のバージョン）UI コントロールを使用します。
Place Autocomplete（従来版）のデータフィールドの基本を理解します。
位置情報のバイアスと位置情報の制限のフィールドは省略可能ですが、予測入力のパフォーマンスに大きく影響する場合があります。
エラー処理を使用して、API がエラーを返した場合に、アプリでグレースフルデグラデーションが行われるようにします。
アプリでは、選択肢がない場合でもユーザーが操作を続行できるようにします。

費用の最適化に関するヒント

基本的な費用の最適化

Place Autocomplete（従来版）サービスの使用コストを最適化するには、Place Details（従来版）と Place Autocomplete（従来版）ウィジェットのフィールドマスクを使用して、必要な Place Autocomplete（従来版）のデータフィールドのみを返すように設定します。

高度な費用の最適化

SKU: Autocomplete - Per Request の料金設定を利用し、Place Details（Legacy）の代わりに選択された場所に関する Geocoding API の結果をリクエストするためには、Place Autocomplete（Legacy）のプログラマティック実装を行うことをおすすめします。次の両方に該当する場合は、リクエストあたりの料金設定と Geocoding API を組み合わせた方が、セッションあたり（セッションベース）の料金設定よりも費用対効果が高くなります。

ユーザーが選択した場所の緯度/経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details（レガシー）の呼び出しよりも少ないコストでこの情報を提供できます。
ユーザーが予測結果を選択するまでの Place Autocomplete（レガシー）予測入力候補リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。

ニーズに合った Place Autocomplete（レガシー）実装を選ぶ際は、次の質問に対する答えを考え、それに対応するタブを選択するとヒントが表示されます。

アプリケーションで、選択された予測結果の住所と緯度 / 経度以外の情報が必要ですか？

はい。その他の情報も必要です

セッションベースの Place Autocomplete（従来版）と Place Details（従来版）を併用します。
アプリケーションで、場所の名前、ビジネスステータス、営業時間などの Place Details（以前のバージョン）が必要なため、Place Autocomplete（以前のバージョン）の実装では、セッショントークン（プログラムまたは JavaScript、Android、iOS ウィジェットに組み込まれている）をセッションごとに使用する必要があります。また、リクエストする場所のデータフィールドに応じて、該当する Places Data SKU も使用する必要があります。¹

ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete（Legacy）リクエストと Place Details（Legacy）リクエストの両方が含まれます。必要な Place Autocomplete（Legacy）データフィールドのみをリクエストするように、必ず fields パラメータを指定してください。

プログラマティック実装
Place Autocomplete（レガシー）リクエストでセッショントークンを使用します。選択された予測結果に関する Place Details（Legacy）をリクエストする際は、次のパラメータを含めます。

Place Autocomplete（従来版）レスポンスのプレイス ID
Place Autocomplete（従来版）リクエストで使用されるセッショントークン
必要な Place Autocomplete（従来版）のデータフィールドを指定する fields パラメータ

いいえ。住所と場所のみが必要です

Place Autocomplete（レガシー）の使用時のパフォーマンスによっては、アプリケーションで Place Details（レガシー）を使用するよりも、Geocoding API を使用した方が費用対効果が高くなる場合があります。アプリケーションの Place Autocomplete（レガシー）の効率は、ユーザーの入力内容や、アプリケーションが使用される場所、パフォーマンス最適化のベストプラクティスが導入されているかどうかによって変わります。

次の質問に答えるためには、ユーザーがアプリケーション内で Place Autocomplete（従来版）の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析する必要があります。

ユーザーが Place Autocomplete（従来版）の予測を選択するまでに実行されるリクエスト数は、平均で 4 回以下ですか？

はい

セッショントークンを使用せずにプログラムによって Place Autocomplete（従来版）を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、住所と緯度/経度の座標を提供します。Autocomplete - Per Request のリクエスト 4 件と、選択された場所の候補に関する Geocoding API の呼び出しを合わせた料金は、Place Autocomplete（以前の）のセッションあたりの料金よりも安くなります。¹

パフォーマンスに関するベストプラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。

いいえ

セッションベースの Place Autocomplete（従来版）と Place Details（従来版）を併用します。
ユーザーが Place Autocomplete（Legacy）の予測を選択するまでに行うリクエストの平均数が、セッション単位の料金設定の費用を超えるため、Place Autocomplete（Legacy）の実装では、Place Autocomplete（Legacy）リクエストと関連する Place Details（Legacy）リクエストの両方で、セッション単位のセッショントークンを使用する必要があります。¹

ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete（レガシー）リクエストと Place Details（レガシー）リクエストの両方が含まれます。必要なフィールドのみをリクエストするように、必ず fields パラメータを指定してください。

Place Autocomplete（従来版）レスポンスのプレイス ID
Place Autocomplete（従来版）リクエストで使用されるセッショントークン
住所やジオメトリなどの基本データフィールドを指定する fields パラメータ

Place Autocomplete（Legacy）リクエストを遅らせることを検討する
ユーザーが最初の 3 ～ 4 文字を入力するまで Place Autocomplete（Legacy）リクエストを遅らせて、アプリケーションでのリクエスト数を減らすこともできます。たとえば、ユーザーが 3 文字を入力した後に、入力された文字ごとに Place Autocomplete（Legacy）リクエストを行う場合、ユーザーが 7 文字を入力して、予測を選択し、それに対して Geocoding API リクエストを 1 回行うと、合計料金は Place Autocomplete（Legacy）Per Request 4 回分 + Geocoding になります。¹

リクエストを遅らせることで、プログラマティックリクエストの回数を平均 4 回以下に抑えられる場合は、高パフォーマンスで Place Autocomplete（レガシー）と Geocoding API を併用する実装に関するガイダンスをご覧ください。なお、リクエストを遅らせると、1 文字入力するたびに予測が表示されはずと考えているユーザーには、遅延と受けとられる場合もあります。

費用については、Google Maps Platform の料金リストをご覧ください。

パフォーマンスに関するベストプラクティス

Place Autocomplete（レガシー）のパフォーマンスを最適化するためのガイドラインは次のとおりです。

Place Autocomplete（従来版）実装に、国別のポリシー、場所のバイアス、言語設定（プログラマティック実装の場合）を追加します。ウィジェットはユーザーのブラウザやモバイルデバイスから言語設定を選択するため、ウィジェットでは言語設定は不要です。
Place Autocomplete（従来版）が地図に関連付けられている場合は、地図のビューポートを基準に場所にバイアスをかけることができます。
ユーザーが Place Autocomplete（従来版）の予測入力候補を選択しなかった場合は（通常は目的の住所が候補に挙がらなかったことが原因）、ユーザー入力内容を再利用して、より関連性の高い結果を取得できます。
- ユーザーが住所情報のみを入力することが予想される場合は、Geocoding API の呼び出しで、ユーザー入力を再利用します。
- ユーザーが特定の場所に関する検索語句（名前や住所）を入力することが予想される場合は、Place Details（Legacy）リクエストを使用します。特定の地域の結果のみが求められる場合は、場所のバイアスを使用します。
Geocoding API へのフォールバックが最適となるその他のシナリオは次のとおりです。
- 建物内の特定のユニットやアパートの住所など、サブプレミス住所を入力するユーザー。たとえば、チェコ語の住所「Stroupežnického 3191/17, Praha」では、Place Autocomplete（従来版）で部分的な予測が生成されます。
- ユーザーがニューヨークの「23-30 29th St, Queens」や、ハワイのカウアイ島の「47-380 Kamehameha Hwy, Kaneohe」など、道路区間のプレフィックスを入力する場合。

位置情報のバイアス

location パラメータと radius パラメータを渡すことで、バイアスを設定し、指定した範囲内の結果を優先します。これにより、定義されたエリア内の結果を優先的に表示するよう Place Autocomplete（従来版）に指示します。指定した範囲外の結果が返されることもあります。includedRegionCodes パラメータを使用すると、指定した国内の場所のみを表示するように結果をフィルタできます。

警告: radius が指定されていない場合、location パラメータは無視されます。

検索範囲が広い場合、通常、施設の結果は検索結果に表示されるほど上位にランク付けされません。施設を施設とジオコードの混合結果に表示する場合は、より小さい半径を指定します。または、types=establishment を使用して、結果を施設のみに制限します。

ロケーションの制限

locationRestriction パラメータを渡すことで、結果を指定したエリアに制限します。

strictbounds パラメータを追加することで、location パラメータと radius パラメータで定義された地域に結果を制限することもできます。これにより、Place Autocomplete（従来版）は、その地域内の結果のみを返すようになります。

Place Autocomplete（従来版） コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Place Autocomplete（従来版）リクエスト

必須パラメータ

入力

オプション パラメータ

#components

language

ロケーション

locationbias

locationrestriction

offset

origin

半径

地域

sessiontoken

strictbounds

タイプ

Place Autocomplete（従来版）の例

URL

curl

URL

curl

URL

curl

URL

curl

Place Autocomplete（従来版）のレスポンス

URL

curl

JSON

XML

PlacesAutocompleteResponse

predictions

status

error_message

info_messages

PlacesAutocompleteStatus

PlaceAutocompletePrediction

description

matched_substrings

structured_formatting

terms

distance_meters

place_id

reference

types

PlaceAutocompleteMatchedSubstring

length

offset

PlaceAutocompleteStructuredFormat

main_text

main_text_matched_substrings

secondary_text

secondary_text_matched_substrings

PlaceAutocompleteTerm

offset

value

Place Autocomplete（従来版）の最適化

費用の最適化に関するヒント

基本的な費用の最適化

高度な費用の最適化

はい。その他の情報も必要です

いいえ。住所と場所のみが必要です

はい

いいえ

パフォーマンスに関するベスト プラクティス

位置情報のバイアス

ロケーションの制限

Place Autocomplete（従来版）

オプションパラメータ

`predictions`

`status`

`error_message`

`info_messages`

`description`

`matched_substrings`

`structured_formatting`

`terms`

`distance_meters`

`place_id`

`reference`

`types`

`length`

`offset`

`main_text`

`main_text_matched_substrings`

`secondary_text`

`secondary_text_matched_substrings`

`offset`

`value`

パフォーマンスに関するベストプラクティス