Geocoding using Amazon Location - Amazon Location Service
Start geocodingGeocode near a positionGeocode within a bounding boxGeocode within a countryFiltering by categoryGeocode in a preferred languageExample response

Geocoding using Amazon Location

Geocoding is a process that converts text, such as an address, a region, a business name, or point of interest, into a set of geographic coordinates. You can use place index resources to submit geocoding requests and incorporate data retrieved from geocoding to display data on a map for your web or mobile application.

This section guides you through how to send a simple geocoding request, and how to send geocoding requests with optional specifications.

Geocoding

You can submit a simple request to geocode using the SearchPlaceIndexForText operation to convert an address to a set of coordinates. A simple request contains the following required parameter:

  • Text – An address, name, city, or region to convert to a set of coordinates. For example, the string Any Town.

To specify a maximum number of results per pages, use the following optional parameter:

  • MaxResults – Limits the maximum number of results returned in the query response.

You can use the AWS CLI or the Amazon Location APIs.

API

The following example is a SearchPlaceIndexForText request to search the place index resource, ExamplePlaceIndex, for an address, name, city or region called Any Town.

POST /places/v0/indexes/ExamplePlaceIndex/search/text 
Content-type: application/json

{
    "Text": "Any Town",
    "MaxResults": 10
}
AWS CLI

The following example is a search-place-index-for-text command to search the place index resource, ExamplePlaceIndex, for an address, name, city or region called Any Town.

aws location \
    search-place-index-for-text \
        --index-name ExamplePlaceIndex \
        --text "Any Town" \
        --max-results 10

Geocode near a position

When geocoding, you can geocode near a given position with the following optional parameter:

  • BiasPosition – The position you want to search nearby. This narrows your search by searching for results closest to the given position. Defined as [longitude, latitude]

The following example is a SearchPlaceIndexForText request to search the place index resource for an address, name, city or region called Any Town near the position [-123.4567,45.6789].

POST /places/v0/indexes/ExamplePlaceIndex/search/text 
Content-type: application/json

{
   "Text": "Any Town",
   "BiasPosition": [-123.4567,45.6789]
}

Geocode within a bounding box

You can geocode within a bounding box to narrow your results to coordinates within a given boundary using the following optional parameter:

  • FilterBBox – A bounding box that you specify to filter your results to coordinates within the box's boundaries. Defined as [LongitudeSW, LatitudeSW, LongitudeNE, LatitudeNE]

    Note

    A request can't contain both the FilterBBox and BiasPosition parameters. Specifying both parameters in the request returns a ValidationException error.

The following example is a SearchPlaceIndexForText request to search within a bounding box for an address, name, city or region called Any Town. The bounding box follows that:

  • The longitude of the southwest corner is -124.1450.

  • The latitude of the southwest corner is 41.7045.

  • The longitude of the northeast corner is -124.1387.

  • The latitude of the northeast corner is 41.7096.

POST /places/v0/indexes/ExamplePlaceIndex/search/text 
Content-type: application/json

{
   "Text": "Any Town",
   "FilterBBox":  [
        -124.1450,41.7045,
        -124.1387,41.7096
    ]
}

Geocode within a country

You can geocode within one or more countries you specify by using the following optional parameter:

  • FilterCountries – The country or region you want to geocode within. You can define up to 100 countries in one request using a ISO 3166 three letter country code. For example, use AUS for Australia.

The following example is a SearchPlaceIndexForText request to search for an address, name, city or region called Any Town in Germany and France. 

POST /places/v0/indexes/ExamplePlaceIndex/search/text 
Content-type: application/json

{
   "Text": "Any Town",
   "FilterCountries": ["DEU","FRA"]
}

Filtering by category

You can filter the categories that are returned in your geocode request by using the following optional parameter:

  • FilterCategories – The categories of results you want returned in your query. You can specify up to 5 categories in one request. You can find the list of Amazon Location Service categories in the Categories section. For example, you can specify Hotel to specify only returning hotels in your query.

