Skip to content

Latest commit

 

History

History
226 lines (196 loc) · 7.21 KB

PlaceAutocomplete.md

File metadata and controls

226 lines (196 loc) · 7.21 KB

Place Autocomplete

Table of Contents

Summary

Place Autocomplete (/core/geography/place/autocomplete) is a wrapper service for Google's Place Autocomplete API, which returns place predictions based upon a user input string. It can be used in conjunction with [Google Place Details] to validate user input and retrieve geographic information. Please refer to Google's documentation for information about this service.

NOTE: Aside from autocompleting user input, Place Autocomplete is also the geo service to use for validating or normalizing non-street address location types, such as cities or zip codes.

Session Tokens and Usage Example

All requests require a UUID session token. Session tokens are used by Google to group multiple requests into one billing session.

As an example of the intended usage of sessions, suppose a consumer of the Place Autocomplete and Place Details apis has a user searching for a place:

  1. A session token UUID A is generated for the session.
  2. The user begins typing a place name.
  3. On e.g. the third keystroke "Har" a request is sent to /core/geography/place/autocomplete with input: Har and session_token: A.
  4. A list of predictions and their place_ids are generated for "Har" and returned in the response.
  5. The user does not select any of the predictions and instead inputs another keystroke "Harb".
  6. input: "Harb" and session_token: A is sent in a new request.
  7. A new list of predictions and their place_ids are generated and returned
  8. The user selects one of the predictions.
  9. The place_id for the selected prediction is sent to the Place Details service along with session_token: A.
  10. Place Details returns geographic details (locality name, lat/lng, etc.) for the selected place.
  11. A new session token is generated for any subsequent searches done by that user or any other users (i.e. DO NOT reuse session tokens).

Using session tokens in this way greatly minimizes billing costs incurred. Please see Google's session token documentation for more information.

Request Structure

Request structure for this service mirrors Google's request structure.

Request

Field Type Required Example Note
input string True "Harbi"
session_token string True - Must be UUID.
language string False "et" See supported languages
components array[string] False ["US", "CA", "CN"] No more than 5 countries. Must be ISO 3166-1 Alpha-2
types string False "(regions)" See place types

Examples

Only required fields w/ a city:

{
    "input": "Harbi",
    "session_token": "<UUID_TOKEN>"
}

Only required fields w/ a postal code:

{
    "input": "90210",
    "session_token": "<UUID_TOKEN>"
}

Only required fields w/ a country:

{
    "input": "China",
    "session_token": "<UUID_TOKEN>"
}

Only required fields w/ an address code:

{
    "input": "1600 Pennsylvania Avenue, washington dc",
    "session_token": "<UUID_TOKEN>"
}

All fields:

{
    "input": "Harbi",
    "session_token": "<UUID_TOKEN>",
    "language": "zh-cn",
    "components": ["CN", "US", "CA", "ET", "FR"],
    "types": "(regions)"
}

Response Structure

The response contains a list of up to 5 predictions.

Each prediction contains:

  • description string
  • place_id
  • List of terms and their offset
  • Location of the matched_substring in the prediction result
  • structured_formatting, pre-formatted text that can be used when displaying predictions
  • distance_meters from origin (if origin was specified in the request)

Please see Google's documentation for additional information on these fields.

Example

{
  "data": {
    "predictions": [
      {
        "description": "Harbin, 黑龙江省中国",
        "place_id": "ChIJYRRkpvhkQ14R1SygWnOSfF4",
        "types": [
          "locality",
          "political",
          "geocode"
        ],
        "terms": [
          {
            "offset": 0,
            "value": "Harbin"
          },
          {
            "offset": 8,
            "value": "黑龙江省"
          },
          {
            "offset": 12,
            "value": "中国"
          }
        ],
        "structured_formatting": {
          "main_text": "Harbin",
          "secondary_text": "黑龙江省中国",
          "main_text_matched_substrings": [
            {
              "length": 4,
              "offset": 0
            }
          ]
        },
        "matched_substring": [
          {
            "length": 4,
            "offset": 0
          }
        ],
        "distance_meters": 5233
      },
      {
        "description": "Nangang, 哈尔滨市黑龙江省中国",
        "place_id": "ChIJIcgm1bB5RF4RZA29COpGXqg",
        "types": [
          "sublocality_level_1",
          "sublocality",
          "political",
          "geocode"
        ],
        "terms": [
          {
            "offset": 0,
            "value": "Nangang"
          },
          {
            "offset": 9,
            "value": "哈尔滨市"
          },
          {
            "offset": 13,
            "value": "黑龙江省"
          },
          {
            "offset": 17,
            "value": "中国"
          }
        ],
        "structured_formatting": {
          "main_text": "Nangang",
          "secondary_text": "哈尔滨市黑龙江省中国",
          "main_text_matched_substrings": [
            {
              "length": 7,
              "offset": 0
            }
          ]
        },
        "matched_substring": [
          {
            "length": 7,
            "offset": 0
          }
        ],
        "distance_meters": 8416
      }
    ]
  }
}

In the above example, the place_id value in the response could then be sent to Place Details to retrieve relevant geo information about this locality. Please see the request and response sections of Place Details documentation, which continue the above example and show this locations place information.

Versioning

The current version of the service is 1.0.

Version must be specified in the Accept header. E.g. application/json;version=1.0.

Our general versioning strategy is available here.