オートコンプリート(新)

プラットフォームを選択: Android iOS JavaScript ウェブサービス
欧州経済領域(EEA)のデベロッパー

はじめに

Autocomplete(新版)は、HTTP リクエストに応じて場所の候補とクエリ予測を返すウェブサービスです。リクエストでは、テキスト検索文字列に加え、検索対象地域を限定する地理的境界を指定します。

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

Autocomplete(新版)からのレスポンスには、次の 2 種類の予測が含まれます。

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

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

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

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

API Explorer を使用すると、ライブ リクエストを送信して、API と API オプションを理解できます。

Autocomplete(新版)リクエスト

Autocomplete(新版)リクエストは、次の形式の 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

サポートされるパラメータ

パラメータ

説明

input*

検索するテキスト文字列(完全な単語、部分文字列、場所の名前、住所、Plus Codes)。

FieldMask(HTTP ヘッダー)

レスポンスで返すフィールドを指定するカンマ区切りのリスト。

includedPrimaryTypes

指定した最大 5 つのプライマリ タイプのいずれかに一致する場所に結果を制限します。

includePureServiceAreaBusinesses

true の場合、実店舗を持たないビジネス(非店舗型ビジネス)が含まれます。デフォルトは false です。

includeQueryPredictions

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

includedRegionCodes

結果を制限する 2 文字の国コードの配列(最大 15 個)。

inputOffset

入力文字列内のカーソル位置の 0 ベースの Unicode 文字オフセット。予測に影響します。デフォルトは入力の長さです。

languageCode

結果の優先言語(IETF BCP-47 コード)。 デフォルトは Accept-Language ヘッダーまたは「en」です。

locationBias

検索結果にバイアスをかける領域(円または長方形)を指定します。領域外の結果も表示されます。locationRestriction と一緒に使用することはできません。

locationRestriction

検索結果を制限する領域(円または長方形)を指定します。このエリア外の結果は除外されます。 locationBias と併用することはできません。

origin

予測された目的地までの直線距離(distanceMeters)の計算に使用される出発地点(緯度、経度)。

regionCode

レスポンスの形式設定と候補のバイアスに使用される地域コード(例: 「uk」、「fr」)。

sessionToken

請求処理のために Autocomplete 呼び出しをセッションにグループ化する、ユーザー生成の文字列。

* は必須項目です。

回答について

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

  • suggestions 配列には、予測されたすべての場所とクエリが、関連性の高い順に格納されます。各場所は placePrediction フィールドで表され、各クエリは queryPrediction フィールドで表されます。
  • placePrediction フィールドには、プレイス ID やテキストによる説明など、1 つの場所の予測に関する詳細情報が含まれます。
    • input パラメータで指定されたユーザー入力により近い一致を返すため、場所の予測のテキスト説明には、場所、通り、その他の住所コンポーネントの別名が含まれる場合があります。これらの別名は、同じプレイス ID の Place Details の結果の displayName フィールドとアドレス フィールドで返される名前とは異なる場合があります。
    • この場合、一部の場所の別名は、languageCode パラメータに基づいて想定される言語とは異なる言語になることがあります。これは、ユーザー入力により近い名前がどれかによって異なります。
  • queryPrediction フィールドには、単一のクエリ予測に関する詳細情報が含まれます。

完全な 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 Codes を指定します。Autocomplete(新版)サービスは、この文字列と一致する候補を、関連性の高い順に並べて結果として返します。

オプション パラメータ

FieldMask

レスポンス フィールド マスクを作成して、レスポンスで返すフィールドのリストを指定します。HTTP ヘッダー X-Goog-FieldMask を使用して、レスポンス フィールド マスクをメソッドに渡します。

返す候補フィールドのカンマ区切りのリストを指定します。たとえば、候補の suggestions.placePrediction.text.text と suggestions.queryPrediction.text.text を取得します。

  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

すべてのフィールドを取得するには、* を使用します。

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

true の場合、将来的に営業を開始する予定のビジネスを返します。デフォルトは false です。

includedPrimaryTypes

場所には、表 A または表 B に記載されているタイプのうち、1 つのプライマリ タイプのみを設定できます。たとえば、プライマリ タイプは "mexican_restaurant" または "steak_house" です。

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

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

このパラメータには、代わりに (regions) または (cities) のいずれかを含めることもできます。(regions) タイプのコレクション フィルタ。近隣地域や郵便番号などのエリアまたは区分を対象とします。(cities) タイプ コレクションは、Google が都市として識別する場所をフィルタします。

次の場合、リクエストは INVALID_REQUEST エラーで拒否されます。

  • 指定したタイプの数が 5 個より多い。
  • (cities) または (regions) に加えて、任意の型が指定されています。
  • 認識できないタイプが指定されている。

includePureServiceAreaBusinesses

true に設定すると、顧客を直接訪問したり、顧客に直接配送したりするものの、実店舗を持たないビジネスがレスポンスに含まれます。false に設定すると、API は実店舗のあるビジネスのみを返します。

