Source: https://developers.woosmap.com/products/localities/features/nearby/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Localities Nearby **Complete API Specification** : [Nearby Endpoint Reference](/api-reference/localities-api/get-localities-nearby/) ## What is the Nearby Endpoint? The Nearby Endpoint 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 Endpoint 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 [Localities Autocomplete](/products/localities/features/autocomplete/) is for. If you need to convert an address to coordinates first, use [Localities Geocoding](/products/localities/features/geocoding/), then call Nearby with the resulting coordinates. ## API Endpoint ```http 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. You can also use the `X-Api-Key` header for server-side or mobile authentication. ```shell # Client-side (query parameter) ?location=48.863469,2.330941&types=point_of_interest&key=YOUR_PUBLIC_KEY # Server-side (query parameter) ?location=48.863469,2.330941&types=point_of_interest&private_key=YOUR_PRIVATE_KEY # Server-side / Mobile (header) -H "X-Api-Key: YOUR_PRIVATE_KEY" ``` For complete authentication details and security best practices, see [API Keys Documentation](/api-reference/authentication/). ## 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](#common-poi-types) below. **`key`** or **`private_key`** - Your API authentication key. See [Authentication](#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](/api-reference/localities-api/get-localities-nearby/). ## Implementation Options Choose the best integration approach for your project. See the [Integration Path Guide](/products/localities/guides/integration-path/) for detailed comparison of REST API, Widget, JS SDK, Map JS API, and Store Locator options. ## Request Examples ### Basic Nearby Search ```shell curl "https://api.woosmap.com/localities/nearby/?location=48.863469,2.330941&types=point_of_interest&key=YOUR_KEY" ``` ### With Type Filter ```shell # 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 ```shell # 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 ```javascript 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)); ``` ```shell 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' ``` ```python 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) ``` ```text https://api.woosmap.com/localities/nearby ?location=40.71399%2C-74.00499 &page=3 &types=business &key=YOUR_PUBLIC_API_KEY ``` ```javascript 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); }); ``` ```java 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(); ``` ```ruby 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 Localities Nearby returns POIs sorted from nearest to farthest, with pagination metadata. For the complete response schema, see the [OpenAPI Specification](/api-reference/localities-api/get-localities-nearby/). ### Key Response Fields **`public_id`** - Unique identifier for each POI. Use this with [Localities Details](/products/localities/features/details/) to get complete information. **`types`** - POI type classification (e.g., `["point_of_interest", "business.food_and_drinks.restaurant"]`). **`geometry`** - Location coordinates ```json "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 ```json { "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](/js-samples/localities-nearby-poi/) for implementation details. https://demo.woosmap.com/js-samples/samples/localities-nearby-poi/app/dist/ [](https://demo.woosmap.com/js-samples/samples/localities-nearby-poi/highlight/highlight.html "Open in new tab with highlighted code") Try sample - [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/localities-nearby-poi/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-nearby-poi/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-nearby-poi) ## Related Features **Required for Coordinates:** - [Localities Geocoding](/products/localities/features/geocoding/) - Convert addresses to coordinates for Nearby searches - [Localities Autocomplete](/products/localities/features/autocomplete/) + [Localities Details](/products/localities/features/details/) - Get coordinates from user-selected locations **Get Complete POI Information:** - [Localities Details](/products/localities/features/details/) - Fetch full details using the `public_id` from Nearby results