Geocoding - Amazon Location Service

Geocoding

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.

If you want to specify a maximum number of results per pages, use the following optional parameter:

  • MaxResults – Limits the maximum number of results returned per page.

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.1387.

  • The latitude of the southwest corner is 41.7096.

  • The longitude of the upper northeast corner is -124.1450.

  • The longitude of the upper northeast corner is 41.7045.

POST /places/v0/indexes/ExamplePlaceIndex/search/text Content-type: application/json { "Text": "Any Town", "FilterBBox": [ [-124.1387,41.7096], [-124.1450,41.7045] ] }

Geocode within a country

You can geocode within a country 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 3-digit country code. For example, 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"] }

Example response

The following is an example response when calling the SearchPlaceIndexForText operation from the Amazon Location Places APIs. The results returns relevant places and the request summary.

Example request
POST /places/v0/indexes/ExamplePlaceIndex/search/text Content-type: application/json { "Text": "Amazon", "MaxResults": 1, "FilterCountries": ["USA"] }
Example response
{ "Results": [ { "Place": { "Country": "USA", "Geometry": { "Point": [ -112.10667999999998, 46.319090000000074 ] }, "Label": "Amazon, MT, USA", "Municipality": "Amazon", "Region": "Montana", "SubRegion": "Jefferson County" } } ], "Summary": { "DataSource": "Esri", "FilterCountries": [ "USA" ], "MaxResults": 50, "ResultBBox": [ -122.03701999999998, 26.696170000000052, -80.14603999999997, 46.319090000000074 ], "Text": "Amazon" } }