Search

Search and filter your store assets using attribute queries and geographic filters.

Complete API Specification: Search Endpoint Reference

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 is for. For managing your asset data (import, update, delete), use Data Management.

New to the API? Start with the Making Your First Request tutorial for a step-by-step introduction. For parameter optimization, see 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.

Shell
        # Client-side (Referer header is sent automatically by browsers)
?query=type:"grocery"&key=YOUR_PUBLIC_KEY

# Server-side
?lat=48.856&lng=2.352&radius=5000&private_key=YOUR_PRIVATE_KEY

For complete authentication details and security best practices, see API Keys Documentation.

Request Parameters Overview

Required Parameters

key or private_key - Your API authentication key. See 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 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 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 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 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 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.

The query parameter value must be URL-encoded. 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.

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"

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.

Sample Search call
        https://api.woosmap.com/stores/search/
  ?lat=51.50976
  &lng=-0.145276
  &radius=300
  &key=YOUR_PUBLIC_API_KEY
    
        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'

    
        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));

    
        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);
});


    
        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)


    
        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();

    
        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 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 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:

Sample Search response
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 for implementation details.

For multi-language code examples (cURL, JavaScript, Node.js, Python, Java, Ruby), see the API Reference.

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 for details.

‹ Get Started Autocomplete Search ›
Was this helpful?