このページは Cloud Translation API によって翻訳されました。

オートコンプリート（新）

Autocomplete (new) サービスは、HTTP リクエストに応じて場所の予測とクエリの予測を返すウェブサービスです。リクエストでは、検索領域を制御するテキスト検索文字列と地理的境界を指定します。

Autocomplete（新）サービスでは、入力された完全な単語や部分文字列を照合して、場所の名前、住所、Plus Code を解決できます。そのため、アプリケーションはユーザーの入力に合わせてクエリを送信し、場所やクエリをその場で予測できます。

Autocomplete（新規）API からのレスポンスには、次の 2 種類の予測が含まれます。

場所の予測: 指定された入力テキスト文字列と検索領域に基づいた、お店やサービス、住所、スポットなどの場所。場所の予測はデフォルトで返されます。
クエリの予測: 入力テキスト文字列と検索領域に一致するクエリ文字列。デフォルトでは、クエリ予測は返されません。includeQueryPredictions リクエストパラメータを使用して、クエリ予測をレスポンスに追加します。

たとえば、部分的なユーザー入力「Sicilian piz」を含む文字列を入力として使用して API を呼び出します。検索領域はカリフォルニア州サンフランシスコに限定されます。レスポンスには、検索文字列と検索領域に一致する場所の予測リスト（「Sicilian Pizza Kitchen」という名前のレストランなど）のリストと、その場所の詳細が含まれます。

返される場所の予測は、ユーザーが目的の場所を選択できるように、ユーザーに提示するように設計されています。Place Details (New) リクエストを使用すると、返された場所の予測に関する詳細情報を取得できます。

レスポンスには、「Sicilian Pizza & Pasta」など、検索文字列と検索領域に一致するクエリ予測のリストを含めることもできます。レスポンスの各クエリ予測には、推奨されるテキスト検索文字列を含む text フィールドが含まれます。その文字列を Text Search (New) への入力として使用して、より詳細な検索を行います。

オートコンプリート（新規）リクエスト

オートコンプリート（新規）リクエストは、次の形式の URL に対する HTTP POST リクエストです。

https://places.googleapis.com/v1/places:autocomplete

すべてのパラメータを JSON リクエスト本文またはヘッダーで POST リクエストの一部として渡します。次に例を示します。

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

オートコンプリート（新機能）を使用してリクエストする

Places API は、既存の Autocomplete API と Query Autocomplete API をサポートしています。これらの API を使い慣れている方を対象に、オートコンプリート（新）のプレビュー版に次の変更が加えられています。

新しいオートコンプリートは HTTP POST リクエストを使用します。HTTP POST リクエストの一部として、リクエスト本文またはヘッダーでパラメータを渡します。これに対して、既存の API では、HTTP GET リクエストを使用して URL パラメータを渡します。
新しいオートコンプリートは、認証メカニズムとして API キーと OAuth トークンの両方をサポートしています。
新しいオートコンプリートでは、レスポンス形式として JSON のみがサポートされています。

次の表は、既存の Autocomplete API と Query Autocomplete API のパラメータのうち、新しい Autocomplete に合わせて名前が変更されたり、変更されたパラメータと、サポートされなくなったパラメータを示しています。

現在のパラメータ	新しいパラメータ	メモ
`components`	`includedRegionCodes`
`language`	`languageCode`
`location`	`locationBias`
`ipbias`		`locationBias` と `locationRestriction` の両方を省略した場合、API はデフォルトで IP バイアスを使用します。
`offset`	`inputOffset`
`radius`	`locationBias` または `locationRestriction`
`region`	`regionCode`
`stricbounds`	`locationRestriction`
`sessiontoken`	`sessionToken`
`types`	`includedPrimaryTypes`

使用量上限

プレビューリリースでは、プロジェクトごとに 1 分あたり最大 600 件のクエリに制限されます。

プレビューリリースのサポートオプション

Google は本サービスのプレビュー版、機能、機能に関してサポートを提供する義務を負いませんが、これらの開発段階でのリクエストは状況に応じて個別に検討します。

プレリリース版は Google Maps Platform SLA の対象外です。
特に本番環境でプレリリース版を使用している場合は、フォールバックメカニズムを使用することをおすすめします。フォールバックの状況の例としては、割り当て超過、予期しないレスポンスコードとレイテンシ、既存のオートコンプリートと比較した場合の予期しないレスポンスなどがあります。

Issue Tracker を使用して、新機能のリクエストや既存の機能の変更の提案を行うことができます。追加を希望する機能と、その機能を重視する理由を記載してください。可能であれば、具体的なユースケースと、この機能によって実現できる新たな可能性についても記載してください。

機能に関するその他のご質問については、newplacesapi@google.com までメールをお送りください。

回答について

Autocomplete (New) は、レスポンスとして JSON オブジェクトを返します。レスポンスの説明:

suggestions 配列には、予測される場所とクエリがすべて、関連性の高い順に並べて含まれます。各場所は placePrediction フィールドで表され、各クエリは queryPrediction フィールドで表されます。
placePrediction フィールドには、プレイス ID やテキストによる説明など、1 つの場所の予測に関する詳細情報が含まれます。
queryPrediction フィールドには、単一のクエリ予測に関する詳細情報が含まれます。

注: Autocomplete (new) は、リクエストに応じて、合計 5 つの予測（placePredictions、queryPredictions、またはその両方の組み合わせ）を返します。たとえば、リクエストで includeQueryPredictions が設定されていない場合、レスポンスの本文には最大 5 つの placePredictions が含まれます。リクエストで includeQueryPredictions が設定されている場合、レスポンスの本文には placePredictions と queryPredictions の組み合わせで最大 5 つの予測が含まれます。

完全な JSON オブジェクトの形式は次のとおりです。

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

必須パラメータ

入力

検索するテキスト文字列。完全な単語や部分文字列、場所の名前、住所、Plus Code を指定します。Autocomplete (new) サービスは、この文字列と一致する候補を、関連性の高い順に並べて結果を並べ替えます。

省略可能なパラメータ

includedPrimaryTypes

1 つの場所に設定できるメインタイプは Table A または Table B の1 つのみです。たとえば、メインのタイプは "mexican_restaurant" や "steak_house" です。

デフォルトでは、API は、場所に関連付けられているメインのタイプの値に関係なく、input パラメータに基づいてすべての場所を返します。includedPrimaryTypes パラメータを渡すことで、結果を特定のプライマリ型またはプライマリ型に制限します。

このパラメータを使用して、Table A または Table B から最大 5 つの型値を指定します。場所は、指定されたプライマリタイプ値のいずれかに一致すると、レスポンスに含まれます。

次の場合、リクエストは INVALID_REQUEST エラーで拒否されます。
- 5 個を超えるタイプが指定されています。
- 認識できないタイプが指定されています。
includeQueryPredictions

true の場合、レスポンスには場所の予測とクエリの予測の両方が含まれます。デフォルト値は false です。つまり、レスポンスには場所の予測のみが含まれます。
includedRegionCodes

指定した地域のリストに含まれる結果のみを含めます。リストには、最大 15 個の ccTLD（「トップレベルドメイン」）の 2 文字の値からなる配列を指定します。省略した場合、レスポンスに制限は適用されません。たとえば、リージョンをドイツとフランスに制限するには、次のようにします。
```
    "includedRegionCodes": ["de", "fr"]
```
locationRestriction と includedRegionCodes の両方を指定した場合、結果は 2 つの設定の交差領域に配置されます。
inputOffset

input でのカーソル位置を示す、ゼロベースの Unicode 文字オフセット。カーソルの位置は、返される予測に影響を与える可能性があります。空の場合、デフォルトで input の長さになります。

注: 最初の限定公開プレビューリリースでは、このプロパティは predictionTermOffset と呼ばれていました。
languageCode

結果を返す際の優先言語。input で使用されている言語が languageCode で指定された値と異なる場合、または返された場所のローカル言語から languageCode への翻訳がない場合、結果は言語が混在することがあります。
- 優先言語を指定するには、IETF BCP-47 言語コードを使用する必要があります。
- languageCode が指定されていない場合、API は Accept-Language ヘッダーで指定された値を使用します。どちらも指定されていない場合、デフォルトは en です。無効な言語コードを指定すると、API から INVALID_ARGUMENT エラーが返されます。
- 優先言語は、API が返す結果のセットや、返される順序にわずかな影響を及ぼします。これは、API のスペルミスを修正する機能にも影響します。
- この API は、ユーザーと地域住民の両方が判読できる住所を提供すると同時に、ユーザー入力を反映しようとします。プレイス予測の形式は、各リクエストでのユーザー入力によって異なります。
  - input パラメータで一致する用語が最初に選択され、利用可能な場合は languageCode パラメータで示される言語設定に沿った名前が使用されます。それ以外の場合は、ユーザー入力に最も一致する名前が使用されます。
  - 番地はローカル言語でフォーマットされ、可能であればユーザーが読み取れるスクリプトを使用します。ただし、input パラメータで指定された語句と一致する語句が選ばれた場合に限ります。
  - その他の住所はすべて、input パラメータの語句と一致する語句が選択された後、優先言語で返されます。優先言語で名前を利用できない場合、API は最も近い言語を使用します。
locationBias または locationRestriction

locationBias または locationRestriction のいずれかを指定して、検索領域を定義できます。locationRestriction は結果が存在するリージョンを指定するもので、locationBias は結果が存在する必要があるリージョンを指定するもので、エリアの外にあってもよいと考えてください。

注: locationBias と locationRestriction の両方を省略した場合、API はデフォルトで IP バイアスを使用します。IP バイアスを設定すると、API はデバイスの IP アドレスを使用して結果をバイアスします。
- locationBias
  
  検索する領域を指定します。この場所はバイアスとして機能します。つまり、指定された場所の周辺にある結果（指定された領域外の結果を含む）を返すことができます。