includeQueryPredictions

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

includedRegionCodes

指定された地域のリストの結果のみを含めます。最大 15 個の ccTLD(「トップレベル ドメイン」)の 2 文字の値の配列として指定します。省略すると、レスポンスに制限は適用されません。たとえば、リージョンをドイツとフランスに制限するには、次のようにします。

    "includedRegionCodes": ["de", "fr"]

locationRestriction と includedRegionCodes の両方を指定すると、2 つの設定の交差領域に結果が配置されます。

inputOffset

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

languageCode

結果を返す優先言語。input で使用されている言語が languageCode で指定された値と異なる場合、または返された場所に現地語から languageCode への翻訳がない場合、結果は複数の言語が混在する可能性があります。

  • 優先言語を指定するには、IETF BCP-47 言語コードを使用する必要があります。
  • languageCode が指定されていない場合、API は Accept-Language ヘッダーで指定された値を使用します。どちらも指定されていない場合、デフォルトは en です。無効な言語コードを指定すると、API は INVALID_ARGUMENT エラーを返します。
  • 優先言語は、API が返す結果のセットと、それらが返される順序にわずかに影響します。これは、API のスペルミスを修正する機能にも影響します。
  • 場所の予測は、各リクエストのユーザー入力に応じて異なる形式になります。
    • input パラメータで一致する用語が最初に選択されます。languageCode パラメータで指定された言語設定に一致する名前が使用されます(使用可能な場合)。それ以外の場合は、ユーザー入力に最も一致する名前が使用されます。
    • 場所の名前は、input パラメータの用語に一致するように、代替名を使用してフォーマットされる場合があります。これには、languageCode パラメータで指定された言語以外の言語の名前も含まれます。
    • 番地は、input パラメータの用語に一致する用語が選択された後にのみ、ユーザーが読み取れるスクリプトで、現地語でフォーマットされます。
    • 他のすべての住所は、input パラメータの用語に一致する用語が選択された後、優先言語で返されます。優先言語で名前が利用できない場合、API は最も近い一致を使用します。

locationBias または locationRestriction

locationBias または locationRestriction を指定して検索エリアを定義できますが、両方を指定することはできません。locationRestriction は、結果がその範囲内にある必要があるリージョンを指定し、locationBias は、結果がそのエリアの近くにある必要があるが、エリア外でもよいリージョンを指定すると考えてください。

  • locationBias

    検索する領域を指定します。この位置はバイアスとして機能します。つまり、指定された位置の周辺の結果(指定されたエリア外の結果を含む)が返される可能性があります。

  • locationRestriction

    検索する領域を指定します。指定したエリア外の結果は返されません。

locationBias または locationRestriction の地域を、長方形のビューポートまたは円として指定します。

  • 円は、中心点と半径(メートル単位)で定義されます。半径は 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
        }
      }
    }

origin

目的地までの直線距離を計算する際の起点(distanceMeters として返されます)。この値を省略すると、直線距離は返されません。緯度と経度の座標として指定する必要があります。

"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

regionCode

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

候補は、リージョン コードに基づいてバイアスされます。Google では、ユーザーの地域別の設定に応じて regionCode を設定することをおすすめしています。

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

regionCode を設定すると、その地域内の予測では、候補テキストから国名が省略されることがあります。つまり、structuredFormat.secondaryText が存在しない可能性があります。したがって、secondaryText が未定義または欠落しているケースをアプリケーションで処理できるようにしてください。

sessionToken

セッション トークンは、Autocomplete(新版)の呼び出しを「セッション」として追跡する、ユーザーが生成した文字列です。Autocomplete(新版)はセッション トークンを使用し、予測入力検索でのユーザーのクエリと選択フェーズを、請求処理のために個別のセッションにグループ化します。詳細については、セッション トークンをご覧ください。

結果をバイアスするパラメータを選択する

Autocomplete(新版)のパラメータは、検索結果に異なる影響を与える可能性があります。次の表に、目的の結果に基づくパラメータの使用に関する推奨事項を示します。
パラメータ 使用に関する推奨事項
regionCode ユーザーの地域別の設定に従って設定します。
includedRegionCodes 指定したリージョンのリストに結果を制限するように設定します。
locationBias 特定の地域内またはその周辺の結果を優先する場合に使用します。該当する場合は、ユーザーが表示している地図のビューポートとして地域を定義します。
locationRestriction リージョン外の結果を返すべきではない場合にのみ使用します。
origin 各予測への直線距離を意図する場合に使用します。

Autocomplete(新版)の例

locationRestriction を使用して検索を特定のエリアに制限する

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

curl -X POST -d '{
  "input": "Art museum",
  "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/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

locationRestriction を使用して、検索を長方形のビューポートに制限することもできます。次の例では、リクエストをサンフランシスコのダウンタウンに制限しています。

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

結果は suggestions 配列に含まれます。

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

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

locationBias を使用して、長方形のビューポートに検索をバイアスすることもできます。次の例では、リクエストをサンフランシスコのダウンタウンに制限しています。

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -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": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "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": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

