How To Tune Stores API Results

How Stores API parameters shape your search results. Use query filters, geographic parameters, and pagination to go from broad to precise queries.

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 and Query Syntax Reference. If you’re using the Map JS API, check out the JS API Store Query Guide.

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.

Broad search: all stores within 5 km of central Paris
Shell
        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.

Relevant search: only grocery stores
Shell
        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.

Stores tagged "drive-through
Shell
        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 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.

Shell
        # 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.

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.

15 results per page, get page 2
Shell
        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.

All stores within 3 km
Shell
        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.

Stores within 500 m of a driving route
Shell
        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 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.

Which store serves this address?
Shell
        curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=1000&zone=true&key=YOUR_KEY"

See 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.
  • 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.

‹ Integration Path Query Syntax ›
Was this helpful?