Source: https://developers.woosmap.com/products/stores-api/features/search/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Search **Complete API Specification** : [Search Endpoint Reference](/api-reference/search-api/get-stores-search/) ## What is the Search Endpoint? The Search Endpoint queries your store and asset data by combining a query language with spatial filtering in a single request. ### What It Does The endpoint accepts two complementary types of filters. The `query` parameter which uses a structured syntax to filter on store attributes. And Geographic parameters (`lat`, `lng`,`radius`, `encoded_polyline`, `zone`) which restrict results to a specific area. You can use either type alone or combine both for precise results. ### Response Structure Results are returned as a GeoJSON `FeatureCollection` containing all assets that match your criteria. Each feature includes the asset’s geometry (location coordinates) and properties (name, tags, types, user properties, address, contact, opening hours, and other attributes). When geographic filtering is applied, each feature also includes a `distance` field (straight-line distance in meters) from the search center. Results are paginated with page metadata. ### Key Characteristics Attribute queries support exact matching, numeric comparisons, collection membership tests, boolean checks, and datetime filtering. Queries are evaluated server-side, so only matching assets are returned. Geographic parameters are separate from the `query` parameter and act as additional filters. The `radius` parameter (in meters) is always required when filtering by point or polyline. When geographic filtering is active, results are sorted by distance from the search center. ## When to Use This Endpoint Use Search when you need to find stores by specific attributes (type, tag, city, custom properties), by geographic proximity (nearest stores to a location), along a route (stores on a driving path), within zone boundaries (delivery areas, service regions), or any combination of these criteria. It is the primary endpoint for building store locators and filtered search interfaces. Don’t use Search for search-as-you-type on asset names, that’s what [Autocomplete](/products/stores-api/features/autocomplete/) is for. For managing your asset data (import, update, delete), use [Data Management](/products/stores-api/features/data-management/). New to the API? Start with the [Making Your First Request](/products/stores-api/tutorials/making-first-request/) tutorial for a step-by-step introduction. For parameter optimization, see [Tuning Search Results](/products/stores-api/guides/tuning-search-results/). ## API Endpoint ```http GET https://api.woosmap.com/stores/search/ ``` ### Authentication Authenticate using either a `key` (public API key for client-side requests) or `private_key` (for server-side requests). Public keys require domain restrictions and a valid `Referer` header. 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 (Referer header is sent automatically by browsers) ?query=type:"grocery"&key=YOUR_PUBLIC_KEY # Server-side (query parameter) ?lat=48.856&lng=2.352&radius=5000&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 Overview ### Required Parameters **`key`** or **`private_key`** - Your API authentication key. See [Authentication](#authentication) above. ### Search Parameters All search parameters are optional. When called with no `query` or geographic parameters, the endpoint returns all assets in your project (paginated). Use one or both of the following to filter results: **`query`** - A search query string combining one or more search clauses. Each clause is structured as `field:operatorvalue` (e.g., `name:="My cool store"`). See the [Query Syntax](/products/stores-api/concepts/query-syntax/) concept to understand it fully. **`lat`** + **`lng`** + **`radius`** - Geographic center point and search radius in meters for proximity-based search. ### Query Parameter The `query` parameter uses a structured syntax of fields, operators, and values to filter assets. For the complete reference including all searchable fields, operators, combinators (`AND`, `OR`, `NOT`), and URL encoding guidance, see the [Query Syntax](/products/stores-api/concepts/query-syntax/) concept page. ### Geographic Parameters **`lat`** - Latitude of the center point for proximity search (e.g., `48.856`). Must be used together with `lng` and `radius`. **`lng`** - Longitude of the center point for proximity search (e.g., `2.352`). Must be used together with `lat` and `radius`. **`radius`** - Maximum distance in meters from the center point or polyline (e.g., `5000`). Required whenever `lat`/`lng` or `encoded_polyline` is provided. **`encoded_polyline`** - An [encoded polyline](/products/map-api/concepts/polyline-encoding/) representing a route. Assets within the specified `radius` of the polyline are returned. Must be used together with `radius`. **`zone`** - Boolean. When set to `true`, returns assets that possess a [zone](/products/stores-api/features/zones/) intersecting the provided point (`lat`/`lng`). ### Pagination Parameters | Parameter | Description | Default | Max | | --- | --- | --- | --- | | `page` | Page number to retrieve | 1 | – | | `stores_by_page` | Number of assets per page | 100 | 300 | ## Implementation Options Choose the best integration approach for your project. See the [Integration Path Guide](/products/stores-api/guides/integration-path/) for a detailed comparison of REST API, Map JS API, Store Locator Widget, and Mobile SDK options. ## Request Examples The examples below show the main search patterns. For query syntax details and attribute filtering examples, see [Query Syntax](/products/stores-api/concepts/query-syntax/). The `query` parameter value must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent). For example, `type:"grocery"` becomes `type%3A%22grocery%22`. Tools like cURL and Postman handle this automatically when using the `--data-urlencode` flag or the Params tab respectively. ### Geographic Search #### Search Around a Point Find all assets within 3 km of a given location: ```shell curl "https://api.woosmap.com/stores/search/?lat=43.3&lng=3.883&radius=3000&key=YOUR_KEY" ``` #### Combine Geographic and Attribute Filters Find grocery stores within 5 km of central Paris: ```shell curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=5000&query=type:%22grocery%22&key=YOUR_KEY" ``` #### Search Along a Polyline Find assets within 500 meters of an encoded route: ```shell curl "https://api.woosmap.com/stores/search/?encoded_polyline=YOUR_ENCODED_POLYLINE&radius=500&key=YOUR_KEY" ``` #### Zone Intersection Search Find assets whose defined zones intersect a specific point: ```shell curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=1000&zone=true&key=YOUR_KEY" ``` ### Multi-Language Examples Here we search stores nearby a location and within a radius of 300 meters. ```javascript const requestOptions = { method: "GET", redirect: "follow" }; fetch("https://api.woosmap.com/stores/search/?lat=51.50976&lng=-0.145276&radius=300&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/stores/search/?lat=51.50976&lng=-0.145276&radius=300&key=YOUR_PUBLIC_API_KEY' \ -H 'Referer: http://localhost' ``` ```python import requests url = "https://api.woosmap.com/stores/search/?lat=51.50976&lng=-0.145276&radius=300&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/stores/search/ ?lat=51.50976 &lng=-0.145276 &radius=300 &key=YOUR_PUBLIC_API_KEY ``` ```javascript const axios = require('axios'); let config = { method: 'get', maxBodyLength: Infinity, url: 'https://api.woosmap.com/stores/search/?lat=51.50976&lng=-0.145276&radius=300&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/stores/search/?lat=51.50976&lng=-0.145276&radius=300&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/stores/search/?lat=51.50976&lng=-0.145276&radius=300&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 Search API returns a [GeoJSON](https://geojson.org/) `FeatureCollection`. Each feature represents a matching asset with its location geometry and properties. When geographic filtering is applied, results are sorted by distance and include a `distance` property. For the complete store data model, see the [Data Structure](/products/stores-api/features/data-management/) reference. ### Key Response Fields **`type`** - Always `"FeatureCollection"` at the top level. **`features`** - Array of GeoJSON `Feature` objects, each representing a matched asset. **`properties.store_id`** - Unique identifier for the asset. **`properties.name`** - Display name of the asset. **`properties.distance`** - Distance in meters from the search center to the asset. Only present when geographic parameters are used. **`properties.address`** - Structured address with `lines`, `city`, `zipcode`, and `country_code`. **`properties.contact`** - Contact information including `phone` and `website` when available. **`properties.tags`** - Array of tags associated with the asset. **`properties.types`** - Array of type classifications for the asset. **`properties.user_properties`** - Custom key-value data stored with the asset. **`properties.open`** - Current opening status, including `open_now`, today’s hours, and the current time slice. **`geometry`** - GeoJSON Point with the asset’s `[longitude, latitude]` coordinates. **`pagination`** - Contains `page` (current page number) and `pageCount` (total number of pages). ## Response Examples For this query the Search API will return the following content: ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "store_id": "2354", "name": "Berkeley Street/Berkeley Square", "contact": { "phone": "02076295779", "website": "https://www.starbucks.com/store-locator/store/2354/berkeley-street-berkeley-square-27-berkeley-st-berkeley-square-london-eng-w-1-x-5-", }, "address": { "lines": ["27 Berkeley St", "London, ENG W1X 5AD"], "country_code": "GB", "city": "London", "zipcode": "W1X 5AD", }, "user_properties": { "take_away": "available" }, "tags": ["WA", "WF", "CD", "DR", "XO"], "types": ["Coffee shop"], "last_updated": "2022-11-10T13:23:53.564829+00:00", "distance": 135.28682936, "open": { "open_now": true, "open_hours": [{ "end": "18:00", "start": "06:30" }], "week_day": 2, "current_slice": { "end": "18:00", "start": "06:30" }, }, "weekly_opening": { "1": { "hours": [{ "end": "18:00", "start": "06:30" }], "isSpecial": false, }, "2": { "hours": [{ "end": "18:00", "start": "06:30" }], "isSpecial": false, }, "3": { "hours": [{ "end": "18:00", "start": "06:30" }], "isSpecial": false, }, "4": { "hours": [{ "end": "18:00", "start": "06:30" }], "isSpecial": false, }, "5": { "hours": [{ "end": "18:00", "start": "06:30" }], "isSpecial": false, }, "6": { "hours": [{ "end": "17:00", "start": "08:00" }], "isSpecial": false, }, "7": { "hours": [{ "end": "17:00", "start": "08:00" }], "isSpecial": false, }, "timezone": "Europe/London", }, "opening_hours": { "usual": { "1": [{ "end": "18:00", "start": "06:30" }], "2": [{ "end": "18:00", "start": "06:30" }], "3": [{ "end": "18:00", "start": "06:30" }], "4": [{ "end": "18:00", "start": "06:30" }], "5": [{ "end": "18:00", "start": "06:30" }], "6": [{ "end": "17:00", "start": "08:00" }], "7": [{ "end": "17:00", "start": "08:00" }], }, "special": {}, "timezone": "Europe/London", }, }, "geometry": { "type": "Point", "coordinates": [-0.14408, 51.5088] }, }, ], "pagination": { "page": 1, "pageCount": 1 }, } ``` ## Troubleshooting | Issue | Common Cause | Solution | | --- | --- | --- | | No results returned | Query syntax error | Check clause structure: `field:operatorvalue` with proper quoting | | Unexpected empty results | Mismatched field name | Verify field names match your store data (e.g., `user.*` prefix) | | Query returns all stores | Missing or malformed operator | Ensure operator immediately follows `:` with no spaces | | Boolean filtering not working | Using `true`/`false` as strings | Use `#t` or `#f` for boolean values in user properties | | Date filtering not working | Unquoted datetime value | Wrap ISO8601 datetime in quotes: `last_updated:>="2023-06-02T09:57:55.264631"` | | Empty results with nearby assets | `radius` too small or lat/lng swapped | Verify `radius` is in meters and coordinates are correct | | `400 Bad Request` | Missing `radius` parameter | `radius` is required with `lat`/`lng` or `encoded_polyline` | | Unexpected assets with zone search | Zone polygon intersects search area | Expected behavior: zone search returns assets whose zone contains the point | | Results not sorted by distance | No geographic parameters | Distance sorting only applies when `lat`/`lng`/`radius` are included | | API key error | Wrong key type or restrictions | Check key type (public vs private) and referer settings | ## Usage Limits & Quotas - **Rate Limit** : 25 queries per second (QPS) per project (combined client-side and server-side queries) - Exceeding limits returns `429 Too Many Requests` - Contact support for higher quotas ## Working Code Examples ### Example: Stores API with Query and Geographic Filtering See the complete [Stores API JS Sample](/js-samples/stores-search/) for implementation details. https://demo.woosmap.com/js-samples/samples/stores-search/app/dist/ [](https://demo.woosmap.com/js-samples/samples/stores-search/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/stores-search/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/stores-search/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/stores-search) For multi-language code examples (cURL, JavaScript, Node.js, Python, Java, Ruby), see the [API Reference](/api-reference/search-api/get-stores-search/). ### Bounds Endpoint The Search API also provides a bounds endpoint that returns the geographic bounding box for assets matching your query. This is useful for automatically zooming a map to fit search results. ```shell curl "https://api.woosmap.com/stores/search/bounds?lat=51.509&lng=-0.145&radius=5000&key=YOUR_KEY" ``` The response contains `west`, `south`, `east`, and `north` coordinates. See the [API Reference](/api-reference/search-api/get-stores-search-bounds/) for details. ## Related Features - [Autocomplete](/products/stores-api/features/autocomplete/) - Full-text search on asset names with type-ahead suggestions - [Data Management](/products/stores-api/features/data-management/) - Import, update, and manage store data - [Zones](/products/stores-api/features/zones/) - Define and query geographic zones - [Polyline Encoding](/products/map-api/concepts/polyline-encoding/) - Encode route paths for polyline-based search - [Tuning Search Results](/products/stores-api/guides/tuning-search-results/) - Optimize search relevance and parameters - [Integration Path](/products/stores-api/guides/integration-path/) - Choose the right integration approach - [Making Your First Request](/products/stores-api/tutorials/making-first-request/) - Step-by-step getting started guide