Searching in the V2 API

Searching in the Whiplash API is very powerful, and pretty simple once you master a few things.

You can search pretty much any attribute available via the API, like order["shipping_city"], item["sku"], or order_item["quantity"].

You combine the attribute with one of the predicates below to create filters like "shipping_city_matches", "sku_start", or "quantity_gt".

You can search a resource's associations. For instance, an order has order_items. So, you can search an order using "order_items_sku_start".

Here is an example of each search predicate in action:

eq (equals)

The eq predicate returns all records where a field is exactly equal to a given value:

GET /api/v2/orders?search={"email_eq": "customer@gmail.com"}

Opposite: not_eq

matches

The matches predicate returns all records where a field is like a given value:

GET /api/v2/orders?search={"shipping_city_matches": "ANN arbor"}

Opposite: does_not_match

Note: If you want to do wildcard matching, you may be looking for the cont/not_contpredicates instead.

lt (less than)

The lt predicate returns all records where a field is less than a given value:

GET /api/v2/orders?search={"status_lt": 300}

Opposite: gteq (greater than or equal to)

lteq (less than or equal to)

The lteq predicate returns all records where a field is less than or equal to a given value:

GET /api/v2/orders?search={"shipped_on_lteq": '2017-11-25 00:00:00'}

Opposite: gt (greater than)

in

The in predicate returns all records where a field is within a specified list:

GET /api/v2/orders?search={"status_in": [300, 350]}

Opposite: not_in

cont

The cont predicate returns all records where a field contains a given value:

GET /api/v2/items?search={"title_cont": "shirt"}

Opposite: not_cont

cont_any (contains any)

The cont_any predicate returns all records where a field contains any of the given values:

GET /api/v2/orders?search={"order_items_description_cont_any": ["CD", "LP", "Cassette"]}

Opposite: not_cont_any

cont_all (contains all)

The cont_all predicate returns all records where a field contains all of the given values:

GET /api/v2/orders?search={"order_items_description_cont_all": ["LP", "Deluxe"]}

Opposite: not_cont_all

start (starts with)

The start predicate returns all records where a field begins with a given value:

GET /api/v2/items?search={"sku_start": "SKU-XX"}

Opposite: not_start

end (ends with)

The end predicate returns all records where a field ends with a given value:

GET /api/v2/items?search={"sku_end": "-SM"}

Opposite: not_end

true

The true predicate returns all records where a field is true. The '1' indicates that you indeed want to check the truthiness of this field. The other truthy values are 'true', 'TRUE', 't' or 'T'.

GET /api/v2/items?search={"promo_true": "true"}

Opposite: not_true

false

The false predicate returns all records where a field is false.

GET /api/v2/items?search={"packaging_false": "true"}

Opposite: not_false

Note: the false predicate may be considered the opposite of the true predicate if the field does not contain null values. Otherwise, use not_false.

present

The present predicate returns all records where a field is present (not null and not a blank string).

GET /api/v2/shipnotices?search={"tracking_present": "true"}

Opposite: blank

null

The null predicate returns all records where a field is null:

GET /api/v2/orders?search={"public_notes_null": "true"}

Opposite: not_null