- locationRestriction
  
  検索する領域を指定します。指定された領域外の結果は返されません。
locationBias または locationRestriction の領域は、長方形のビューポートまたは円として指定します。
- 円は、中心点と半径（メートル単位）で定義されます。radius は 0.0 ～ 50000.0 の範囲で指定する必要があります。デフォルト値は 0.0 です。locationRestriction では、半径を 0.0 より大きい値に設定する必要があります。それ以外の場合、リクエストは結果を返しません。
  
  次に例を示します。
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- 長方形は緯度と経度のビューポートで、対角線上に 2 つの low と高い点として表されます。ビューポートは閉じた領域と見なされます。つまり、その境界も含まれます。緯度の境界は -90 ～ 90 度、経度の境界は -180 ～ 180 度の範囲内にする必要があります。
  - low = high の場合、ビューポートはその単一ポイントで構成されます。
  - low.longitude > high.longitude の場合、経度の範囲が反転します（ビューポートが 180 度の経度線と交差します）。
  - low.longitude = -180 度、high.longitude = 180 度の場合、ビューポートにはすべての経度が含まれます。
  - low.longitude = 180 度、high.longitude = -180 度の場合、経度の範囲は空になります。
  low と high の両方を入力する必要があります。表示されるボックスを空にすることはできません。空のビューポートはエラーになります。
  
  たとえば、次のビューポートはニューヨーク市を完全に囲んでいます。
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
出所

目的地までの直線距離を計算する出発地点（distanceMeters として返されます）。この値を省略すると、直線距離は返されません。緯度と経度の座標で指定する必要があります。
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

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

無効なリージョンコードを指定すると、API から INVALID_ARGUMENT エラーが返されます。パラメータは、適用される法律に基づいて結果に影響を与える可能性があります。
sessionToken

セッショントークンは、オートコンプリート（新機能）の呼び出しを「セッション」としてトラッキングする、ユーザー生成の文字列です。オートコンプリート（新機能）は、セッショントークンを使用して、ユーザーのオートコンプリート検索のクエリと選択のフェーズを個別のセッションにグループ化し、請求を行います。詳細については、セッショントークンをご覧ください。

オートコンプリート（新機能）の例

locationRestriction と locationBias を使用する

API はデフォルトで IP バイアスを使用して検索領域を制御します。IP バイアスでは、API はデバイスの IP アドレスを使用して結果をバイアスします。必要に応じて locationRestriction または locationBias を使用できますが、両方を使用することはできません。

locationRestriction は検索する領域を指定します。指定された領域外の結果は返されません。次の例では、locationRestriction を使用して、サンフランシスコを中心とする半径 5, 000 m の円にリクエストを制限します。

curl -X POST -d '{
  "input": "Amoeba",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

指定した領域からのすべての結果が suggestions 配列に含まれます。

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

locationBias では、地域はバイアスとして機能します。つまり、指定された地域周辺の結果（指定された領域外の結果を含む）を返すことができます。次の例では、locationBias を使用するようにリクエストを変更します。

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

結果には、半径 5, 000 メートルの外にある結果など、さらに多くのアイテムが含まれるようになりました。

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

includePrimaryTypes の使用

includedPrimaryTypes パラメータを使用して、リクエストの結果を表 A と表 B にある特定のタイプに制限します。最大 5 つの値の配列を指定できます。省略すると、すべての型が返されます。

次の例では、input 文字列を「Soccer」と指定し、includedPrimaryTypes パラメータを使用して、結果を "sporting_goods_store" タイプの施設に限定しています。

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

includedPrimaryTypes パラメータを省略すると、不要なタイプの施設（"athletic_field" など）が結果に含まれる可能性があります。

クエリ予測をリクエストする

デフォルトでは、クエリ予測は返されません。includeQueryPredictions リクエストパラメータを使用して、レスポンスにクエリ予測を追加します。次に例を示します。

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

これで、上記のレスポンスについてで説明されているように、suggestions 配列に場所の予測とクエリの予測の両方が含まれるようになりました。各クエリ予測には、推奨されるテキスト検索文字列を含む text フィールドが含まれます。Text Search (New) リクエストを使用すると、返されたクエリ予測に関する詳細情報を取得できます。

注: includedRegionCodes パラメータが設定されている場合、クエリ予測は返されません。

オリジンを使用

この例では、リクエストに origin を緯度と経度の座標として含めます。origin を含めると、API は、origin から目的地までの直線距離を含む distanceMeters フィールドをレスポンスに含めます。次の例では、起点をサンフランシスコの中心に設定しています。

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

レスポンスに distanceMeters が追加されました。

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

オートコンプリート（新）

オートコンプリート（新規）リクエスト

オートコンプリート（新機能）を使用してリクエストする

使用量上限

プレビュー リリースのサポート オプション

回答について

必須パラメータ

入力

省略可能なパラメータ

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias または locationRestriction

locationBias

locationRestriction

出所

regionCode

sessionToken