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 stringAny 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.
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
FilterBBoxandBiasPositionparameters. Specifying both parameters in the request returns aValidationExceptionerror.
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 3166three letter country code. For example, use AUSfor 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 specifyHotelto 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
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 47language code. For example, enfor 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.
