# Place Autocomplete

The Place Autocomplete service is a web service that returns place predictions in response to an HTTP request. The request specifies a textual search string and optional geographic bounds. The service can be used to provide autocomplete functionality for text-based geographic searches, by returning places such as businesses, addresses and points of interest as a user types.

# Place Autocomplete requests

The Place Autocomplete service can match on full words and substrings, resolving place names, addresses. Applications can therefore send queries as the user types, to provide on-the-fly place predictions.

The returned predictions are designed to be presented to the user to aid them in selecting the desired place. You can send a Place Fields request for more information about any of the places which are returned.

A Place Autocomplete request is an HTTP URL of the following form:

https://apis.geodir.co/places/autocomplete/v1/**outputFormat**?**parameters**

where outputFormat may be either of the following values:

json (recommended) indicates output in JavaScript Object Notation (JSON); or
xml indicates output in XML

Security is important and HTTPS is recommended whenever possible, especially for applications that include sensitive user data, such as a user's location, in requests. Using HTTPS encryption makes your application more secure, and more resistant to snooping or tampering.

Note: URLs must be properly encoded (See best practices) to be valid and are limited to 8000 characters for all web services. Be aware of this limit when constructing your URLs. Note that different browsers, proxies, and servers may have different URL character limits as well.

Some parameters are required while some are optional. As is standard in URLs, parameters are separated using the ampersand (&) character.

Required parameters in an autocomplete request:

key: Your application's API key. This key identifies your application for purposes of quota management. Learn how to obtain your API key.
search: 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.

Examples of Place Autocomplete requests

A request for establishments containing the string "Rebagliati" within an area centered in Lima, PE:

https://apis.geodir.co/places/autocomplete/v1/json?text=Rebagliati&types=establishment&key=YOUR_KEY

# Place Autocomplete responses

Place Autocomplete responses are returned in the format indicated by the output flag within the request's URL path. The results below are indicative of what may be returned for a query with the following parameters:

search=jiron pedro ruiz gallo 658

{
    "status": "OK",
    "predictions": [
        {
            "types": [
                "route_number",
                " geocode"
            ],
            "description": "Jiron Pedro Ruiz Gallo 658, Breña, Lima, Perú",
            "main_text": "Jiron Pedro Ruiz Gallo 658",
            "secondary_text": "Breña, Lima, Perú",
            "place_id": "NGU2Mzg0YWYtMjkwMS01NGRjLTg1MWYtODQ1MGU2OWZhMzU4"
        },
        {
            "types": [
                "route_number",
                " geocode"
            ],
            "description": "Jirón Comandante Pedro Ruiz Gallo 658, Callao, Callao, ",
            "main_text": "Jirón Comandante Pedro Ruiz Gallo 658",
            "secondary_text": "Callao, Callao, ",
            "place_id": "NGU2Mzg0YWYtMjkwMS01NGRjLTg1MWYtODQ1MGU2OWZhMzU4"
        }
    ]
}

A JSON response contains up to two root elements:

status contains metadata on the request. See Status Codes below.
predictions contains an array of places, with information about the place. See Place Autocomplete Results for information about these results. The Places API returns up to 5 results.

Of particular interest within the results are the place_id elements, which can be used to request more specific details about the place via a separate query. See Place Fields requests.

See Processing JSON with JavaScript for help parsing JSON responses.

An XML response consists of a single PlaceAutocompleteResponse element with two types of child elements:

A single status element contains metadata on the request. See Status Codes (opens new window)below.
Zero or more prediction elements, each containing information about a single place. See Place Autocomplete Results for information about these results. The Places API returns up to 5 results.

We recommend that you use json as the preferred output flag unless your application requires xml for some reason. Processing XML trees requires some care, so that you reference proper nodes and elements. See Processing XML with XPath for help processing XML.

# Status Codes

The "status" field within the Place Autocomplete response object contains the status of the request, and may contain debugging information to help you track down why the Place Autocomplete request failed. The "status" field may contain the following values:

"OK" indicates that no errors occurred and at least one of result was returned.
"ZERO_RESULTS" indicates that the search was successful but returned no results. This may occur if the search was passed a bounds in a remote location.
"OVER_QUERY_LIMIT" indicates that you are over your quota.
"REQUEST_DENIED" indicates that your request was denied, generally because of lack of a valid key parameter.
"INVALID_REQUEST" generally indicates that the text parameter is missing.
"UNKNOWN_ERROR" indicates a server-side error; trying again may be successful.

# Error Messages

When the Places service returns a status code other than OK, there may be an additional message field within the response object. This field contains more detailed information about the reasons behind the given status code.

# Place Autocomplete Results

When the Places service returns JSON results from a search, it places them within a predictions array. Even if the service returns no results (such as if the location is remote) it still returns an empty predictions array. XML responses consist of zero or more prediction elements.

Each prediction result contains the following fields:

description contains the human-readable name for the returned result. For establishment results, this is usually the business name.
place_id is a textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in the place_id field of a Places API request. For more information about place IDs, see the Place ID overview.
types 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.
main_text contains the main text of a prediction, usually the name of the place.
secondary_text contains the secondary text of a prediction, usually the location of the place.

← Place Fields Fields list →