SearchText - Amazon Location Service
Request SyntaxURI Request ParametersRequest BodyResponse SyntaxResponse ElementsErrorsSee Also

SearchText

SearchText searches for geocode and place information. You can then complete a follow-up query suggested from the Suggest API via a query id.

For more information, see Search Text in the Amazon Location Service Developer Guide.

Request Syntax

POST /search-text?key=Key HTTP/1.1
Content-type: application/json

{
   "AdditionalFeatures": [ "string" ],
   "BiasPosition": [ number ],
   "Filter": { 
      "BoundingBox": [ number ],
      "Circle": { 
         "Center": [ number ],
         "Radius": number
      },
      "IncludeCountries": [ "string" ]
   },
   "IntendedUse": "string",
   "Language": "string",
   "MaxResults": number,
   "NextToken": "string",
   "PoliticalView": "string",
   "QueryId": "string",
   "QueryText": "string"
}

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. For GrabMaps customers, ap-southeast-1 and ap-southeast-5 regions support only the TimeZone value.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 4 items.

Valid Values: TimeZone | Phonemes | Access | Contact

Required: No

BiasPosition

The position, in longitude and latitude, that the results should be close to. Typically, place results returned are ranked higher the closer they are to this position. Stored in [lng, lat] and in the WGS 84 format.

Note

Exactly one of the following fields must be set: BiasPosition, Filter.BoundingBox, or Filter.Circle.

Type: Array of doubles

Array Members: Fixed number of 2 items.

Required: No

Filter

A structure which contains a set of inclusion/exclusion properties that results must possess in order to be returned as a result.

Type: SearchTextFilter object

Required: No

IntendedUse

Indicates if the query results will be persisted in customer infrastructure. Defaults to SingleUse (not stored).

Note

When storing SearchText responses, you must set this field to Storage to comply with the terms of service. These requests will be charged at a higher rate. Please review the user agreement and service pricing structure to determine the correct setting for your use case.

Type: String

Valid Values: SingleUse | Storage

Required: 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. For GrabMaps customers, ap-southeast-1 and ap-southeast-5 regions support only the following codes: en, id, km, lo, ms, my, pt, th, tl, vi, zh

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.

Default value: 20

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No

NextToken

If nextToken is returned, there are more results available. The value of nextToken is 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. Not available in ap-southeast-1 and ap-southeast-5 regions for GrabMaps customers.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 3.

Pattern: ([A-Z]{2}|[A-Z]{3})

Required: No

QueryId

The query Id returned by the suggest API. If passed in the request, the SearchText API will preform a SearchText query with the improved query terms for the original query made to the suggest API. Not available in ap-southeast-1 and ap-southeast-5 regions for GrabMaps customers.

Note

Exactly one of the following fields must be set: QueryText or QueryId.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 500.

Required: No

QueryText

The free-form text query to match addresses against. This is usually a partially typed address from an end user in an address box or form.

Note

Exactly one of the following fields must be set: QueryText or QueryId.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

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"
            },
            "SecondaryAddressComponents": [ 
               { 
                  "Designator": "string",
                  "Number": "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 nextToken is returned, there are more results available. The value of nextToken is 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 SearchTextResultItem 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 Error Types.

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.

FieldList

Test stub for FieldList.

Reason

Test stub for reason

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: