Note
Stored results incur higher Storage pricing. Use the IntendedUse parameter to indicate single-use or
storage. Refer to the Places pricing to understand cost implications for stored results.
Geocoding transforms textual addresses or place names into geographic coordinates, along with detailed address components and additional information. This API supports flexible queries, including both free-form text and structured queries with street names, postal codes, and regions. Optional features include time zone data and political view adjustments.
Use cases
-
Add supplementary data to customer addresses: Improve address records by including zip codes, coordinates, and utilizing persistent storage to support informed business and marketing decisions.
-
Address Data Standardization: Apply geocoding in data pipelines or batch processes to standardize address data, utilizing persistent storage for ongoing reference.
-
Determine Time Zones: Identify the time zone for cities or addresses to provide accurate timestamps for applications like travel, scheduling, and invoicing.
Understand the request
The request accepts optional parameters, such as AdditionalFeatures, BiasPosition, and Filter, to refine the search results. Additional options, like Language, MaxResults, and PoliticalView, provide further customization of the response. The required parameter is Query, which can be provided as free-form text or structured as QueryComponents. For more information, refer to the Geocode API Reference.
The request includes the following key parameters:
- Authentication
-
For authentication, the
Keyparameter is optional if other methods are in use.Key: Optional parameter for authentication.
For more information, see Authenticate with Amazon Location Service
- Querying and biasing
-
Parameters used for querying and geographic biasing of results.
QueryText: Free-form text query for searching locations.QueryComponents: Structured components such as address number, country, locality, or postal code for precise searching.BiasPosition: Geographic position to bias search results towards.
For more information, see Querying and biasing
- Refining Results
-
Apply filters to refine the results.
Filter: Filter to include specific countries or place types. For more information, see Filtering.
- Internationalization and localization
-
Specify language and apply political view for localized results.
Language: Language for the results.PoliticalView: Applies a political view reflecting territorial claims.
For more information, see Localization and internationalization
- Additional Features
-
Request additional information like time zone details.
AdditionalFeatures: Option to request additional details such as time zone. For more information, see Additional features.
Understand the response
The response provides ResultItems, which contain detailed location data such as
Address, PlaceId, Position, and other relevant attributes. Additional features like TimeZone
information or match scores for each query component may also be included. Each ResultItem represents a
matched location or geocoding result based on the specified request parameters. For further details, see the Geocode API Reference.
The response includes the following key parameters:
- Address and related details
-
Details about the returned location, including address components.
Address: Full address including country, region, postal code, and street details.PostalCodeDetails: Additional information related to postal codes.StreetComponents: Street details including base name and type.
- Place types and categories
-
Information on the type and category of place returned.
Categories: List of categories describing the place, for example Restaurants, Schools.PlaceType: Specifies the type of place, such as city, address, or region.
- Result analysis
-
Scores indicating how closely results match the input query.
MatchScores: Scores for matching precision.
- Additional details
-
Includes extra location-related information as needed.
AccessPoints: Geographic coordinates representing access points.TimeZone: Time zone information for the location.
