Usage Guide

This section goes over how to use the External Item Search service.

Endpoints

The service is fairly simple, and only has a few endpoints available.

These endpoints are documented at the running service’s swagger endpoint at /q/swagger-ui/

Get Search Methods

GET /api/v1/info/methods

This endpoint gathers what search methods are currently available to use for searching. It also lists what services are available to do those searches.

Example return data:

{
        "BARCODE": [
                "BARCODE_LOOKUP",
                "DATAKICK",
                "UPC_ITEM_DB",
                "OPENFOODFACTS"
        ],
        "TEXT": [
                "BARCODE_LOOKUP",
                "REBRICKABLE",
                "OPENFOODFACTS"
        ],
        "PART_NUM": [
                "REBRICKABLE"
        ],
        "SET_NUM": [
                "REBRICKABLE"
        ]
}

Get Search Providers

GET /api/v1/info/providers

This endpoint gathers what providers (downstream services) we have available.

Example return data:

[
        {
                "id": "BARCODE_LOOKUP",
                "displayName": "BarcodeLookup.com",
                "description": "Comprehensive database of products, but a paid service. Can get a 2-week trial API key.",
                "cost": "Paid",
                "acceptsContributions": true,
                "homepage": "https://www.barcodelookup.com/",
                "enabled": true,
                "lookupMethods": [
                        "BARCODE",
                        "TEXT"
                ],
                "lookupSources": [
                        "BARCODE_LOOKUP"
                ]
        },
        //...
]

Search External Items

GET /api/v1/search

This endpoint gathers what providers (downstream services) we have available.

Example return data:

[
        { // successful responses will return with a "SUCCESS" type
                "service": "DATAKICK",
                "source": "DATAKICK",
                "method": "BARCODE",
                "name": "-  Blackberry peach",
                "unifiedName": "-  Blackberry peach",
                "description": "",
                "prices": {},
                "identifiers": {},
                "attributes": {
                        "gtin14": "00888109010058",
                        "size": "30ML",
                        "ingredients": "s"
                },
                "images": [],
                "links": {},
                "type": "SUCCESS"
        },
        { // services with no results will return with a "NO_RESULTS" type (omitted by default)
                "service": "UPC_ITEM_DB",
                "source": "UPC_ITEM_DB",
                "method": "BARCODE",
                "detail": "No results found.",
                "type": "NO_RESULTS"
        },
        { // services that otherwise failed to be called will return with a "ERROR" type
                "service": "OPENFOODFACTS",
                "source": "OPENFOODFACTS",
                "method": "BARCODE",
                "detail": "Failed to connect.",
                "type": "ERROR"
        },
        //...
]

Searching Specifics

Searches take the following important GET parameters:

Search Query

q (String)

This is the main search query. Required.

Lookup Method

lookupMethod

One of the methods returned from the get methods endpoints, i.e, TEXT or BARCODE

This is how to specify the method to use for search. Can specify multiple times to specify multiple methods.

Omit to default to TEXT.