Source: https://developers.woosmap.com/products/stores-api/concepts/query-syntax/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Query Syntax ## Overview The Stores API uses a structured query language to filter your assets. Queries are passed via the `query` parameter on the [Search](/products/stores-api/features/search/) and [Autocomplete](/products/stores-api/features/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 {#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](/products/stores-api/features/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) 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: ```json { "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`: ```bash 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"): ```bash 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"): ```bash 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`: ```bash 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`: ```bash 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`: ```bash 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: ```bash 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`: ```bash 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): ```bash curl "https://api.woosmap.com/stores/autocomplete/?query=localized%3A%22street%22%20AND%20type%3A%22restaurant%22&language=en&key=YOUR_KEY" ```