Query Syntax

How to build queries for the Stores API using fields, operators, and combinators to filter assets by type, tag, location, custom properties, and more.

Overview

The Stores API uses a structured query language to filter your assets. Queries are passed via the query parameter on the Search and Autocomplete endpoints. This page explains how to build queries from individual clauses, combine them with logical operators, and use them in API requests.

Query Structure

A query is made up of one or more clauses. Each clause has three parts:

Field - The store attribute to filter on (e.g., name, type, tag, user.rating).
Operator - The comparison to perform (e.g., =, >, <). Each field has a default operator; if no operator follows the :, the default is used.
Value - The content to match against (e.g., "My cool store", 5, "FR").

The general form of a clause is:

        field:operatorvalue

For example:

        type:"grocery"
name:="My cool store"
user.rating:>3

Searchable Fields

Field	Value Type	Operators	Default	Description
`type`	collection	none	contains	Match assets whose `type` array contains the value. e.g. `type:"myType"`
`tag`	collection	none	contains	Match assets whose `tag` array contains the value. e.g. `tag:"myTag"`
`city`	string	none or `=`	`=`	Exact match on the `city` field. e.g. `city:="Paris"`
`country`	string	none or `=`	`=`	Exact match on the `countryCode` field. e.g. `country:="FR"`
`name`	string	none or `=`	`=`	Exact match on the `name` field. e.g. `name:="myName"`
`idstore`	string	none or `=`	`=`	Exact match on the `idstore` field. e.g. `idstore:="myIdStore"`
`user.{ATTRIBUTE_NAME}`	string, numeric	none or `=`, `>`, `<`, `>=`, `<=`	`=`	Filter on any field inside `user_properties`. e.g. `user.myAttribute:="myValue"`
`last_updated`	string (datetime)	`>`, `<`, `>=`, `<=`	none	ISO 8601 datetime comparison. e.g. `last_updated:>="2023-06-02T09:57:55.264631"`
`localized`	string	none	contains	Full-text search on localized asset names. Autocomplete endpoint only. e.g. `localized:"street"`

Query field names differ from the data model field names used in request bodies and responses. type queries the types array, tag queries the tags array, country queries the countryCode/country_code field, and idstore queries the storeId/store_id field.

The user_properties field has no restriction on the data types you can store (arrays, objects, booleans, strings, numbers), but you can only query for text matching, numerical comparison, or boolean values.

The localized field is only available on the Autocomplete endpoint. All other fields work on both Search and Autocomplete endpoints.

Operators

Operator	Description
`:`	Default and mandatory separator between field and value. For `type` and `tag`, tests collection membership.
`=`	Exact equality for strings or numbers.
`>`	Greater than (numeric).
`<`	Less than (numeric).
`>=`	Greater than or equal to (numeric).
`<=`	Less than or equal to (numeric).
`#t`	Match assets with a `true` boolean value in `user_properties`.
`#f`	Match assets with a `false` boolean value in `user_properties`.

Combining Clauses

Use AND, OR, and NOT to combine multiple clauses. Parentheses group clauses for precedence.

Combinator	Description
`AND`	Match assets satisfying both clauses
`OR`	Match assets satisfying either clause
`NOT`	Negate a clause

Examples

Match assets that are either type1 or type2 and tagged hockey:

        (type:"type1" OR type:"type2") AND tag:"hockey"

Match all assets except those of type grocery:

        NOT type:"grocery"

Match assets in Paris with a rating above 4:

        city:="Paris" AND user.rating:>4

Legacy Shorthand Notation

You may see a shorter notation in older examples, SDK documentation, and the OpenAPI specification that uses | and & as clause prefixes:

        &name:"My store"|type:"grocery"

In this notation, | means OR and & means AND. The example above is equivalent to name:"My store" OR type:"grocery". Prefer the explicit AND/OR/NOT keywords for clarity.

URL Encoding

The query parameter value must be URL-encoded when passed in a request URL. Special characters like :, =, ", >, <, and spaces must be percent-encoded.

Character	Encoded
`:`	`%3A`
`=`	`%3D`
`"`	`%22`
`>`	`%3E`
`<`	`%3C`
space	`%20`

For example, the query type:"grocery" becomes:

        ?query=type%3A%22grocery%22

Tools like cURL and Postman handle URL encoding automatically when using the --data-urlencode flag or the Params tab respectively.

Query Examples

The examples below reference this sample data:

        {
  "stores": [
    {
      "store_id": "first",
      "name": "My cool store",
      "tags": ["grocery", "apple"],
      "user_properties": {
        "rating": 3,
        "seats": 345
      }
    },
    {
      "store_id": "second",
      "name": "My Second Store",
      "tags": ["lightsaber", "samsung"],
      "user_properties": {
        "rating": 5
      }
    }
  ]
}

Filter by Collection Field

Match assets tagged grocery:

        curl "https://api.woosmap.com/stores/search/?query=tag%3A%22grocery%22&private_key=YOUR_PRIVATE_KEY"

Filter by User Property

Match assets with rating greater than 3 (returns “My Second Store”):

        curl "https://api.woosmap.com/stores/search/?query=user.rating%3A%3E3&private_key=YOUR_PRIVATE_KEY"

Match assets with rating equal to 5 (returns “My Second Store”):

        curl "https://api.woosmap.com/stores/search/?query=user.rating%3A5&private_key=YOUR_PRIVATE_KEY"

Combine Multiple Conditions

Match assets where idstore is “My cool store” and seats equals 345:

        curl "https://api.woosmap.com/stores/search/?query=idstore%3A%3D%22My%20cool%20store%22%20AND%20user.seats%3A345&private_key=YOUR_PRIVATE_KEY"

Match assets where idstore is “My cool store” and seats is greater than 300:

        curl "https://api.woosmap.com/stores/search/?query=idstore%3A%3D%22My%20cool%20store%22%20AND%20user.seats%3A%3E300&private_key=YOUR_PRIVATE_KEY"

Negate a Clause

Match all assets except those of type grocery:

        curl "https://api.woosmap.com/stores/search/?query=NOT%20type%3A%22grocery%22&private_key=YOUR_PRIVATE_KEY"

Filter by Last Updated Date

Match assets updated after a specific date:

        curl "https://api.woosmap.com/stores/search/?query=last_updated%3A%3E%3D%222023-06-02T09%3A57%3A55.264631%22&private_key=YOUR_PRIVATE_KEY"

Boolean Properties

Match assets where a boolean user property is true:

        curl "https://api.woosmap.com/stores/search/?query=user.is_open%3A%23t&private_key=YOUR_PRIVATE_KEY"

Autocomplete with Query Filters

Search for assets with names matching “street” that are of type “restaurant” (Autocomplete endpoint):

        curl "https://api.woosmap.com/stores/autocomplete/?query=localized%3A%22street%22%20AND%20type%3A%22restaurant%22&language=en&key=YOUR_KEY"

‹ Tuning Your Search Results Opening Hours ›