Method: places.autocomplete

指定された入力に対する予測を返します。

HTTP リクエスト

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

この URL は gRPC Transcoding 構文を使用します。

リクエスト本文

リクエストの本文には、次の構造のデータが含まれます。

JSON 表現
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string
}
フィールド
input

string

必須。検索するテキスト文字列。

locationBias

object (LocationBias)

省略可。指定した場所にバイアスをかけます。

locationBias または locationRestriction のいずれか 1 つのみを設定してください。どちらも設定されていない場合、結果は IP アドレスによってバイアスされます。つまり、IP アドレスは不正確な場所にマッピングされ、バイアス シグナルとして使用されます。

locationRestriction

object (LocationRestriction)

省略可。結果を指定した場所に制限します。

locationBias または locationRestriction のいずれか 1 つのみを設定してください。どちらも設定されていない場合、結果は IP アドレスによってバイアスされます。つまり、IP アドレスは不正確な場所にマッピングされ、バイアス シグナルとして使用されます。

includedPrimaryTypes[]

string

省略可。https://developers.google.com/maps/documentation/places/web-service/place-types のメインの場所タイプ(「レストラン」、「ガソリン スタンド」など)を追加しました。プレイスは、メインのタイプがこのリストに含まれている場合にのみ返されます。最大 5 つの値を指定できます。タイプが指定されていない場合は、すべてのプレイスタイプが返されます。

includedRegionCodes[]

string

省略可。指定した地域の検索結果のみを含めます。最大 15 個の CLDR の 2 文字の地域コードで指定します。空のセットを指定すると、結果は制限されません。locationRestrictionincludedRegionCodes の両方を設定した場合、結果は交差点の領域に配置されます。

languageCode

string

省略可。結果を返す言語。デフォルトは en-US です。input で使用されている言語が languageCode と異なる場合、または返されたプレイスにローカル言語から languageCode への翻訳がない場合は、結果が混在することがあります。

regionCode

string

省略可。CLDR の 2 文字の地域コードとして指定される地域コード。これは、住所の形式や検索結果のランキングに影響します。また、返される結果に影響する場合もあります。指定したリージョンに結果が制限されることはありません。結果を特定のリージョンに限定するには、region_code_restriction を使用します。

origin

object (LatLng)

省略可。目的地までの測地線距離を計算する出発地点(distanceMeters として返されます)。この値を省略すると、測地線距離は返されません。

inputOffset

integer

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

空の場合、デフォルトで input の長さになります。

includeQueryPredictions

boolean

省略可。true の場合、レスポンスには場所の予測とクエリの予測の両方が含まれます。それ以外の場合、レスポンスは場所の予測のみを返します。

sessionToken

string

省略可。オートコンプリート セッションを課金目的で識別する文字列。長さが 36 文字以下の ASCII 文字の、URL とファイル名に安全な base64 文字列にする必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。

セッションは、ユーザーがクエリの入力を開始すると開始され、場所を選択して Place Details または Address Validation が呼び出されると終了します。各セッションでは複数のクエリの後に、Place Details または Address Validation リクエストを 1 回行うことができます。セッション内の各リクエストに使用される認証情報は、同じ Google Cloud コンソール プロジェクトに属している必要があります。セッションが終了するとトークンは無効になります。アプリでセッションごとに新しいトークンを生成する必要があります。sessionToken パラメータを省略した場合、またはセッション トークンを再利用する場合は、セッション トークンを指定しなかった場合と同様にセッションが課金されます(各リクエストは個別に課金されます)。

次のガイドラインに従うことをおすすめします。

  • すべての Place Autocomplete 呼び出しにセッション トークンを使用します。
  • セッションごとに新しいトークンを生成します。バージョン 4 の UUID を使用することをおすすめします。
  • セッション内のすべての Place Autocomplete、Place Details、Address Validation リクエストに使用される認証情報が、同じ Cloud コンソール プロジェクトに属していることを確認します。
  • 新しいセッションごとに固有のセッション トークンを渡すようにしてください。複数のセッションで同じトークンを使用すると、リクエストごとに課金されます。

レスポンスの本文

Places.Autocomplete のレスポンス プロトコル。

成功すると、レスポンスの本文に次の構造のデータが含まれます。

JSON 表現
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
フィールド
suggestions[]

object (Suggestion)

関連性の降順で並べ替えられた提案のリストが含まれます。

LocationBias

検索するリージョン。指定した地域でバイアスがかかっている場合があります。

JSON 表現
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
フィールド

共用体フィールド type

type は次のいずれかになります。

rectangle

object (Viewport)

北東と南西の角で定義されたビューポート。

circle

object (Circle)

中心点と半径で定義される円。

LocationRestriction

検索するリージョン。結果は指定したリージョンに制限されます。

JSON 表現
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
フィールド

共用体フィールド type

type は次のいずれかになります。

rectangle

object (Viewport)

北東と南西の角で定義されたビューポート。

circle

object (Circle)

中心点と半径で定義される円。

アドバイス

オートコンプリート候補の結果。

JSON 表現
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
フィールド

共用体フィールド kind

