SearchNearby
SearchNearby queries for points of interest within a radius from a central
coordinates, returning place results with optional filters such as categories, business
chains, food types and more. The API returns details such as a place name, address, phone,
category, food type, contact, opening hours. Also, the API can return phonemes, time zones
and more based on requested parameters.
Request Syntax
POST /search-nearby?key=Key HTTP/1.1
Content-type: application/json
{
"AdditionalFeatures": [ "string" ],
"Filter": {
"BoundingBox": [ number ],
"ExcludeBusinessChains": [ "string" ],
"ExcludeCategories": [ "string" ],
"ExcludeFoodTypes": [ "string" ],
"IncludeBusinessChains": [ "string" ],
"IncludeCategories": [ "string" ],
"IncludeCountries": [ "string" ],
"IncludeFoodTypes": [ "string" ]
},
"IntendedUse": "string",
"Language": "string",
"MaxResults": number,
"NextToken": "string",
"PoliticalView": "string",
"QueryPosition": [ number ],
"QueryRadius": number
}URI Request Parameters
The request uses the following URI parameters.
- Key
-
Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request.
Length Constraints: Minimum length of 0. Maximum length of 1000.
Request Body
The request accepts the following data in JSON format.
- AdditionalFeatures
-
A list of optional additional parameters, such as time zone, that can be requested for each result.
Type: Array of strings
Array Members: Minimum number of 1 item. Maximum number of 4 items.
Valid Values:
TimeZone | Phonemes | Access | ContactRequired: No
- Filter
-
A structure which contains a set of inclusion/exclusion properties that results must posses in order to be returned as a result.
Type: SearchNearbyFilter object
Required: No
- IntendedUse
-
Indicates if the results will be stored. Defaults to
SingleUse, if left empty.Note
Storing the response of an SearchNearby query is required to comply with service terms, but charged at a higher cost per request. Please review the user agreement
and service pricing structure to determine the correct setting for your use case. Type: String
Valid Values:
SingleUse | StorageRequired: No
- Language
-
A list of BCP 47
compliant language codes for the results to be rendered in. If there is no data for the result in the requested language, data will be returned in the default language for the entry. Type: String
Length Constraints: Minimum length of 2. Maximum length of 35.
Required: No
- MaxResults
-
An optional limit for the number of results returned in a single call.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 100.
Required: No
- NextToken
-
If
nextTokenis returned, there are more results available. The value ofnextTokenis a unique pagination token for each page.Type: String
Length Constraints: Minimum length of 1. Maximum length of 2000.
Required: No
- PoliticalView
-
The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country.
Type: String
Length Constraints: Minimum length of 2. Maximum length of 3.
Pattern:
([A-Z]{2}|[A-Z]{3})Required: No
- QueryPosition
-
The position, in
[lng, lat]for which you are querying nearby resultsfor. Results closer to the position will be ranked higher then results further away from the positionType: Array of doubles
Array Members: Fixed number of 2 items.
Required: Yes
- QueryRadius
-
The maximum distance in meters from the QueryPosition from which a result will be returned.
Note
The fields
QueryText, andQueryIDare mutually exclusive.Type: Long
Valid Range: Minimum value of 1. Maximum value of 21000000.
Required: No
Response Syntax
HTTP/1.1 200
x-amz-geo-pricing-bucket: PricingBucket
Content-type: application/json
{
"NextToken": "string",
"ResultItems": [
{
"AccessPoints": [
{
"Position": [ number ]
}
],
"AccessRestrictions": [
{
"Categories": [
{
"Id": "string",
"LocalizedName": "string",
"Name": "string",
"Primary": boolean
}
],
"Restricted": boolean
}
],
"Address": {
"AddressNumber": "string",
"Block": "string",
"Building": "string",
"Country": {
"Code2": "string",
"Code3": "string",
"Name": "string"
},
"District": "string",
"Intersection": [ "string" ],
"Label": "string",
"Locality": "string",
"PostalCode": "string",
"Region": {
"Code": "string",
"Name": "string"
},
"Street": "string",
"StreetComponents": [
{
"BaseName": "string",
"Direction": "string",
"Language": "string",
"Prefix": "string",
"Suffix": "string",
"Type": "string",
"TypePlacement": "string",
"TypeSeparator": "string"
}
],
"SubBlock": "string",
"SubDistrict": "string",
"SubRegion": {
"Code": "string",
"Name": "string"
}
},
"AddressNumberCorrected": boolean,
"BusinessChains": [
{
"Id": "string",
"Name": "string"
}
],
"Categories": [
{
"Id": "string",
"LocalizedName": "string",
"Name": "string",
"Primary": boolean
}
],
"Contacts": {
"Emails": [
{
"Categories": [
{
"Id": "string",
"LocalizedName": "string",
"Name": "string",
"Primary": boolean
}
],
"Label": "string",
"Value": "string"
}
],
"Faxes": [
{
"Categories": [
{
"Id": "string",
"LocalizedName": "string",
"Name": "string",
"Primary": boolean
}
],
"Label": "string",
"Value": "string"
}
],
"Phones": [
{
"Categories": [
{
"Id": "string",
"LocalizedName": "string",
"Name": "string",
"Primary": boolean
}
],
"Label": "string",
"Value": "string"
}
],
"Websites": [
{
"Categories": [
{
"Id": "string",
"LocalizedName": "string",
"Name": "string",
"Primary": boolean
}
],
"Label": "string",
"Value": "string"
}
]
},
"Distance": number,
"FoodTypes": [
{
"Id": "string",
"LocalizedName": "string",
"Primary": boolean
}
],
"MapView": [ number ],
"OpeningHours": [
{
"Categories": [
{
"Id": "string",
"LocalizedName": "string",
"Name": "string",
"Primary": boolean
}
],
"Components": [
{
"OpenDuration": "string",
"OpenTime": "string",
"Recurrence": "string"
}
],
"Display": [ "string" ],
"OpenNow": boolean
}
],
"Phonemes": {
"Address": {
"Block": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
],
"Country": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
],
"District": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
],
"Locality": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
],
"Region": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
],
"Street": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
],
"SubBlock": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
],
"SubDistrict": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
],
"SubRegion": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
]
},
"Title": [
{
"Language": "string",
"Preferred": boolean,
"Value": "string"
}
]
},
"PlaceId": "string",
"PlaceType": "string",
"PoliticalView": "string",
"Position": [ number ],
"TimeZone": {
"Name": "string",
"Offset": "string",
"OffsetSeconds": number
},
"Title": "string"
}
]
}Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The response returns the following HTTP headers.
- PricingBucket
-
The pricing bucket for which the query is charged at.
For more information on pricing, please visit Amazon Location Service Pricing
.
The following data is returned in JSON format by the service.
- NextToken
-
If
nextTokenis returned, there are more results available. The value ofnextTokenis a unique pagination token for each page.Type: String
Length Constraints: Minimum length of 1. Maximum length of 2000.
- ResultItems
-
List of places or results returned for a query.
Type: Array of SearchNearbyResultItem objects
Array Members: Minimum number of 0 items. Maximum number of 100 items.
Errors
For information about the errors that are common to all actions, see Common Errors.
- AccessDeniedException
-
You don't have sufficient access to perform this action.
HTTP Status Code: 403
- InternalServerException
-
The request processing has failed because of an unknown error, exception or failure.
HTTP Status Code: 500
- ThrottlingException
-
The request was denied due to request throttling.
HTTP Status Code: 429
- ValidationException
-
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
