Place Autocomplete

プラットフォームを選択: Android iOS JavaScript ウェブサービス

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

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

プレイス オートコンプリート サービスは Places API の一部であり、API キーと割り当て量を Places 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 リクエストを送信できます。

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

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

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

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

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

Required parameters

  • input

    The text string on which to search. The Place Autocomplete service will return candidate matches based on this string and order results based on their perceived relevance.

Optional parameters

  • components

    A grouping of places to which you would like to restrict your results. Currently, you can use components to filter by up to 5 countries. Countries must be passed as a two character, ISO 3166-1 Alpha-2 compatible country code. For example: components=country:fr would restrict your results to places within France. Multiple countries must be passed as multiple country:XX filters, with the pipe character | as a separator. For example: components=country:us|country:pr|country:vi|country:gu|country:mp would restrict your results to places within the United States and its unincorporated organized territories.

    Note: If you receive unexpected results with a country code, verify that you are using a code which includes the countries, dependent territories, and special areas of geographical interest you intend. You can find code information at Wikipedia: List of ISO 3166 country codes or the ISO Online Browsing Platform.

  • language

    The language in which to return results.

    • See the list of supported languages. Google often updates the supported languages, so this list may not be exhaustive.
    • If language is not supplied, the API attempts to use the preferred language as specified in the Accept-Language header.
    • The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
    • If a name is not available in the preferred language, the API uses the closest match.
    • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.

  • location

    The point around which to retrieve place information. This must be specified as latitude,longitude. The radius parameter must also be provided when specifying a location. If radius is not provided, the location parameter is ignored.

    When using the Text Search API, the `location` parameter may be overriden if the `query` contains an explicit location such as `Market in Barcelona`.

  • locationbias

    Prefer results in a specified area, by specifying either a radius plus lat/lng, or two lat/lng pairs representing the points of a rectangle. If this parameter is not specified, the API uses IP address biasing by default.

    • IP bias: Instructs the API to use IP address biasing. Pass the string ipbias (this option has no additional parameters).
    • Circular: A string specifying radius in meters, plus lat/lng in decimal degrees. Use the following format: circle:radius@lat,lng.
    • Rectangular: A string specifying two lat/lng pairs in decimal degrees, representing the south/west and north/east points of a rectangle. Use the following format:rectangle:south,west|north,east. Note that east/west values are wrapped to the range -180, 180, and north/south values are clamped to the range -90, 90.

  • locationrestriction

    Restrict results to a specified area, by specifying either a radius plus lat/lng, or two lat/lng pairs representing the points of a rectangle.

    • Circular: A string specifying radius in meters, plus lat/lng in decimal degrees. Use the following format: circle:radius@lat,lng.
    • Rectangular: A string specifying two lat/lng pairs in decimal degrees, representing the south/west and north/east points of a rectangle. Use the following format:rectangle:south,west|north,east. Note that east/west values are wrapped to the range -180, 180, and north/south values are clamped to the range -90, 90.

  • offset

    The position, in the input term, of the last character that the service uses to match predictions. For example, if the input is Google and the offset is 3, the service will match on Goo. The string determined by the offset is matched against the first word in the input term only. For example, if the input term is Google abc and the offset is 3, the service will attempt to match against Goo abc. If no offset is supplied, the service will use the whole term. The offset should generally be set to the position of the text caret.

  • origin

    The origin point from which to calculate straight-line distance to the destination (returned as distance_meters). If this value is omitted, straight-line distance will not be returned. Must be specified as latitude,longitude.

  • radius

    Defines the distance (in meters) within which to return place results. You may bias results to a specified circle by passing a location and a radius parameter. Doing so instructs the Places service to prefer showing results within that circle; results outside of the defined area may still be displayed.

    The radius will automatically be clamped to a maximum value depending on the type of search and other parameters.

    • Autocomplete: 50,000 meters
    • Nearby Search:
      • with keyword or name: 50,000 meters
      • without keyword or name
        • Up to 50,000 meters, adjusted dynamically based on area density, independent of rankby parameter.
        • When using rankby=distance, the radius parameter will not be accepted, and will result in an INVALID_REQUEST.
    • Query Autocomplete: 50,000 meters
    • Text Search: 50,000 meters

  • region

    The region code, specified as a ccTLD ("top-level domain") two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland").

  • sessiontoken

    A random string which identifies an autocomplete session for billing purposes.

    The session begins when the user starts typing a query, and concludes when they select a place and a call to Place Details is made. Each session can have multiple queries, followed by one place selection. The API key(s) used for each request within a session must belong to the same Google Cloud Console project. Once a session has concluded, the token is no longer valid; your app must generate a fresh token for each session. If the sessiontoken parameter is omitted, or if you reuse a session token, the session is charged as if no session token was provided (each request is billed separately).

    We recommend the following guidelines:

    • Use session tokens for all autocomplete sessions.
    • Generate a fresh token for each session. Using a version 4 UUID is recommended.
    • Ensure that the API key(s) used for all Place Autocomplete and Place Details requests within a session belong to the same Cloud Console project.
    • Be sure to pass a unique session token for each new session. Using the same token for more than one session will result in each request being billed individually.

  • strictbounds

    Returns only those places that are strictly within the region defined by location and radius. This is a restriction, rather than a bias, meaning that results outside this region will not be returned even if they match the user input.

  • types

    You can restrict results from a Place Autocomplete request to be of a certain type by passing the types parameter. This parameter specifies a type or a type collection, as listed in Place Types. If nothing is specified, all types are returned.

    A place can only have a single primary type from types listed in Table 1 or Table 2. For example, a hotel where food is served may by returned only with types=lodging and not with types=restaurant.

    For the value of the types parameter you can specify either:

    • Up to five values from Table 1 or Table 2. For multiple values, separate each value with a | (vertical bar). For example:

      types=book_store|cafe

    • Any single supported filter in Table 3. You cannot mix type collections.

    The request will be rejected with an INVALID_REQUEST error if:

    • More than five types are specified.
    • Any unrecognized types are present.
    • Any types from in Table 1 or Table 2 are mixed with any of the filters in Table 3.

