_search¶

Search for receipts.

Query parameters:

Name	Type	Description
`pretty`	boolean, optional, default: false	readable output formatting
`consumer`	string vector, optional, min: 1, max: 5	one or more consumer identifiers
`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

Depending on the settings of the API key used to access this resource, consumer can be a required query parameter. When the consumer query parameter is used, the following fields cannot be used in search queries, and will result in an error:

identifier
identifier.exact

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, range value or the symbol: *, 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

It is possible to check for the existence of a field by using the special value *:

path.to.field:*

as well as check that a field does not exist:

-path.to.field:*

should you need to search for the * symbol, it can be quoted:

path.to.field:"*"

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.
`items.return:*`	receipts with returns
`-items.return:*`	receipts without returns
`dynamic.receipt_type:RETURN`	dynamic properties are configured per-retailer, in this case it selects receipts which are either RETURN 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, integer range or exists
`items.quantity.decimal`	float match or range
`items.unit`	exact match or exists
`items.total`	float match or range
`items.discounts`	exists
`items.discounts.name`	partial match
`items.discounts.quantity`	integer match, integer range or exists
`items.discounts.amount`	float match or range
`items.discounts_length`	integer match or range
`items.discounts_quantity`	integer match or range
`items.return`	exists
`items.return.localtime`	date match or range
`items.return.reason`	partial match or exists
`items.properties`	exists
`items.properties.details`	partial match or exists
`items.properties.product_code`	exact match or exists
`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`	exists
`discounts.name`	partial match
`discounts.quantity`	integer match or integer range or exists
`discounts.amount`	float match or range
`discounts_length`	integer match or range
`discounts_quantity`	integer match or range
`payments`	exists
`payments.change`	float match, float range or exists
`payments.number`	exact match or exists
`payments.method`	exact match or exists
`payments.issue`	exact match or exists
`payments.start`	exact match or exists
`payments.end`	exact match or exists
`payments.po_number`	exact match or exists
`payments_length`	integer match or range
`store_id`	integer match or range
`store_reference`	integer match or range
`external_store_reference`	exact match
`properties`	exists
`properties.email`	prefix match or exists
`properties.email.exact`	exact match
`properties.operator`	exact match or exists
`properties.salesperson`	partial match or exists
`identifier`	prefix match or exists
`identifier.exact`	exact match
`pos_data_ids`	exact match or exists
`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 contains “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. Exists fields support checking if the field is set.

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
}

Invalid Query¶

Example request:

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

Example response:

HTTP/1.1 400 Bad Request
Connection: keep-alive
Content-Type: application/json
Transfer-Encoding: chunked

{
    "description": "invalid query: itemssss.name is not a valid field",
    "status": "bad request"
}