kind は次のいずれかになります。

placePrediction

object (PlacePrediction)

プレイスに対する予測。

queryPrediction

object (QueryPrediction)

クエリの予測。

PlacePrediction

Place Autocomplete 予測の予測結果。

JSON 表現
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
フィールド
place

string

候補の場所のリソース名。この名前は、プレイス名を受け付ける他の API で使用できます。

placeId

string

提案された場所の一意の識別子。この ID は、プレイス ID を受け付ける他の API で使用できます。

text

object (FormattableText)

返された結果の名前が人が読める形式で格納されます。施設の検索結果の場合、通常はビジネスの名前と住所です。

text は、単一の UI 要素を表示したいデベロッパーにおすすめです。2 つの独立した、しかし関連性のある UI 要素を表示したい場合は、代わりに structuredFormat を使用してください。これらは、場所の候補を表す 2 つの異なる方法です。structuredFormattext に解析したり、逆に解析したりしないでください。

このテキストは、Places.get から返される displayName とは異なる場合があります。

リクエスト inputlanguageCode が異なる言語の場合、またはプレイスにローカル言語から languageCode への翻訳がない場合は、複数の言語が混在している可能性があります。

structuredFormat

object (StructuredFormat)

場所の予測を、場所の名前を含むメインテキストと、曖昧さ回避するための追加の特徴(都市や地域など)を含むサブテキストに分割します。

structuredFormat は、別々の 2 つの UI 要素を関連させて表示したい場合におすすめします。単一の UI 要素を表示する場合は、代わりに text を使用することをおすすめします。これらは、場所の候補を表す 2 つの異なる方法です。structuredFormattext に解析したり、逆に解析したりしないでください。

types[]

string

このプレイスに適用されるタイプのリスト(https://developers.google.com/maps/documentation/places/web-service/place-types の表 A または表 B)。

タイプはプレイスの分類です。同じタイプの場所には、似たような特徴があります。

distanceMeters

integer

origin が指定されている場合、origin からの測地線の長さ(メートル単位)。経路などの特定の予測では、このフィールドにデータが入力されない場合があります。

FormattableText

場所またはクエリの予測を表すテキスト。テキストはそのまま使用することも、書式を適用することもできます。

JSON 表現
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
フィールド
text

string

そのままで使用できるテキスト、または matches でフォーマットされたテキスト。

matches[]

object (StringRange)

text で入力リクエストが一致した場所を識別する文字列範囲のリスト。範囲は、text の特定の部分を書式設定するために使用できます。文字列マッチング以外の条件(スペルの訂正や文字変換など)によって一致と判断された場合、部分文字列は input と完全一致しないことがあります。

これらの値は、text の Unicode 文字オフセットです。範囲はオフセット値の昇順で順序付けられます。

StringRange

指定されたテキスト内の部分文字列を識別します。

JSON 表現
{
  "startOffset": integer,
  "endOffset": integer
}
フィールド
startOffset

integer

文字列の最初の Unicode 文字のゼロベースのオフセット(この値を含む)。

endOffset

integer

最後の Unicode 文字のゼロベースのオフセット(その文字を含まない)。

StructuredFormat

場所またはクエリの予測のメインテキストとセカンダリ テキストの内訳が含まれます。

プレイス予測の場合、メインテキストにはプレイスの具体的な名前が含まれます。クエリ予測の場合、メインテキストにクエリが含まれます。

セカンダリ テキストには、プレイスをさらに識別したり、クエリを絞り込んだりするための、曖昧さを取り除く追加の特徴(都市や地域など)が含まれます。

JSON 表現
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
フィールド
mainText

object (FormattableText)

プレイスまたはクエリの名前を表します。

secondaryText

object (FormattableText)

プレイスをさらに特定したり、クエリを絞り込んだりできる、曖昧さ回避の追加の特徴(都市や地域など)を表します。

QueryPrediction

Query Autocomplete 予測の予測結果。

JSON 表現
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
フィールド
text

object (FormattableText)

予測されたテキスト。このテキストは場所を表すものではなく、検索エンドポイント(テキスト検索など)で使用できるテキストクエリです。

text は、単一の UI 要素を表示したいデベロッパーにおすすめです。2 つの独立した、しかし関連性のある UI 要素を表示したい場合は、代わりに structuredFormat を使用してください。クエリ予測を表す 2 つの異なる方法です。structuredFormattext に解析したり、逆に解析したりしないでください。

リクエスト inputlanguageCode が異なる言語の場合、またはクエリの一部にローカル言語から languageCode への翻訳がない場合は、複数の言語が混在している可能性があります。

structuredFormat

object (StructuredFormat)

クエリ予測を、クエリを含むメインテキストと、曖昧性除去用の特徴(都市や地域など)を含むセカンダリ テキストに分割します。

structuredFormat は、別々の 2 つの UI 要素を関連させて表示したい場合におすすめします。単一の UI 要素を表示する場合は、代わりに text を使用することをおすすめします。クエリ予測を表す 2 つの異なる方法です。structuredFormattext に解析したり、逆に解析したりしないでください。