The following example is a SearchPlaceIndexForText request to search for an coffee shop called Hometown Coffee in the United States.

POST /places/v0/indexes/ExamplePlaceIndex/search/text 
Content-type: application/json

{
   "Text": "Hometown Coffee",
   "FilterCategories": ["Coffee Shop"],
   "FilterCountries": ["USA"]
}

For more details about filtering on categories, see Place categories and filtering results with Amazon Location

Geocode in a preferred language

You can set a language preference for results of your search by using the optional Language parameter. For example, a search for 100 Main St, Anytown, USA may return 100 Main St, Any Town, USA by default. But if you select fr as the Language, then the results may return 100 Rue Principale, Any Town, États-Unis instead.

  • Language – A language code to use for rendering the results of your query. The value must be a valid BCP 47 language code. For example, en for English.

Note

If Language is not specified, or the specified language is not supported for a result, the partner's default language for that result will be used.

The following example is a SearchPlaceIndexforText request to search for a place called Any Town with the preferred language specified as de.

POST /places/v0/indexes/ExamplePlaceIndex/search/text 
Content-type: application/json
{
   "Text": "Any Town",
   "Language": "de"
}

Example response

The following is an example response when you call the SearchPlaceIndexForText operation from the Amazon Location Places APIs. The results include relevant places and the request summary. Two responses are shown, based on selecting Esri or HERE as the partner.

Example request
POST /places/v0/indexes/ExamplePlaceIndex/search/text 
Content-type: application/json

{
   "Text": "Amazon",
   "MaxResults": 1,
   "FilterCountries": ["USA"],
   "BiasPosition": [-112.10, 46.32]
}
Example response (Esri)
{
    "Results": [
        {
            "Place": {
                "Country": "USA",
                "Geometry": {
                    "Point": [
                        -112.10667999999998,
                        46.319090000000074
                    ]
                },
                "Interpolated": false,
                "Label": "Amazon, MT, USA",
                "Municipality": "Amazon",
                "Region": "Montana",
                "SubRegion": "Jefferson County"
            },
            "Distance": 523.4619749879726,
            "Relevance": 1
        }
    ],
    "Summary": {
        "BiasPosition": [
            -112.1,
            46.32
        ],
        "DataSource": "Esri",
        "FilterCountries": [
            "USA"
        ],
        "MaxResults": 1,
        "ResultBBox": [
            -112.10667999999998,
            46.319090000000074,
            -112.10667999999998,
            46.319090000000074
        ],
        "Text": "Amazon"
    }
}
Example response (HERE)
{
    "Summary": {
        "Text": "Amazon",
        "BiasPosition": [
            -112.1,
            46.32
        ],
        "FilterCountries": [
            "USA"
        ],
        "MaxResults": 1,
        "ResultBBox": [
            -112.10668,
            46.31909,
            -112.10668,
            46.31909
        ],
        "DataSource": "Here"
    },
    "Results": [
        {
            "Place": {
                "Label": "Amazon, Jefferson City, MT, United States",
                "Geometry": {
                    "Point": [
                        -112.10668,
                        46.31909
                    ]
                },
                "Neighborhood": "Amazon",
                "Municipality": "Jefferson City",
                "SubRegion": "Jefferson",
                "Region": "Montana",
                "Country": "USA",
                "Interpolated": false,
                "TimeZone": {
                    "Name": "America/Denver",
                    "Offset": -25200
                }
            },
            "PlaceId": "AQAAAIAADsn2T3KdrRWeaXLeVEyjNx_JfeTsMB0NVCEAnAZoJ-o3nqdlJZAdgcT2oWi1w9pS4wXXOk3O1vsKlGsPyHjV4EJxsu289i3hVO_BUPgP7SFoWAi8BW2v7LvAjQ5NfUPy7a1v9ajT3feIqcUZszWSTqKbJHFYvQqW7wdqhpQq3Wy-et39ZQDWSPLZUzgcjN-6VD2gyKkH0Po7gSm8YSJNSQ",            "Distance": 523.4619749905755
        }
    ]
}