includedPrimaryTypes を使用する

includedPrimaryTypes パラメータを使用して、表 A、表 B、(regions) のみ、または (cities) のみから最大 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 フィールドが含まれています。テキスト検索(新版)リクエストを送信すると、返されたクエリ予測の詳細情報を取得できます。

オリジンを使用

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

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

今後オープン予定のビジネスを検索する

次の例は、アイダホ州ニューメドウズで将来開業するビジネスの Autocomplete(新版)リクエストを示しています。

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

レスポンスには場所の詳細が含まれますが、開業日は含まれません。

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

レスポンスに距離が含まれていない

場合によっては、リクエストに origin が含まれていても、レスポンスの本文に distanceMeters が含まれていないことがあります。これは、次のような場合に発生することがあります。

  • distanceMeters は route 予測に含まれません。
  • の値が 0 の場合、distanceMeters は含まれません。これは、指定された origin の位置から 1 メートル未満の予測の場合です。

解析されたオブジェクトから distanceMeters フィールドを読み取ろうとするクライアント ライブラリは、値 0 を持つフィールドを返します。ユーザーに誤解を与えないように、距離がゼロの場合はユーザーに表示しないでください。

Autocomplete(新版)の最適化

このセクションでは、Autocomplete(新版)サービスを最大限に活用するためのヒントを紹介します。

概要は次のとおりです。

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

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

基本的な費用の最適化

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

高度な費用の最適化

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

  • ユーザーが選択した場所の緯度と経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details(新版)の呼び出しよりも少ないコストでこの情報を提供できます。
  • ユーザーが予測結果を選択するまでの予測入力候補(新版)リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。
アプリケーションの費用を最小限に抑える Autocomplete(新版)の実装を選択するには、次の表でアプリケーションのニーズに一致する行を見つけます。
アプリケーションに必要なもの ユーザーが予測を選択するまでの Autocomplete(新版)リクエストの平均数 おすすめの実装方法
住所と位置以外の Place Details(場所の名前、ビジネスのステータス、営業時間など) その他の数字 セッション ベースの Autocomplete(新版)と Place Details(新版)
選択された予測結果の住所と緯度 / 経度のみ 4 以下 リクエストごとの Autocomplete(新版)と Geocoding API
選択された予測結果の住所と緯度 / 経度のみ 4 回以上 住所のみのアプリケーション向けのセッション ベースの Autocomplete(新版)

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

表のリクエストの平均数を確認するには、ユーザーがアプリケーション内で Autocomplete(新版)の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析します。

セッション ベースの Autocomplete(新版)と Place Details(新版)

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

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

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

  1. Autocomplete(新版)レスポンスのプレイス ID
  2. Autocomplete(新版)リクエストで使用されるセッション トークン
  3. 必要な Autocomplete(新版)のデータ フィールドを指定する fields パラメータ

Geocoding API を使用したリクエストごとの Autocomplete(新版)

セッション トークンを使用せずにプログラムによって Autocomplete(新版)を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、住所と緯度 / 経度の座標を提供します。 Autocomplete Requests のリクエスト 4 件と、選択された場所予測に関する Geocoding API の呼び出しを合わせた料金は、Autocomplete(新規)のセッション 1 回あたりの料金よりも少ないコストです。1

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

住所のみのアプリケーション向けのセッション ベースの Autocomplete(新版)

セッション ベースの Autocomplete(新版)と Place Details(新版)を併用します。
ユーザーが Autocomplete(新版)の予測を選択するまでに予想されるリクエストの平均数が、セッションあたりの料金を上回るため、Autocomplete(新版)の実装では、Autocomplete(新版)リクエストと関連する Place Details(新版)リクエストの両方にセッション トークンを使用する必要があります。 セッションごと。 1

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

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

  1. Autocomplete(新版)レスポンスのプレイス ID
  2. Autocomplete(新版)リクエストで使用されるセッション トークン
  3. 住所やジオメトリなどのフィールドを指定する fields パラメータ

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

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

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


  1. 費用については、Google Maps Platform の料金表をご覧ください。

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

Autocomplete(新版)のパフォーマンスを最適化するためのガイドラインは次のとおりです。

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

位置情報のバイアス

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

ロケーションの制限

locationRestriction パラメータを渡して、結果を特定のエリアに制限します。

locationRestriction パラメータを追加することで、location パラメータと radius パラメータで定義された地域に結果を制限することもできます。これにより、Autocomplete(新版)は、そのリージョン内の結果のみを返すようになります。

試してみよう:

API Explorer を使用すると、サンプル リクエストを作成して、API と API オプションに慣れることができます。

  1. ページの右側にある API アイコン api を選択します。

  2. 必要に応じて、リクエスト パラメータを編集します。

  3. [Execute] ボタンを選択します。ダイアログで、リクエストに使用するアカウントを選択します。

  4. API Explorer パネルで、全画面表示アイコン fullscreen を選択して、API Explorer ウィンドウを拡大します。