Source: https://developers.woosmap.com/products/stores-api/guides/tuning-search-results/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# How To Tune Stores API Results



This guide walks you through common scenarios for refining Stores API search results, from a broad "everything nearby"
query to precisely filtered results.

For full API details, see the [Search Reference](/products/stores-api/features/search/)
and [Query Syntax Reference](/products/stores-api/concepts/query-syntax/). If you're using the Map JS API, check out
the [JS API Store Query Guide](/products/js-api/guides/query-stores/).

## The Default Search

A Stores API request with only geographic parameters returns all assets near a point, sorted by distance.
This is the baseline, every example below builds on it.

```bash
curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=5000&key=YOUR_KEY"
```

## Show Only Relevant Store Types

If your dataset contains multiple store types (grocery, bakery, pharmacy…), you probably don't want to show them all at
once.

```bash
curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=5000&query=type%3A%22grocery%22&key=YOUR_KEY"
```

For more fine-grained distinctions, use `tag` instead. For example, `tag:"drive-through"` filters on the asset's `tags`
array rather than its `types`.

```bash
curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=5000&query=tag%3A%22drive-through%22&key=YOUR_KEY"
```

See [Query Syntax — Fields](/products/stores-api/concepts/query-syntax/#fields) for the full list of filterable fields.

## Combine Multiple Filters

You can mix geography, city/country, and custom attributes in a single `query`. Operators `AND`, `OR`, `NOT`, and
parentheses work as you'd expect.

```bash
# Grocery stores in France
curl "https://api.woosmap.com/stores/search/?query=type%3A%22grocery%22%20AND%20country%3A%3D%22FR%22&key=YOUR_KEY"

# Grocery stores with a rating above 4
curl "https://api.woosmap.com/stores/search/?query=type%3A%22grocery%22%20AND%20user.rating%3A%3E4&key=YOUR_KEY"

# Grocery OR bakery stores in France
curl "https://api.woosmap.com/stores/search/?query=(type%3A%22grocery%22%20OR%20type%3A%22bakery%22)%20AND%20country%3A%3D%22FR%22&key=YOUR_KEY"
```

Custom properties live under `user.*` — so a property called `rating` becomes `user.rating` in queries.

One thing to keep in mind: geographic parameters (`lat`/`lng`/`radius`) and the `query` parameter are independent.
An asset must satisfy **both** to appear in results.

For the full combining syntax, see
[Query Syntax — Combining Clauses](/products/stores-api/concepts/query-syntax/#combining-clauses).

## Paginate Large Result Sets

When your query returns hundreds of stores but you only show 15 at a time, use `stores_by_page` and `page`.

```bash
curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=5000&stores_by_page=15&page=2&key=YOUR_KEY"
```

For store locator UIs, 10–20 results per page works well. The response includes `pagination.pageCount` so you know the total number of pages available.

## Control the Search Area

### Search Near a Point

This is the most common pattern for store locators. Adjust `radius` (in meters) to match how dense your coverage is.

```bash
curl "https://api.woosmap.com/stores/search/?lat=43.3&lng=3.883&radius=3000&key=YOUR_KEY"
```

**Choosing the right radius:**

| Use Case                   | Suggested Starting Radius |
| -------------------------- | ------------------------- |
| Dense urban areas          | 1,000–3,000 m             |
| Suburban areas             | 5,000–10,000 m            |
| Rural or sparse coverage   | 20,000–50,000 m           |
| Nationwide with few stores | 100,000+ m                |

All three parameters — `lat`, `lng`, and `radius` — are required together.

### Search Along a Route

Show stores along a driving route by passing an encoded polyline instead of a single point.

```bash
curl "https://api.woosmap.com/stores/search/?encoded_polyline=owdiHcpiM%3FAA%3FOK%3F%3FA%40A%40Ot%40ERHDDBt%40%5EFBNFVLx%40%5EB%40B%40DDFDENCHADKd%40Ih%40Q%60AgAnGMh%40Ol%40Qd%40i%40tA%5D%7C%40CFs%40fBIPwBnDIPHPjAhA%5C%5CZHHFDh%40d%40FDNNDBFFXNtBp%40FBAHA%60%40MpCCP&radius=500&key=YOUR_KEY"
```

See [Polyline Encoding](/products/map-api/concepts/polyline-encoding/) for how to generate encoded polylines.

### Check Service Coverage

Need to know which store's delivery zone covers an address? Use `zone=true` to switch from proximity matching to polygon containment.

```bash
curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=1000&zone=true&key=YOUR_KEY"
```

See [Zones](/products/stores-api/features/zones/) for details on setting up zone polygons.

## Common Mistakes

- **Over-filtering**: Combining strict attribute filters with a small radius often returns nothing. Start broad, then add filters one at a time.
- **Missing radius**: Forgetting `radius` when using `lat`/`lng` or `encoded_polyline` returns a `400 Bad Request`.
- **Unencoded queries**: Special characters in the `query` parameter must be URL-encoded. See [URL Encoding](/products/stores-api/concepts/query-syntax/#url-encoding).
- **Wrong field prefix**: Custom properties require the `user.` prefix (e.g., `user.rating`, not `rating`).
- **Boolean syntax**: Use `#t` and `#f` for boolean values in `user_properties`, not `true` or `false`.
- **Geographic + query interaction**: These are independent filters — both must match. A `query` for `country:="FR"` combined with `lat`/`lng` in Berlin will return nothing, even if you have French stores.

For integration options and setup, see the [Integration Path Guide](/products/stores-api/guides/integration-path/).