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 (|).
Please refer to the coverage page for detailed coverage information by country.
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 100,000 meters.
excluded_types
Specifies types of locations to exclude. Multiple types should be separated using the pipe character (|).
categories
This allows you to specify the categories of points of interests that should be returned as suggestions. Multiple categories can be passed using the pipe character (|) as a separator. For example: categories=business.shop|medical.pharmacy|bank. The complete list of categories can be found here
excluded_categories
This allows you to specify categories you want to exclude from the results. Multiple categories can be passed using the pipe character (|) as a separator. For example: excluded_categories=business.food_and_drinks.fast_food|business.food_and_drinks.pub
The list of categories to exclude can be found here
List of categories for point of interest:
The following are the commonly used categories. A detailed list is available here:
business |
All commercial establishments, such as malls, restaurants, and retail shops. |
education |
All establishments related to education like school or university |
government |
Government buildings |
hospitality |
A place or business that provides accommodations, services, and amenities to guests |
medical |
All establishments related to medical like hospital, clinic or pharmacy |
park |
All recreational areas such as public parks, nature reserves, or gardens. |
place_of_worship |
Places of worship, including churches, temples, mosques, and others |
police |
Law enforcement locations, such as police stations. |
post_office |
Post office |
sports |
Sports complex like football fields or tennis court. |
tourism |
All establishments related to tourism |
transit.station |
Transit stations e.g. airport, rail |
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).