Localities Nearby API
Discover and filter points of interest (POIs) within a specified radius of any location. Use this API to find restaurants, stores, hotels, and more, with support for type-based queries and precise geolocation.
- What is the Nearby API?
- When to Use This API
- API Endpoint
- Request Parameters
- Implementation Options
- API Request Examples
- Understanding the Response
- Response Examples
- Usage Limits & Quotas
- Working Code Examples
- Related Features
Complete API Specification: Nearby API Reference
What is the Nearby API?
The Nearby API finds points of interest (POIs) within a specified radius of any location. It returns places like restaurants, shops, hotels, hospitals, parks, and more, sorted by distance from your search center.
What It Does
Nearby takes coordinates and a radius, then returns up to 10 POIs per page (configurable) sorted nearest to farthest.
You filter results by types—either including specific types (types=business.shop|medical.pharmacy) or
excluding them (excluded_types=business.food_and_drinks.fast_food). Results include coordinates, types, and
basic address information.
Key Characteristics
This is a radius-based spatial search, not a text search. You must provide coordinates—get them from user geolocation, a
geocoded address, or a selected autocomplete suggestion. Results are paginated, with navigation metadata included in
each response. The type system is hierarchical, so filtering by business includes all sub-types like
business.shop, business.food_and_drinks, etc.
When to Use This API
Use Nearby for “find nearby” features, store locators showing points of interest around a location, discovery interfaces for restaurants or services near a user, or location-based recommendations. It’s perfect for mobile apps showing what’s around the user’s current position or web apps displaying POIs near a selected address. For example, hotel booking platforms can use Nearby to show the nearest restaurants, tourist attractions, or transportation options on hotel detail pages.
Don’t use Nearby for address search—that’s what Autocomplete is for. If you need to convert an address to coordinates first, use Geocoding, then call Nearby with the resulting coordinates.
API Endpoint
GET https://api.woosmap.com/localities/nearby
Authentication
Authenticate using either a key (public API key for client-side requests) or private_key (for server-side requests).
Public keys require domain/IP restrictions, while private keys should be kept secret and never exposed in client code.
# Client-side
?location=48.863469,2.330941&types=point_of_interest&key=YOUR_PUBLIC_KEY
# Server-side
?location=48.863469,2.330941&types=point_of_interest&private_key=YOUR_PRIVATE_KEY
For complete authentication details and security best practices, see API Keys Documentation.
Request Parameters
Required Parameters
location - Search center coordinates in latitude,longitude format (e.g., 48.863469,2.330941).
types - POI types to include (pipe-separated). For example: business.shop|medical.pharmacy|bank.
See types list below.
key or private_key - Your API authentication key. See Authentication above.
Key Optional Parameters
radius - Search distance in meters (default: 1000). Defines how far from the location to search for POIs.
excluded_types - POI types to exclude (pipe-separated). For example:
business.food_and_drinks.fast_food|business.food_and_drinks.pub.
Common POI Types
| Type | Description |
|---|---|
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 |
Complete Parameter Reference
For all available parameters and the complete poi type hierarchy, see the OpenAPI Specification.
Implementation Options
Choose the best integration approach for your project. See the Integration Path Guide for detailed comparison of REST API, Widget, JS SDK, Map JS API, and Store Locator options.
API Request Examples
Basic Nearby Search
curl "https://api.woosmap.com/localities/nearby/?location=48.863469,2.330941&types=point_of_interest&key=YOUR_KEY"
With Type Filter
# Find restaurants and cafes within 2km
curl "https://api.woosmap.com/localities/nearby/?location=48.863469,2.330941&types=business.food_and_drinks&radius=2000&key=YOUR_KEY"
With Excluded Types
# Find all businesses except fast food
curl "https://api.woosmap.com/localities/nearby/?location=48.863469,2.330941&types=business&excluded_types=business.food_and_drinks.fast_food&key=YOUR_KEY"
Multi-Language Examples
https://api.woosmap.com/localities/nearby
?location=40.71399%2C-74.00499
&page=3
&types=business
&key=YOUR_PUBLIC_API_KEY
curl -L 'https://api.woosmap.com/localities/nearby?types=business&location=40.71399%2C-74.00499&page=3&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'
const requestOptions = {
method: "GET",
redirect: "follow"
};
fetch("https://api.woosmap.com/localities/nearby?types=business&location=40.71399%2C-74.00499&page=3&key=YOUR_PUBLIC_API_KEY", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://api.woosmap.com/localities/nearby?types=business&location=40.71399%2C-74.00499&page=3&key=YOUR_PUBLIC_API_KEY',
headers: {
'Referer': 'http://localhost'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
url = "https://api.woosmap.com/localities/nearby?types=business&location=40.71399%2C-74.00499&page=3&key=YOUR_PUBLIC_API_KEY"
payload = {}
headers = {
'Referer': 'http://localhost'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://api.woosmap.com/localities/nearby?types=business&location=40.71399%2C-74.00499&page=3&key=YOUR_PUBLIC_API_KEY")
.method("GET", body)
.addHeader("Referer", "http://localhost")
.build();
Response response = client.newCall(request).execute();
require "uri"
require "net/http"
url = URI("https://api.woosmap.com/localities/nearby?types=business&location=40.71399%2C-74.00499&page=3&key=YOUR_PUBLIC_API_KEY")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"
response = https.request(request)
puts response.read_body
Understanding the Response
The API returns POIs sorted from nearest to farthest, with pagination metadata. For complete response schema, see the OpenAPI Specification.
Key Response Fields
public_id - Unique identifier for each POI. Use this with
the Details API to get complete information.
types - POI type classification (e.g., ["point_of_interest", "business.food_and_drinks.restaurant"]).
geometry - Location coordinates
"geometry": {
"location": {"lat": 48.864716, "lng": 2.331775}
}
address_components - Currently returns country code only. More fields coming in future updates.
pagination - Navigation metadata showing current page, next page availability, and total results.
Response Examples
{
"results":
[
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLmZvb2RfYW5kX2RyaW5rcy5mYXN0X2Zvb2Q6ZTc2ZDA1YzBiM2M0M2NmNmVkNTJjNGQyZDFiZDE3Nzc0OTZkNjlmOA==",
"types": ["point_of_interest", "business.food_and_drinks.fast_food"],
"categories": ["business.food_and_drinks.fast_food"],
"name": "Pret A Manger",
"formatted_address": "Broadway, New York",
"geometry":
{
"location":
{ "lat": 40.715905992166256, "lng": -74.00508673226767 },
},
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
{
"types": ["locality"],
"long_name": "New York",
"short_name": "New York",
},
{
"types": ["route"],
"long_name": "Broadway",
"short_name": "Broadway",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLmZvb2RfYW5kX2RyaW5rcy5mYXN0X2Zvb2Q6MzBlMGYxMzVhNGUzZDQ4MzRiMmNlNDMzMWJiYjZkOTY0MWJhN2E0Zg==",
"types": ["point_of_interest", "business.food_and_drinks.fast_food"],
"categories": ["business.food_and_drinks.fast_food"],
"name": "Dunkin'",
"formatted_address": "Broadway, New York",
"geometry":
{
"location": { "lat": 40.71602115951586, "lng": -74.00494482664695 },
},
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
{
"types": ["locality"],
"long_name": "New York",
"short_name": "New York",
},
{
"types": ["route"],
"long_name": "Broadway",
"short_name": "Broadway",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLmZvb2RfYW5kX2RyaW5rcy5yZXN0YXVyYW50OmJlMWNkMTE2ZDQwM2E0Y2YwNGQ5NWQ2OTlmZWRmM2FhZTExNGU3ZWY=",
"types": ["point_of_interest", "business.food_and_drinks.restaurant"],
"categories": ["business.food_and_drinks.restaurant"],
"name": "Chambers",
"formatted_address": "Chambers Street, New York",
"geometry":
{
"location": { "lat": 40.71461844801976, "lng": -74.00754036678366 },
},
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
{
"types": ["locality"],
"long_name": "New York",
"short_name": "New York",
},
{
"types": ["route"],
"long_name": "Chambers Street",
"short_name": "Chambers Street",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLnNob3AuZ3JvY2VyeTo1YTczMjYxOTQyYjVlZmUwOGEzZjQ1NGZmMTMwMmJjNjA4ODE3NmRk",
"types": ["point_of_interest", "business.shop.grocery"],
"categories": ["business.shop.grocery"],
"name": "City Hall Oasis",
"geometry":
{
"location": { "lat": 40.71283012706819, "lng": -74.00727837935057 },
"viewport":
{
"northeast":
{ "lat": 40.71286059528623, "lng": -74.00724213866874 },
"southwest":
{ "lat": 40.71279957503111, "lng": -74.00731464213119 },
},
},
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLmZpbmFuY2UuYmFuazpiOGY5MDE4Nzc2ZDZjNmEwZTljOGM4YWM0OTAxZWZlNzNmODZkM2M3",
"types": ["point_of_interest", "business.finance.bank"],
"categories": ["business.finance.bank"],
"name": "Citibank",
"formatted_address": "Broadway, New York",
"geometry":
{ "location": { "lat": 40.7130414767567, "lng": -74.0074818610995 } },
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
{
"types": ["locality"],
"long_name": "New York",
"short_name": "New York",
},
{
"types": ["route"],
"long_name": "Broadway",
"short_name": "Broadway",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLmZvb2RfYW5kX2RyaW5rcy5yZXN0YXVyYW50OmQzMTMzZTJkODdiOGJjMGE3ZjI2YTdiMWVjYTZlZmI1MjQyYWE3MTE=",
"types": ["point_of_interest", "business.food_and_drinks.restaurant"],
"categories": ["business.food_and_drinks.restaurant"],
"name": "Saffron",
"geometry":
{
"location": { "lat": 40.71467049963849, "lng": -74.00767187884445 },
},
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLmZvb2RfYW5kX2RyaW5rcy5yZXN0YXVyYW50OmQ1NjMyN2RiM2EyNWJlYmIwNjJjZjNlYWYwMDE3ZDIyYzEyNWNlMjY=",
"types": ["point_of_interest", "business.food_and_drinks.restaurant"],
"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", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLmZvb2RfYW5kX2RyaW5rcy5iYXI6MDE5ZGUzNTdiZDkyNzAyZDM4ZDUyOWQ0YmJiZjBmODQ5YWEzZmY1NA==",
"types": ["point_of_interest", "business.food_and_drinks.bar"],
"categories": ["business.food_and_drinks.bar"],
"name": "Bon Courage",
"formatted_address": "Reade Street, New York",
"geometry":
{
"location": { "lat": 40.71541472882126, "lng": -74.00719193106873 },
},
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
{
"types": ["locality"],
"long_name": "New York",
"short_name": "New York",
},
{
"types": ["route"],
"long_name": "Reade Street",
"short_name": "Reade Street",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLmZvb2RfYW5kX2RyaW5rcy5mYXN0X2Zvb2Q6OGIyNDY5MDM4M2JhYzE1NmY4OGRiMGQzYmIyYzNjMTVmOTk0NDQwZQ==",
"types": ["point_of_interest", "business.food_and_drinks.fast_food"],
"categories": ["business.food_and_drinks.fast_food"],
"name": "Burger King",
"formatted_address": "Broadway, New York",
"geometry":
{
"location": { "lat": 40.71619516782573, "lng": -74.00480635760651 },
},
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
{
"types": ["locality"],
"long_name": "New York",
"short_name": "New York",
},
{
"types": ["route"],
"long_name": "Broadway",
"short_name": "Broadway",
},
],
},
{
"public_id": "cG9pOnVzOmJ1c2luZXNzLnRoZWF0cmU6MTU1Yjk5YmEwY2FiYzIzZjYxYWYyYTViYzI0ZDViYTVlNmVmZTAwNA==",
"types": ["point_of_interest", "business.theatre"],
"categories": ["business.theatre"],
"name": "The Flea",
"formatted_address": "Thomas Street, New York",
"geometry":
{
"location": { "lat": 40.71609349534023, "lng": -74.00589281989586 },
},
"address_components":
[
{
"types":
["country", "administrative_area_level_0", "division_level_0"],
"long_name": "United States",
"short_name": "US",
},
{
"types": ["locality"],
"long_name": "New York",
"short_name": "New York",
},
{
"types": ["route"],
"long_name": "Thomas Street",
"short_name": "Thomas Street",
},
],
},
],
"pagination": { "previous_page": 2, "next_page": 4 },
}
Usage Limits & Quotas
- Rate Limit: 50 queries per second (QPS) per project
- Exceeding limits returns
429 Too Many Requests - Contact support for higher quotas
Working Code Examples
See the complete Localities Nearby POI JS Sample for implementation details.
Related Features
Required for Coordinates:
- Geocoding API - Convert addresses to coordinates for Nearby searches
- Autocomplete API + Details API - Get coordinates from user-selected locations
Get Complete POI Information:
- Details API - Fetch full details using the
public_idfrom Nearby results