Place Autocomplete の例

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

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=amoeba
  &location=37.76999%2C-122.44696
  &radius=500
  &types=establishment
  &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
  &location=37.76999%2C-122.44696
  &radius=500
  &strictbounds=true
  &types=establishment
  &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
  &language=fr
  &types=geocode
  &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
  &language=pt_BR
  &types=%28cities%29
  &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 キーの値は自分のものに置き換えてください。

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

プレイス オートコンプリート レスポンスは、リクエストの 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

<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

FieldRequiredTypeDescription
required Array<PlaceAutocompletePrediction>

Contains an array of predictions.

See PlaceAutocompletePrediction for more information.

requiredPlacesAutocompleteStatus

Contains the status of the request, and may contain debugging information to help you track down why the request failed.

See PlacesAutocompleteStatus for more information.

optionalstring

When the service returns a status code other than OK<, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

optionalArray<string>

When the service returns additional information about the request specification, there may be an additional info_messages field within the response object. This field is only returned for successful requests. It may not always be returned, and its content is subject to change.

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

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

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

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

PlacesAutocompleteStatus

Status codes returned by service.

  • OK indicating the API request was successful.
  • ZERO_RESULTS indicating that the search was successful but returned no results. This may occur if the search was passed a bounds in a remote location.
  • INVALID_REQUEST indicating the API request was malformed, generally due to the missing input parameter.
  • OVER_QUERY_LIMIT indicating any of the following:
    • You have exceeded the QPS limits.
    • Billing has not been enabled on your account.
    • The monthly $200 credit, or a self-imposed usage cap, has been exceeded.
    • The provided method of payment is no longer valid (for example, a credit card has expired).
    See the Maps FAQ for more information about how to resolve this error.
  • REQUEST_DENIED indicating that your request was denied, generally because:
    • The request is missing an API key.
    • The key parameter is invalid.
  • UNKNOWN_ERROR indicating an unknown error.

プレイス サービスが JSON 形式で検索結果を返す場合、検索結果は predictions 配列に格納されます。サービスから返す結果がない（location がリモートにある場合など）場合でも、空の predictions 配列が返されます。XML レスポンスは、ゼロ個以上の <prediction> 要素で構成されます。

PlaceAutocompletePrediction

FieldRequiredTypeDescription
requiredstring

Contains the human-readable name for the returned result. For establishment results, this is usually the business name. This content is meant to be read as-is. Do not programmatically parse the formatted address.

required Array<PlaceAutocompleteMatchedSubstring>

A list of substrings that describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired.

See PlaceAutocompleteMatchedSubstring for more information.

requiredPlaceAutocompleteStructuredFormat

Provides pre-formatted text that can be shown in your autocomplete results. This content is meant to be read as-is. Do not programmatically parse the formatted address.

See PlaceAutocompleteStructuredFormat for more information.

required Array<PlaceAutocompleteTerm>

Contains an array of terms identifying each section of the returned description (a section of the description is generally terminated with a comma). Each entry in the array has a value field, containing the text of the term, and an offset field, defining the start position of this term in the description, measured in Unicode characters.

See PlaceAutocompleteTerm for more information.

optionalinteger

The straight-line distance in meters from the origin. This field is only returned for requests made with an origin.

optionalstring

A textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in the placeId field of a Places API request. For more information about place IDs, see the Place IDs overview.

optionalstring

See place_id.

optionalArray<string>

Contains an array of types that apply to this place. For example: [ "political", "locality" ] or [ "establishment", "geocode", "beauty_salon" ]. The array can contain multiple values. Learn more about Place types.

PlaceAutocompleteMatchedSubstring

FieldRequiredTypeDescription
requirednumber

Length of the matched substring in the prediction result text.

requirednumber

Start location of the matched substring in the prediction result text.

PlaceAutocompleteStructuredFormat

FieldRequiredTypeDescription

main_text

requiredstring

Contains the main text of a prediction, usually the name of the place.

main_text_matched_substrings

required Array<PlaceAutocompleteMatchedSubstring>

Contains an array with offset value and length. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired.

See PlaceAutocompleteMatchedSubstring for more information.

secondary_text

optionalstring

Contains the secondary text of a prediction, usually the location of the place.

secondary_text_matched_substrings

optional Array<PlaceAutocompleteMatchedSubstring>

Contains an array with offset value and length. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired.

See PlaceAutocompleteMatchedSubstring for more information.

PlaceAutocompleteTerm

FieldRequiredTypeDescription
requirednumber

Defines the start position of this term in the description, measured in Unicode characters

requiredstring

The text of the term.

Place Autocomplete の最適化

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

概要は次のとおりです。

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

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

基本的な費用の最適化

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

高度な費用の最適化

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

  • ユーザーが選択した場所の緯度 / 経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details の呼び出しよりも少ないコストでこの情報を提供できます。
  • ユーザーが予測結果を選択するまでの予測入力候補リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。
ニーズに合った Place Autocomplete 実装を選ぶ際は、次の質問に対する答えを考え、それに対応するタブを選択するとヒントが表示されます。

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

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

セッション ベースの Place Autocomplete と Place Details を併用します。
アプリケーションで、場所の名前、お店やサービスのステータス、始業時間などの Place Details が必要になるため、Place Autocomplete 実装では、セッション トークン（プログラマティック実装か、JavaScript、Android、または iOS ウィジェットへの組み込み）を使用することをおすすめします。合計では、セッションあたり 0.017 ドルに加え、リクエストするデータ フィールドに応じた対象のプレイスデータ SKU の費用がかかります。1

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

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

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

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

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

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

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

はい

セッション トークンを使用せずにプログラムによって Place Autocomplete を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、リクエスト 1 件につき 0.005 ドルで住所と緯度 / 経度の座標が提供されます。Place Autocomplete - Per Request のリクエスト 4 件の料金は 0.01132 ドルになるため、4 件のリクエストと、選択された場所予測に関する Geocoding API の呼び出しを合わせた料金は、0.01632 ドルになります。これは、Per Session Autocomplete でのセッション 1 回あたりの料金 0.017 ドルよりも少ないコストです。1

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

いいえ

セッション ベースの Place Autocomplete と Place Details を併用します。
ユーザーが Place Autocomplete の予測を選択するまでの平均リクエスト回数が、セッションあたりの料金を超えるため、Place Autocomplete 実装では、Place Autocomplete リクエストと、関連する Place Details リクエストの両方でセッション トークンを使用することをおすすめします（合計費用はセッションあたり 0.017 ドル）。1

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

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

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

Place Autocomplete リクエストを遅らせることを検討する
ユーザーが最初の 3～4 文字を入力するまで Place Autocomplete リクエストを遅らせて、アプリケーションでのリクエスト数を減らすこともできます。たとえば、ユーザーが 3 文字目を入力してから、1 文字ごとに Place Autocomplete リクエストを行うとします。あるユーザーが、7 文字目を入力してから予測を選択し、Geocoding API リクエストが 1 回実行されました。この場合の合計費用は、0.01632 ドル（4 x Autocomplete Per Request 1 回の料金 0.00283 ドル + ジオコーディング 1 回の料金 0.005 ドル）となります。1

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

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

  1. ここで提示されている料金は米ドルです。料金について詳しくは、Google Maps Platform の課金のページをご覧ください。

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

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

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

場所のバイアス

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

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

地域の制限

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

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