Autocomplete API and Place API

Getting a predicted list of addresses: Autocomplete API

The /autocomplete endpoint provides a list of five closely matching addresses provided in the Google address database for a given input string. You can use this API to match on full words and substrings for a place’s names or addresses.

Mandatory parameters

  • input: The input refers to a string or letters of an address that is to be autocompleted.

  • sessionId: The sessionId is the user generated UUID of a session (also called session token). It consists of multiple autocomplete requests and ends with a place fetch request. In other words, the session tokens bundle queries made to the Autocomplete APIs and Place APIs into a single session.

Generating a Session Id

You can generate a UUID using a free tool such as Online UUID Generator.

All autocomplete searches require a session token, with the same token used for all subsequent autocomplete requests until a place is selected from the autocompleted list. The same session token can be used again to call the Place API for the place information, but can not be used again after that.

Failing to provide a valid session token results in the following error:

{
  "errorType": "input_parse_error",
  "message": "Failed to parse input. Error message: Attempt to decode value on failed cursor: DownField(sessionId)"
}

Optional parameters

  • location: The location refers to any place on earth that is in the form of latitude and longitude coordinates.

  • country: The country refers to the two character, ISO 3166-1 Alpha-2 compatible country code. This parameter helps in identifying the place by country. Find the codes of different countries in this list.

For example, let’s say you want to get the autocompleted list of places for the partial string “Central Pa”. In this case, you can send a POST request by calling the /autocomplete endpoint with the following payload:

{
  "input": "Central Pa",
  "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459"
}

This request returns the following autocompleted places:

{
    "result": {
        "predictions": [
            {
                "description": "Central Park South, New York, NY, USA",
                "placeId": "EiVDZW50cmFsIFBhcmsgU291dGgsIE5ldyBZb3JrLCBOWSwgVVNBIi4qLAoUChIJu3GRLvdYwokRYtzyuYIf3zoSFAoSCTsIP9OlT8KJEWL-d-EGjwvI"
            },
            {
                "description": "Central Park West, New York, NY, USA",
                "placeId": "EiRDZW50cmFsIFBhcmsgV2VzdCwgTmV3IFlvcmssIE5ZLCBVU0EiLiosChQKEgkVVHPBmljCiRFwbhPvmnVSRhIUChIJOwg_06VPwokRYv534QaPC8g"
            },
            {
                "description": "Central Park North, New York, NY, USA",
                "placeId": "EiVDZW50cmFsIFBhcmsgTm9ydGgsIE5ldyBZb3JrLCBOWSwgVVNBIi4qLAoUChIJ6XWMiRn2wokROZOJYqrTD4kSFAoSCTsIP9OlT8KJEWL-d-EGjwvI"
            },
            {
                "description": "Central Park Blvd, Denver, CO, USA",
                "placeId": "EiJDZW50cmFsIFBhcmsgQmx2ZCwgRGVudmVyLCBDTywgVVNBIi4qLAoUChIJW79GQXl7bIcRoIQol_5XC38SFAoSCc8XHyOqgGuHEdY2iif49I4R"
            },
            {
                "description": "Central Park Avenue, Yonkers, NY, USA",
                "placeId": "EiVDZW50cmFsIFBhcmsgQXZlbnVlLCBZb25rZXJzLCBOWSwgVVNBIi4qLAoUChIJrb0BuyeTwokRCRUteZIwiGQSFAoSCaGvQwkIwMKJEaLa2KSEc5a-"
            }
        ],
        "status": "OK",
        "errorMessage": null
    }
}

From the result, you can see the five closely matching autocompleted addresses to the input string “Central Pa”.

For the schema information of this endpoint, please refer to /autocomplete.

Finding details of a place: Place API

The /place endpoint provides the detailed information available in Google Places database and Google Maps for a given place. The Place IDs uniquely identify a place and are available for most locations, including businesses, landmarks, parks, roads and intersections. Please note that the same place or location can have different place IDs and they may also change over time.

Mandatory parameters

  • placeID: The placeID refers to a string of letters that is a unique id for a place in the Google system, obtained from the Autocomplete API.

  • sessionId: The sessionId is the user generated UUID of a session also called session token. It consists of multiple autocomplete requests and ends with a place fetch request. In other words the session tokens bundle queries made to the Autocomplete APIs and Place APIs into a single session.

Refer to the Generating a Session Id section for more information about sessionID.

For the schema information of this endpoint, please refer to /place.

Using the Autocomplete and Place APIs to get a list of suggested addresses

Follow the steps given below to combine Skedulo’s Autocomplete and Place APIs to get the place details

  1. Generate a UUID using a free tool such as Online UUID Generator.
  2. Use the /autocomplete to send a POST request with a JSON body defining the input and session token generated by the tool. For example: 
    {
  "input": "Central Pa",
  "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459"
}
  3. Copy the placeId of the address you want to select from the list of the five suggested results. If the place you are looking for is not in the list, please retry using the /autocomplete endpoint with more precise keywords in the input string.
  4. Use the placeId of your interest and send a POST request to the /place endpoint with the same sessionId you used to retrieve your autocomplete results like shown below: 
    {
  "placeId": "EiVDZW50cmFsIFBhcmsgU291dGgsIE5ldyBZb3JrLCBOWSwgVVNBIi4qLAoUChIJu3GRLvdYwokRYtzyuYIf3zoSFAoSCTsIP9OlT8KJEWL-d-EGjwvI",
  "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459"
}

This request returns the following place information:

{
    "result": {
        "addressComponents": {
            "streetNumber": null,
            "route": "Central Park S",
            "subLocality": "Manhattan",
            "locality": "New York",
            "area2": "New York County",
            "area1": "NY",
            "country": "United States",
            "postalCode": null
        },
        "formattedAddress": "Central Park S, New York, NY, USA",
        "geometry": {
            "lat": 40.7661851,
            "lng": -73.9773038
        }
    }
}

ZERO RESULTS

If no addresses match the description you have provided in the request input field in your /autocomplete request, the response will show ZERO RESULTS:

{
  "result": {
    "predictions": [],
    "status": "ZERO_RESULTS",
    "errorMessage": null
  }
}