GET /receipts/_search

Search for receipts.

Name	Type	Description
pretty	boolean, optional, default: false	readable output formatting
count	integer, optional, min: 1, max: 20, default: 20	number of returned results
offset	integer, optional, max: 1000, default: 0	number of initial results that should be skipped
query	string, required	search query

Queries

Search language

A “mini-language” is used to perform searches for receipts and identifiers. A query consists of one or more fields, separated by spaces. A field contains a path, and a match value or range value, separated by a colon. The available paths are defined by the type of record that is being searched for, and can be found below in section on “Search fields”. Paths follow the structure of the record being searched and may contain dots to separate parts of the path. Simple match queries would look as follows:

path.to.number:2

text_path:SearchTerm

path.to.date:2024-10-12

which could be combined into one query using spaces:

path.to.number:2 path:SearchTerm path.to.date:2024-10-12

Range queries use square brackets and braces to indicate closed and open ranges respectively. These can be combined for half-open intervals. The word TO must appear between the two extremes of the range. The brackets and braces are used as follows:

At the start of a range

• [    greater than or equal to (>=)

• {    greater than (>)

At the end of a range

• ]    less than or equal to (<=)

• }    less than (<)

Range queries for numbers and dates can be expresses like this:

path.to.number:[2 TO 6]

path.to.number:{-0.5 TO 0.5]

path.to.date:[2024-10-12 TO 2024-10-16}

when searching text fields, search terms containing spaces can be used by surrounding the search term in quotes, this query all records where the field contains the entire phrase:

text_path:"a multi word phrase"

it is also possible to search for multiple words for one field, where the field must then contain one or more of the words:

text_path:(this that)

for some fields it is possible to search for words that are like the specified word, which might be useful to search for records while ignoring pluralisation or alternative spelling or word endings:

text_path:things~

it is also possible to require, using + or exclude a certain word, using - in a text field:

text_path:(-exclude)

text_path:(+require)

text_path:(+require -exclude)

and excluding or requiring certain search terms can also happen at the field level:

+path.to.number:2

-text_path:SearchTerm

When queries are submitted as a querystring argument to the API, they must be URL encoded.

Example receipt searches

Query	Description
external_store_reference:Store.123	receipts from store with a store reference “Store.123”
items.name:carrots~	first name must contain a term similar to “carrots”
items.name:carrots	specific item names
items.name:"purple carrots"	item name must contain “purple carrots”
items.name:(purple carrots)	item name must contain “purple” or “carrots”
items.name:(+purple -carrots)	item name must contain “purple” and cannot contain “carrots”
total:[100 TO 200]	the total is between 100 and 200
timestamp:[2022 TO 2023}	receipts from 2022
timestamp:[2024-10-01 TO 2024-11-01}	receipts from October 2024.
dynamic.receipt_type:RETURN`	dynamic properties are configured per-retailer, in this case it selects receipts which are either RETURN receipts or SALE receipts.

Search fields

The following fields are available when searching receipts:

Field	Search type
transaction_id	partial match
timestamp	date match or range
items.name	partial match
items.quantity	integer match or range
items.quantity.decimal	float match or range
items.unit	exact match
items.total	float match or range
items.discounts.name	partial match
items.discounts.quantity	integer match or range
items.discounts.amount	float match or range
items.discounts_length	integer match or range
items.discounts_quantity	integer match or range
items.return.localtime	date match or range
items.return.reason	partial match
items.properties.details	partial match
items.properties.product_code	exact match
items.dynamic	per-retailer configured item properties can be searched under this key
items_length	integer match or range
total	float match or range
discounts.name	partial match
discounts.quantity	integer match or range
discounts.amount	float match or range
discounts_length	integer match or range
discounts_quantity	integer match or range
payments.change	float match or range
payments.number	exact match
payments.type	exact match
payments.issue	exact match
payments.start	exact match
payments.end	exact match
payments.po_number	exact match
payments_length	integer match or range
store_id	integer match or range
store_reference	integer match or range
external_store_reference	exact match
properties.email	prefix match
properties.email.exact	exact match
properties.operator	exact match
properties.salesperson	partial match
identifier	prefix match
identifier.exact	exact match
pos_data_ids	exact match
dynamic	per-retailer configured receipt properties can be searched under this key

Partial match fields support partial matching of the field contents. I.e. a search for “purple carrots” will match receipts where the field contained “purple carrots”, “british purple carrots””, or “purple carrots, 200g”. Prefix match fields support partial matching from the beginning of words. I.e. a search for “water” on a prefix match would also match receipts in which the field contains “water” or “watermelon”. For exact match fields a search for “water” would not match a receipt with a field that contained “watermelon”; only receipts with fields containing exactly the string “water” would be returned.

Examples

Search for an item with matching receipts

Example request:

GET /receipts/_search?query=items.name%3A%28british+milk%29 HTTP/1.1
Host: api.ereceipts.co.uk
Accept: application/json

Example response:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Transfer-Encoding: chunked

{
  "hits": 2,
  "receipts": [
    {
      "id": "513e2391ee5e525ff9000000",
      "identifier": null,
      "items": [
        {
          "discounts": [],
          "name": "British Semi Skimmed Milk 6 Pints",
          "properties": {},
          "quantity": 1,
          "total": 2.15
        }
      ],
      "localtime": "2013-11-27T14:57:00+01:00",
      "payments": [
        {
          "amount": 2.15,
          "method": "cash"
        }
      ],
      "pos_data_ids": [],
      "properties": {},
      "retailer": {
        "name": "Paperless Groceries"
      },
      "store": {
        "address": [
          "61 Hatton Garden"
        ],
        "city": "London",
        "country": "GBR",
        "name": "Paperless Groceries Clerkenwell",
        "phone": "+440000000000",
        "postcode": "EC1N 8LS",
        "properties": {}
      },
      "store_reference": "1",
      "timestamp": "2024-11-27T13:57:00+00:00",
      "total": 2.15,
      "transaction_id": "0011120008"
    },
    {
      "id": "513e2391ee5e525ff9000123",
      "identifier": null,
      "items": [
        {
          "discounts": [],
          "name": "British Full Fat Milk 6 Pints",
          "properties": {},
          "quantity": 2,
          "total": 4.6
        }
      ],
      "localtime": "2013-11-30T14:57:00+01:00",
      "payments": [
        {
          "amount": 4.6,
          "method": "cash"
        }
      ],
      "pos_data_ids": [],
      "properties": {},
      "retailer": {
        "name": "Paperless Groceries"
      },
      "store": {
        "address": [
          "52 Grosvenor Gardens"
        ],
        "city": "London",
        "country": "GBR",
        "name": "Paperless Groceries Victoria",
        "phone": "+440000000000",
        "postcode": "SW1W 0AU",
        "properties": {}
      },
      "store_reference": "3",
      "timestamp": "2024-11-30T13:57:00+00:00",
      "total": 4.6,
      "transaction_id": "0011120124"
    }
  ],
  "time": 25
}

Search for an item with no matching receipts

Example request:

GET /receipts/_search?query=items.name%3Acarrot HTTP/1.1
Host: api.ereceipts.co.uk
Accept: application/json

Example response:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Transfer-Encoding: chunked

{
  "hits": 0,
  "receipts": [],
  "time": 11
}