Nearby
Get nearest points of interest based on a specified location.
Overview
Woosmap Localities Nearby allows you to look for points of interest within a defined area (latitude, longitude and a radius). You can narrow down your query by specifying the category you are seeking.
A Woosmap Localities nearby request is an HTTP URL of the following form:
https://api.woosmap.com/localities/nearby?key={PUBLIC_API_KEY}&location={COORDINATES}&types{LIST_OF_TYPES}
Required Parameters
location
The point around which to retrieve place information. It must be specified in the latitude,longitude string format.
types
The types of suggestion to return. Currently, only point_of_interest is supported by Localities Nearby. More types will be included in future updates.
key
Your project’s API key. This key identifies your Woosmap Project for security and quota management purposes. Public keys are designed to be used client side, where every request contain a referer. Alternatively, you can use the parameter private_key for server side requests.
Reminder: To use the Localities API, your Public API key (parameter key) has to be authorized for the domains and/or IPs (referer) where you make the call. More on securing API keys here.
You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.
private_key
Your project’s private API key. This key identifies your Woosmap Project for purposes of security and quota management. Private keys are designed to be used server side, no referer checking associated with those keys.
You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.
Optional parameters
radius
This parameter may be used in addition to the location parameter to define the distance in meters within which the API will return results. When not specified, radius defaults to 1000 meters
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 |
limit
Defines how many results should be included in single page. In case of navigation between pages, limit must not be updated. When not specified, limit defaults to 10 points of interest.
page
Use page to navigate through paginated results. In the response, pagination object informs about a potential next page.
Response
Localities Nearby provides a JSON response containing 2 root elements, pagination, that helps to navigate through paginated results, and results, which contains an array of suggestions sorted from nearest to farthest.
{
"results":
[
{
"public_id": "emXdi2D7RXOpIthsEyKVGBYZVSc=",
"types": ["point_of_interest"],
"categories": ["business.finance.bank"],
"name": "Citibank",
"geometry":
{ "location": { "lat": 40.7130414767567, "lng": -74.0074818610995 } },
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "95FQZAdnETzbfFTEFVb/oofxJ4U=",
"types": ["point_of_interest"],
"categories": ["business.food_and_drinks.restaurant"],
"name": "Gran Morsi",
"geometry":
{
"location": { "lat": 40.71432885326513, "lng": -74.00778746528921 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "c5rIR48wx55zG9RmeFYI7yujDwg=",
"types": ["point_of_interest"],
"categories": ["business.food_and_drinks.restaurant"],
"name": "Saffron",
"geometry":
{
"location": { "lat": 40.714654825479556, "lng": -74.0077106032371 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "eFFoZUgHxyJJNH+Hpm2MbBXPg5Y=",
"types": ["point_of_interest"],
"categories": ["business.food_and_drinks.fast_food"],
"name": "Burger King",
"geometry":
{
"location": { "lat": 40.71619516782573, "lng": -74.00480635760651 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "6GSB3ngwjf3vpdOUnj2TZO2ecOc=",
"types": ["point_of_interest"],
"categories": ["business.food_and_drinks.fast_food"],
"name": "Dunkin'",
"geometry":
{
"location": { "lat": 40.71471299588757, "lng": -74.00777455715831 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "GjVqQF0y4/8+puILSl4GwcvTpG8=",
"types": ["point_of_interest"],
"categories": ["business.shop.grocery"],
"name": "Barakth & Saiful",
"geometry":
{
"location": { "lat": 40.71499001778744, "lng": -74.00766701734061 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "FAs4bm8/XWAzeqIfWy3c5vNNuJM=",
"types": ["point_of_interest"],
"categories": ["business.food_and_drinks.cafe"],
"name": "Hungry Ghost",
"geometry":
{
"location": { "lat": 40.71527793616147, "lng": -74.00745294353355 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "eev6v7sxhhbvAagkbC5NAKqzGV8=",
"types": ["point_of_interest"],
"categories": ["business.shop.grocery"],
"name": "Mr. Exotix",
"geometry":
{
"location": { "lat": 40.71523761920719, "lng": -74.00749141646912 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "VDUWUBQS+dBD6NJyMqfEondAEZE=",
"types": ["point_of_interest"],
"categories": ["business.shop.grocery"],
"name": "Civic Deli",
"geometry":
{
"location": { "lat": 40.71606784671653, "lng": -74.00377261748812 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
{
"public_id": "X8aAA+6/fLGaHeZkbc6EiqzOVR8=",
"types": ["point_of_interest"],
"categories": ["business.shop.grocery"],
"name": "Tribeca Deli Grill",
"geometry":
{
"location": { "lat": 40.7149423247584, "lng": -74.00771462655064 },
},
"address_components":
[
{
"types": ["country", "administrative_area_level_0"],
"long_name": "United States",
"short_name": "us",
},
],
},
],
"pagination": { "previous_page": 2, "next_page": 4 },
}
Suggestion results can contain the following fields:
public_id
Contains a unique ID for each suggestion.
types
Contains the types of the suggestion, See the list of existing types.
categories
Contains the categories of the suggestion, See the list of existing categories.
geometry
The location of the result, in latitude and longitude.
address_components
Detailed fields of the result (long and short). Currently, only country code is returned by Localities Nearby. More components will be included in future updates.
Samples
Usage limits
The following usage limits are in place for the Localities API on the nearby endpoint:
- Maximum of 5 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries)