Search
Search for points of interest based on textual input and a geographical bias along with usual Localities supported types.
Overview
The Localities Search endpoint provides results for text-based geographic searches. It can match both complete words and substrings. The retrieved locations are designed to assist users in selecting their desired place. To obtain additional details about a result, you must send a /Details request using its public_id.
A Woosmap Localities Search request is an HTTP URL formatted as follows:
https://api.woosmap.com/localities/search?key={PUBLIC_API_KEY}&location={COORDINATES}&types={LIST_OF_TYPES}&input={TEXTUAL_INPUT}&components={LIST_OF_COUNTRIES}
The complete OpenAPI reference for Localities Search is available here
Required Parameters
input
The search query string.
components
Geographic areas to which you want to restrict the results. Currently, components can be used to filter results by country. Countries are identified using a two-character ISO 3166-1 Alpha-2 code or a three-character ISO 3166-1 Alpha-3 code. Multiple countries should be separated by a pipe character (|).
Currently, only France (fr) and the United Kingdom (gb) are supported. Coverage will be expanded in the future.
location
This parameter is used to apply a geographical bias to the query. The location specifies the point around which results should be prioritized. It must be provided in the latitude,longitude string format.
types
The types of suggestions to return. Below are the most commonly used types; the complete list is available here:
point_of_interest |
point_of_interest |
locality |
includes locality names (from city to village) and suburbs |
postal_code |
publicly-used postal codes around the world |
address |
addresses |
admin_level |
most commonly used administrative areas |
country |
countries as whole point of interest |
key
Your project’s API key, which identifies your Woosmap Project for security and quota management purposes. Public API keys are intended for client-side use, where every request includes a referer. Alternatively, for server-side requests, you can use the private_key parameter.
Reminder: To use the Localities API, your Public API key (key parameter) must be authorized for the domains and/or IPs (referer) from which the request is made. More details on securing API keys are available here.
You must use either the key parameter OR the private_key parameter. Sending both keys will result in an error.
private_key
Your project’s private API key, used for security and quota management. Private keys are intended for server-side use and do not require referer verification.
Optional Parameters
radius
Defines the search radius (in meters) around the specified location within which the API will return results. If omitted, the default radius is 1,000 meters.
excluded_types
Specifies types of locations to exclude. Multiple types should be separated using the pipe character (|).
language
Defines the preferred language for results. If omitted, the API will use the browser’s Accept-Language header. If neither the specified language nor the Accept-Language header is recognized, the Localities service defaults to English.
Response
Below is an example of a Localities Search response for the textual input "Tower bridge":
{
"results": [
{
"public_id": "CM8AK9E/oYn+RSho9ZFAMjJPF7M=",
"types": [
"point_of_interest"
],
"title": "Tower Bridge",
"description": "London, United Kingdom",
"categories": [
"tourism.attraction"
]
},
{
"public_id": "FA0HZt3n6q8ibr9234PUbxAhQwM=",
"types": [
"point_of_interest"
],
"title": "Tower Bridge Exhibition",
"description": "Tower Bridge Road, London, United Kingdom",
"categories": [
"tourism.museum"
]
},
{
"public_id": "gOiaI5hA5EY+0JLVAJlGT+l0ZMQ=",
"types": [
"route"
],
"title": "Tower Bridge Mews",
"description": "Harrow (HA1 3QU), United Kingdom"
},
{
"public_id": "0FYGohBu9HcSaxHE4dIl1UMVHRg=",
"types": [
"route"
],
"title": "Tower Bridge Road",
"description": "London (SE1 4TL), United Kingdom"
},
{
"public_id": "0GtuXpq23mRWMKvxYaFebw7q6Oc=",
"types": [
"route"
],
"title": "Tower Bridge Road",
"description": "London (SE1 4TR), United Kingdom"
}
]
}
Samples
Usage Limits
The following rate limits apply to the Localities API search endpoint:
- Maximum of 5 queries per second (QPS) per Project (including both client-side and server-side queries).