Address autocomplete and place information

Using the Geoservices API for address autocomplete and gathering place information

Skedulo’s Geoservices API includes /autocomplete and /place endpoints that proxy to Google’s Autocomplete API and Place API to find address and place information.

Address autocompletion provides a list of addresses that match the description input to the closest five matches in the Google address database.

The /geoservices/autocomplete and /geoservices/place endpoints require a user-generated session token in the sessionId field.

Session tokens bundle queries made to the Autocomplete and Place APIs into a single session.

A session begins when a user begins typing a query to the Autocomplete API and ends when you select an address from the list of suggestions, which sends a fetch to the Place API.

Selecting a place based on the autocomplete suggestions concludes a session and the token is no longer valid. Sessions also end after a short period of time if no location is selected.

See the API reference documentation for schema information:

Generating a session token

Session tokens are a user-generated UUID that must be provided in the sessionId field in the JSON body submitted to the /geoservices/autocomplete and /geoservices/place endpoints.

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 an option is selected.

The same session token can be used again to call the Place API for the place information, but should 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)"
}

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

You can request a list of suggested addresses from the /geoservices/autocomplete endpoint using a POST request with a JSON body defining the input and session token.

  1. Generate a UUID to use as a session token.

  2. Create a POST method request to the /geoservices/autocomplete endpoint with a JSON body that includes the address input and session token.

    The following is an example of a JSON body with a partial address in the input field:

    {
        "input": "47 Warner Street",
        "sessionId": "0005c30e-2b8e-4a02-a6e6-f59a73275330",
        "country": "au"
    }

    The JSON response provides the best five matches for this address with the au country code:

    {
      "result": {
        "predictions": [
          {
            "description": "47 Warner Street, Fortitude Valley QLD, Australia",
            "placeId": "ChIJ56eaUPJZkWsRiGOVbF9RoVA"
          },
          {
            "description": "47 Warner Street, Wellington Point QLD, Australia",
            "placeId": "ChIJUQdzLy1nkWsR7p_JbXp6fVY"
          },
          {
            "description": "47 Warner Street, Rosenthal Heights QLD, Australia",
            "placeId": "ChIJm0UDdDGfl2sRRlSsFZuSY7g"
          },
          {
            "description": "47 Warner Street, Raceview QLD, Australia",
            "placeId": "Eik0NyBXYXJuZXIgU3RyZWV0LCBSYWNldmlldyBRTEQsIEF1c3RyYWxpYSIwEi4KFAoSCXkUhxewtZZrEXB5PMxaowITEC8qFAoSCS_m2CqwtZZrEe7XdWWxY0eQ"
          },
          {
            "description": "47 Little Warner Street, Rosenthal Heights QLD, Australia",
            "placeId": "ChIJJepfeTyfl2sRgzGX0Spk6Kg"
          }
        ],
        "status": "OK",
        "errorMessage": null
      }
    }
  3. Copy the placeId of the address you want to select from the suggested results.

  4. Send a PUT request to the /geoservices/place endpoint with the same sessionId you used to retrieve your autocomplete results and the placeId of the address you want to use.

    {
        "placeId": "ChIJ56eaUPJZkWsRiGOVbF9RoVA",
        "sessionId": "0005c30e-2b8e-4a02-a6e6-f59a73275330"
    }

The request returns the place details:

```json 
{
  "result": {
    "addressComponents": {
      "streetNumber": "47",
      "route": "Warner St",
      "locality": "Fortitude Valley",
      "area2": "Brisbane",
      "area1": "QLD",
      "country": "Australia",
      "postalCode": "4006"
    },
    "formattedAddress": "47 Warner St, Fortitude Valley QLD 4006, Australia",
    "geometry": {
      "lat": -27.4569042,
      "lng": 153.0349271
    }
  }
}
```

ZERO RESULTS

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

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