Authentication

To make an API request you'll need an API key. One has already been generated for you on the accounts page. Once you have an API key you need to pass the key in the Authorization header when making a request like below:

curl https://shelfsignal.com/api/products/3830410 \
--header "Authorization: Bearer <YOUR_API_KEY_HERE>" 

All requests use one API credit, to get more, see pricing

Products by SKU

To get a product by it's SKU (Stock Keeping Unit) you can use the /sellers/{seller}/products/{sku} endpoint. Because we hold product information from multiple sellers, GTINs do not uniquely identify product entries in ShelfSignal's API.

Request:

curl https://shelfsignal.com/api/sellers/asda/products/1000383170401 \
--header "Authorization: Bearer <YOUR_API_KEY_HERE>"

Response:

{
    "credits_allocated": 100,
    "credits_used": 1,
    "data": [
        {
            "availability": "https://schema.org/InStock",
            "brand": "Country Style",
            "description": "",
            "gtin": 7675593,
            "image": "https://ui.assets-asda.com:443/dm/5017221360566",
            "name": "Country Style 5 Fresh Cream Doughnuts",
            "price": 1.4,
            "rating": 3.37,
            "review_count": 27,
            "seller": "asda",
            "sku": 1000383170401,
            "url": "https://groceries.asda.com/product/cookies-donuts-scones/country-style-5-fresh-cream-doughnuts/1000383170401"
        }
  ]
}

Products by Search

Using the /search-products you can search for products with the following query parameters:

  • gtin show results matching the specified GTIN (Global Trade Item Number)
  • name show results which contain the specified string in their name
  • seller show only results from the seller specified, for a full list of sellers see the list of supported sellers
  • brand show only results from the specified brand
  • sort sort results by one of name, rating, price, review_count, seller (defaults to name)

Request:

curl https://shelfsignal.com/api/search-products?name=pasta \
--header "Authorization: Bearer <YOUR_API_KEY_HERE>"

Response:

{
    "credits_allocated": 100,
    "credits_used": 21,
    "data": [
        {
        "availability": "https://schema.org/InStock",
        "brand": "ASDA",
        "description": "",
        "gtin": 7701010,
        "image": "https://ui.assets-asda.com:443/dm/5063089221693",
        "name": "ASDA BBQ Chicken Pasta 250g",
        "price": 2.5,
        "rating": null,
        "review_count": 0,
        "seller": "asda",
        "sku": 1000383175759,
        "url": "https://groceries.asda.com/product/lunch-ideas/asda-bbq-chicken-pasta-250-g/1000383175759"
        },
        {
        "availability": "https://schema.org/InStock",
        "brand": "ASDA",
        "description": "",
        "gtin": 6698182,
        "image": "https://ui.assets-asda.com:443/dm/5057172341122",
        "name": "ASDA BBQ Chicken Pasta Salad",
        "price": 3.2,
        "rating": 3.68,
        "review_count": 25,
        "seller": "asda",
        "sku": 1000212268757,
        "url": "https://groceries.asda.com/product/prepared-side-salads/asda-bbq-chicken-pasta-salad/1000212268757"
        },
        ...
    ]
}

List Reviews

To list reviews for a given product you can use the /sellers/{seller}/products/{sku}/reviews endpoint. Because we hold product information from multiple sellers, GTINs do not uniquely identify product entries in ShelfSignal's API.

Request:

curl https://shelfsignal.com/api/sellers/sainsburys/products/7937017/reviews \
--header "Authorization: Bearer <YOUR_API_KEY_HERE>"

Response:

{
  "credits_allocated": 20000,
  "credits_used": 42,
  "data": [
    {
      "author": "Elleysan",
      "created_at": "2024-07-23",
      "description": "Usually enjoy Kombucha, tried this brand for the first time and wished I hadn't!\nAwful strong taste and smell of vinegar, could just about taste a slight cheap cola flavour, so went down the drain",
      "gtin": null,
      "rating": 1.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "If you love the taste of vinagar..."
    },
    {
      "author": "Slurperer",
      "created_at": "2023-11-02",
      "description": "First time I’ve bought one was looking forward to it as an alternative cola but poured into glass and had loads of chunks of something floating about. Ever the optimist took tiny sip just to see what the flavour was like and Vinegar!! Won’t rush to try again. Only bought 1 bottle so maybe just bad luck.",
      "gtin": null,
      "rating": 1.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "Tastes like vinegar"
    },
    {
      "author": "Sukotto",
      "created_at": "2023-10-22",
      "description": "I made an account just for this review.\n\nTasted like straight up vinegar. No cola flavour, went straight down the sink.",
      "gtin": null,
      "rating": 1.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "Up there with the worst drinks I've ever tasted"
    },
    {
      "author": "Catty_",
      "created_at": "2023-08-15",
      "description": "Bought yesterday.  Took two sips, first one astonished at how bad it tasted, second to confirm.  Tipped the rest down the sink.\nSmells and tastes like something you'd clean the drains with.",
      "gtin": null,
      "rating": 1.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "Absolutely filthy"
    },
    {
      "author": "Dan80",
      "created_at": "2023-06-08",
      "description": "I love traditional Colas but they're often syrupy and high in sugar so I was excited to see this! I added one of each flavour of this kombucha to a recent shop and this one was a stand out favourite for me. Delicious ice cold from the fridge. I've just noticed that they're also helping clean up our oceans too so it's a win-win!",
      "gtin": null,
      "rating": 5.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "Lovely traditional Cola taste"
    },
    {
      "author": "newington",
      "created_at": "2023-04-10",
      "description": "Hard to beat coke and pepsi at the cola game but wanted to try this as it's a healthier alternative and it was great. It's obviously a bit pricier but worth it for something a bit different on special occasions",
      "gtin": null,
      "rating": 5.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "Solid replacement for the usual suspects"
    },
    {
      "author": "matilda",
      "created_at": "2022-05-25",
      "description": "Best tasting Kombucha",
      "gtin": null,
      "rating": 5.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "fantastic tasting"
    },
    {
      "author": "John3",
      "created_at": "2020-11-02",
      "description": "Bought 3 bottles, which cost £6 and each one of them had to be thrown out due to a strange metallic taste. Have had them before and they were lovely, but all three had same metallic taste, so won’t be buying anymore.",
      "gtin": null,
      "rating": 1.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "Strange metallic taste"
    },
    {
      "author": "Amy",
      "created_at": "2020-01-23",
      "description": "Great taste and reasonably priced. It is less sour than drinks of same brand but different flavor. It reminds cola taste very slightly, I like it tho.",
      "gtin": null,
      "rating": 5.0,
      "seller": "sainsburys",
      "sku": 7937017,
      "title": "Great taste"
    }
  ],
  "status": "success"
}

Supported Sellers

We have product and review data for the following sellers:

  • tesco
  • sainsburys
  • asda
  • lidl
  • aldi

And limited data for:

  • kroger
  • walmart