Introduction

The Squirrel API brings all the functionality from squirrel to an REST API.

We allow users to search for a single product code ( ASIN, UPC, EAN or SKU) and the API will retrieve the matched product(s) around the globe ( over 10 countries ).

Knowing the product codes, or the product ID within the API, the user will easily access all the retailer’s offers, with the ability to have their own reseller id to get commission-worthy links.

The response from the API will provide the product details, such as recommended retail price, live price, product image and product description in various counties.

This all runs from the Squirrel portal, allowing you to enter your affiliate network details and select the retailers you wish to work with.

Squirrel API also allow you to search for the product name, retailer URL or even by Make & Model.

Authentication

Squirrel API uses a Bearer token to allow access to the API. You can send your auth token like this:

Authorization: Bearer [YOUR_ACCESS_TOKEN]

To get your Bearer token you need to login to your Squirrel account and navigate to API info

Server Info

API endpoint: https://api.getsquirrel.co/api/v2
Limits: - Requests are limited to 1 Request per second - On a single product search request, 10 product codes can be sent

Products

Search by Code

  curl --location --request POST 'https://api.getsquirrel.co/api/v2/products/search' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--form 'code="B07ZPC9QD4"'

The above command returns JSON structured like this:

[
  {
    "data": {
      "B07ZPC9QD4": [
        {
          "name": "Apple AirPods Pro",
          "squirrel_id": 2686508,
          "price": 95,
          "rrp": 249,
          "offer_url": "https://www.ebay.co.uk/itm/284378464855?hash=item4236470257%3Ag%3AaNYAAOSwFv1g9uOB&mkevt=1&mkcid=1&mkrid=710-53481-19255-0&campid=5338111205&customid=bestsquirreldeals&toolid=10049",
          "retailer": {
            "id": 14,
            "name": "eBay UK",
            "logo_url": "https://squirrels.getsquirrel.co/assets/images/retailers/ebayuk-compressor.png"
          },
          "image": "https://squirrels.getsquirrel.co/assets/images/products/149650-apple-airpods-pro.5,0",
          "last_updated": null,
          "last_updated_timestamp": null,
          "all_offers": [
            {
              "id": 47647714,
              "price": 95,
              "offer_url": "https://www.ebay.co.uk/itm/284378464855?hash=item4236470257%3Ag%3AaNYAAOSwFv1g9uOB&mkevt=1&mkcid=1&mkrid=710-53481-19255-0&campid=5338111205&customid=bestsquirreldeals&toolid=10049",
              "retailer": {
                "id": 14,
                "name": "eBay UK",
                "logo_url": "https://squirrels.getsquirrel.co/assets/images/retailers/ebayuk-compressor.png"
              }
            },
            {
              "id": 46018224,
              "price": 189.97,
              "offer_url": "https://track.webgains.com/click.html?wgcampaignid=206781&wgprogramid=272145&product=1&wglinkid=2775635&productname=Apple+AirPods+Pro+-+White+Active+Noise+Cancelling&wgtarget=https://www.laptopsdirect.co.uk/apple-airpods-pro-white-mwp22zm-a/version.asp&clickref=bestsquirreldeals",
              "retailer": {
                "id": 10839,
                "name": "Laptops Direct UK",
                "logo_url": "https://squirrels.getsquirrel.co/assets/images/retailers/laptopsdirect.png"
              }
            },
            {...}
          ],
          "top_offer": {
            "id": 47647714,
            "price": 95,
            "offer_url": "https://www.ebay.co.uk/itm/284378464855?hash=item4236470257%3Ag%3AaNYAAOSwFv1g9uOB&mkevt=1&mkcid=1&mkrid=710-53481-19255-0&campid=5338111205&customid=bestsquirreldeals&toolid=10049",
            "retailer": {
              "id": 14,
              "name": "eBay UK",
              "logo_url": "https://squirrels.getsquirrel.co/assets/images/retailers/ebayuk-compressor.png"
            }
          },
          "description": "Apple AirPods Pro MWP22 with Wireless Charging Case - White",
          "product_codes": {
            "ASIN": "B07ZPML7NP",
            "EAN": [
              "190199247000",
              "0190199247000",
              "00190199247000"
            ],
            "SKU": [
              "0190199247000"
            ],
            "UPC": [
              "190199246850",
              "0190199246850",
              "00190199246850"
            ],
            "MPN": [
              "MWP22ZM/A"
            ]
          },
          "country": "GB"
        }
      ]
    }
  }
]

Endpoint that allows to search for a product by code or URL

HTTP Request

POST https://api.getsquirrel.co/api/v2/products/search

Query Parameters

Parameter	Type	Description
squirrel_id	integer	An numerical value representing the Squirrel ID representing a product on our DB, this value can get access on a previous API response or on the Squirrel Dashboard.
code	string	Alphanumerical code to search the DB, can be EAN, UPC, SKU or ASIN ( when available ). To search for multiple products, send the codes separated by the symbol ' \| '.
urls	string	Well-formed URLs can be sent to retrieve products, it is mandatory that each URL starts with "http" or "https". To search for multiple products, send the urls separated by the symbol ' \| '.
country	string	ISO code of the country to filter the results. When empty, all existant countries will be returned. To send multiple countries, use comma separated values, ex.: "UK,US,AU"
show_with_offers_only	boolean	If you only want products with offers, send 'true'.
~~search_live_apis~~	boolean	deprecated Allow the API to search live our Partners APIs ( like Amazon ). This will make the response slower. By default, the API will not look into Partner's API in realtime, it will store the request on the DB and fetch products and offers offline.
cache_ttl	integer	Use this parameter to reduce the amount of seconds the result is cached on Squirrel's end. Sending '0' will force the cache to be refreshed. ( you'll get a response with a "check later" message )

Responses

Squirrel API always give a response in milliseconds, to make sure your client application doesn't hang waiting for a response. If the request is not new for Squirrel you'll get the cached version of the response. When the cache ttl ( default 120 minutes ) is hit, the response will be refreshed in the backend, and stored in the caching system to be ready for the next time you execute the same request.

For each request, and after it gets cached, you'll get the product information - for each requested product, and each country - with the following fields:

Generic information

Property	Description
monthly_quota	The total amount of requests you can make every 30 days
current_usage	The amount of requests made since the renewal of your subscription
error	True/ False value to indicate if the data object contains error information
data	Object with the Product Information ( see description below )
request_ids	Object that contains the ids ( an hash ) for each cached response, each code/ URL/ term will have one

Product Information

Property	Description
name	The product name for the country
squirrel_id	The unique ID for that product on your account. This is the same squirrel_id you can use on the widget to display this product in a webpage, or to use on "little squirrel"
price	The price of the product, in that country. This is the price for the Best offer.
rrp	The Recommended retail price - this is the price the manufacturer recommends as a retailer price.
offer_url	The monetizable URL to be used for the best offer for this product. It already has your tracking ids and your affiliate tracking ids for the selected retailer.
retailer	An Retailer object with the information about the retailer for the best offer ( see Retailer object description below )
image	Product image URL
all_offers	An array of Offers objects ( see Offer object description below ), this value can be empty when no offers match the requested product in the requested country
top_offer	The best selected Offer object ( see Offer object description below ), this value can be empty when no offers match the requested product in the requested country
no_affiliate_offers	This property contains all the offers we have for this product but you don't have the retailer activated. Check your Squirrel account to activate them.
description	The product description, this information is retrieved from random retailers, might not be very accurate.
product_codes	All the codes for the requested product in the provided country ( ASIN, EAN, SKU, UPC, MPN )
country	The ISO-2 code for the country the above information is related to

Offer Object

Property	Description
id	Internal offer id
price	The numeric value of the price, the prices do not contain any currency information since they are attached to a country
offer_url	The monetizable URL to be used for this offer
offer_url_clean	The direct link to the product page on the selected retailer ( this could be empty/ null due to lack of information from the retailer )
retailer	An Retailer object with the information about the retailer for the current offer ( see Retailer object description below )
retailer_id	Internal ID for the retailer
affiliate_network_id	Internal ID for the affiliate network
api_id	Internal ID for the api where this offer was fetched from
rrp	The Recommended retail price - this is the price the manufacturer recommends as a retailer price.
max_price	The highest price Squirrel registered for this retailer for this product on the 90 days prior to the request
min_price	The lowest price Squirrel registered for this retailer for this product on the 90 days prior to the request.
in_stock_status	A boolean value to provide information if the product is in stock or not. By defaul, Squirrel removes the offers out of stock, you can change this setting on your account.

Retailer Object

Property	Description
id	Internal Squirrel id for the retailer
name	Name of the retailer on the Squirrel Database
logo_url	Squirrel's image url for the retailer

Responses when there isn't product information

[ ] - When the product doesn't match any value on Squirrel's Database.

You can get a message instead of an empty array or the product information, these are the possible messages and the scenarios when they could be seen:

"Squirrel is looking for this product and adding it to the DB."
- Squirrel doesn't know that product, it is being added to the Database to find prices/ codes/ cross-country matches.

"We are almost there, please check again later! Current status: [STATUS]"
Squirrel is processing the request. Different possible status:
- Pending: The request wasn't picked up yet.
- Rejected: The product was rejected by Squirrel because the code is invalid.
- PendingSearch: Squirrel is fetching this product on all retailers.
- Excessive Results: Squirrel got too many results for the specified code, and wasn't able to do a valid match, please use a different code for the same product.
- Not Found: Squirrel wasn't able to find any match for the provided code. Please try adding more retailers to your Squirrel account to increase the search area for Squirrel.

"We are refreshing our cache with the latest response for you."
- It's a new request, and Squirrel will fulfill it in the backend.
- The Squirrel cache was forced to be refreshed.

Search by text

  curl --location --request POST 'https://api.getsquirrel.co/api/v2/terms/search' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--form 'term="Apple iphone 14"'

The above command returns JSON structured like this:

[
    {
        "name": "Apple iPhone 14 (128 GB) - Blue",
        "squirrel_id": null,
        "rrp": 849,
        "image": "https://m.media-amazon.com/images/I/31VjlrbE3bL._SL160_.jpg",
        "description": "",
        "product_codes": {
            "EPID": "",
            "ASIN": [
                "B0BDJHR5DD"
            ],
            "EAN": [
                "0194253409571"
            ],
            "UPC": [
                "194253409571"
            ],
            "SKU": [],
            "MPN": [
                "MPVN3ZD/A"
            ]
        },
        "country": "GB"
    },
    {
        "name": "Apple iPhone 14 Plus (128 GB) - Starlight",
        "squirrel_id": null,
        "rrp": 949,
        "image": "https://m.media-amazon.com/images/I/31XbWVKOFWL._SL160_.jpg",
        "description": "",
        "product_codes": {
            "EPID": "",
            "ASIN": [
                "B0BDHYZ6ZN"
            ],
            "EAN": [
                "0194253373704"
            ],
            "UPC": [
                "194253373704"
            ],
            "SKU": [],
            "MPN": [
                "MQ4Y3ZD/A"
            ]
        },
        "country": "GB"
    },
    {
        "name": "Apple iPhone 14 Pro (128 GB) - Deep Purple",
        "squirrel_id": null,
        "rrp": 1099,
        "image": "https://m.media-amazon.com/images/I/31MX9scnEzL._SL160_.jpg",
        "description": "",
        "product_codes": {
            "EPID": "",
            "ASIN": [
                "B0BDJ279KF"
            ],
            "EAN": [
                "0194253402169"
            ],
            "UPC": [
                "194253402169"
            ],
            "SKU": [],
            "MPN": [
                "MQ0G3ZD/A"
            ]
        },
        "country": "GB"
    },
    {
        "name": "Apple iPhone 14 Pro Max (128 GB) - Silver",
        "squirrel_id": null,
        "rrp": 1199,
        "image": "https://m.media-amazon.com/images/I/31O8D6p7sfL._SL160_.jpg",
        "description": "",
        "product_codes": {
            "EPID": "",
            "ASIN": [
                "B0BDHTRL5X"
            ],
            "EAN": [
                "0194253380177"
            ],
            "UPC": [
                "194253380177"
            ],
            "SKU": [],
            "MPN": [
                "MQ9Q3ZD/A"
            ]
        },
        "country": "GB"
    }
]

HTTP Request

POST https://api.getsquirrel.co/api/v2/terms/search

Query Parameters

Parameter	Type	Description
term	string	Text to search the API.
country	string	ISO code of the country to filter the results. If this field is empty, the results will be for UK.

Response

Product Information

Property	Description
name	The product name for the country
squirrel_id	The unique ID for that product on your account. This is the same squirrel_id you can use on the widget to display this product in a webpage, or to use on "little squirrel"
rrp	The Recommended retail price - this is the price the product was put on the market
image	Product image URL
description	The product description, this information is retrieved from random retailers, might not be very accurate.
product_codes	All the codes for the requested product in the provided country ( ASIN, EAN, SKU, UPC, MPN )
country	The ISO-2 code for the country the above information is related to

Webhooks

Squirrel provides to the Squirrel Expert plan subscribers the ability to receive product updates via a webhook functionality. Contact a team member to have this setup on your account.

Endpoints

With the following endpoints, the user can check for a webhook and activate it or disable it.

Use the request_id you got from the response on any other endpoint to the webhooks endpoints

GET https://api.getsquirrel.co/api/v2/webhooks/{request_id}
This endpoint will reply with the information on the specified webhook

Parameter	Type	Description
with_data	boolean	Request the response to have the content of the webhook

Property	Description
squirrel_id	The Squirrel ID the webhook provides information on
request_hash	The request id
created_at	The date when the webhook was created on the system
last_webhook_at	The most recent date the webhook was sent to the client
active	The status of the webhook ( If active = 1, the webhook is active and will be sent when a update occurs. If active = 0 this webhook is paused )
content	When requested, this property will have the content of the webhook

DELETE https://api.getsquirrel.co/api/v2/webhooks/{request_id}
Disables/ pause a webhook

PUT https://api.getsquirrel.co/api/v2/webhooks/{request_id}
Reactivates a webhook

Countries

The Countries endpoint will return all the supported countries by the Squirrel API.

List

  curl --location --request GET 'https://api.getsquirrel.co/api/v2/utils/countries' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]'

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "iso": "GB",
    "name": "United Kingdom"
  },
  {
    "id": 2,
    "iso": "US",
    "name": "United States"
  },
  {
    "id": 13,
    "iso": "AU",
    "name": "Australia"
  },
  {
    "id": 38,
    "iso": "CA",
    "name": "Canada"
  },
  {
    "id": 73,
    "iso": "FR",
    "name": "France"
  },
  {
    "id": 80,
    "iso": "DE",
    "name": "Germany"
  },
  {
    "id": 99,
    "iso": "IN",
    "name": "India"
  },
  {
    "id": 105,
    "iso": "IT",
    "name": "Italy"
  },
  {
    "id": 150,
    "iso": "NL",
    "name": "Netherlands"
  },
  {
    "id": 199,
    "iso": "ES",
    "name": "Spain"
  },
  {
    "id": 205,
    "iso": "SE",
    "name": "Sweden"
  }
]

Show all supported countries. Code and Id.

HTTP Request

GET https://api.getsquirrel.co/api/v2/utils/countries

Query Parameters

No parameters

Statistics

Impressions

  curl --location 'https://api.getsquirrel.co/api/v2/stats/impressions' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--form 'page="1"' \
--form 'per_page="5"' \
--form 'start_date="2023-01-01"' \
--form 'end_date="2023-01-31"'

The above command returns JSON structured like this:

{
  "total_results": 17969,
  "page": 1,
  "total_pages": 3594,
  "stats": [
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "2687282",
      "url": "https://www.bestsquirreldeals.com/pc-and-video-games-deals/150436-farpoint",
      "render_type": ""
    },
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "4340492",
      "url": "https://www.bestsquirreldeals.com/pc-and-video-games-deals/150436-farpoint",
      "render_type": ""
    },
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "12861893",
      "url": "https://www.bestsquirreldeals.com/pc-and-video-games-deals/150436-farpoint",
      "render_type": ""
    },
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "12856113",
      "url": "https://getsquirrel.co/",
      "render_type": ""
    },
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "4340492",
      "url": "https://getsquirrel.co/",
      "render_type": ""
    }
  ]
}

This endpoint will provide the raw data for all the Impressions of Squirrels on your account.

HTTP Request

POST https://api.getsquirrel.co/api/v2/stats/impressions

Query Parameters

Property	Description
start_date	The start date for the interval of data to get statistics. ( date format: YYYY-MM-DD, example: 2023-01-01 )
end_date	End of the date interval to query the stats ( max interval 31 days )
page	The page number to retrieve from the `total_pages`
per_page	Amount of results per page ( max value: 10,000 )

Response

Meta information

Property	Description
total_results	The amount of results the performed query returned
page	The retrieved page
total_pages	The amount of pages generated to be queried considering the amount of results and the per_page parameter

Stats

Property	Description
date	The day the event occurred ( date format: YYYY-MM-DD, example: 2023-01-01 )
count	The amount of times that event happened
squirrel_id	The unique ID for that product on your account. This is the same squirrel_id you can use on the widget to display this product in a webpage, or to use on "little squirrel"
url	The URL referrer where the event occurred ( this information depends on a large number of factors, Sometimes you might just see your domain here ( for example AMP pages dont allow widgets to collect this data )
render_type	This is the type of impression, possible values: '' ( empty, the default ), 'tbc' ( when the impression happened without offers )

Clicks

  curl --location 'https://api.getsquirrel.co/api/v2/stats/clicks' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--form 'page="1"' \
--form 'per_page="5"' \
--form 'start_date="2023-01-01"' \
--form 'end_date="2023-01-31"'

The above command returns JSON structured like this:

{
  "total_results": 7,
  "page": 1,
  "total_pages": 2,
  "stats": [
    {
      "date": "2023-01-05",
      "count": "1",
      "squirrel_id": "2685401",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/143157-sony-a9",
      "offer_type": "default",
      "retailer": "Amazon UK"
    },
    {
      "date": "2023-01-05",
      "count": "1",
      "squirrel_id": "2693196",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/156521-sigma-85mm-f1-4-dg-dn",
      "offer_type": "default",
      "retailer": "Wex Photo Video"
    },
    {
      "date": "2023-01-05",
      "count": "1",
      "squirrel_id": "2693196",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/156521-sigma-85mm-f1-4-dg-dn",
      "offer_type": "default",
      "retailer": "Very.co.uk"
    },
    {
      "date": "2023-01-05",
      "count": "1",
      "squirrel_id": "2693196",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/156521-sigma-85mm-f1-4-dg-dn",
      "offer_type": "default",
      "retailer": "Wex Photo Video"
    },
    {
      "date": "2023-01-14",
      "count": "1",
      "squirrel_id": "2711615",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/camera-and-photo-price/digital-cameras/307357-olympus-om-d-e-m5-mark-iii-micro-four-thirds-syste",
      "offer_type": "default",
      "retailer": "Clifton Cameras"
    }
  ]
}

This endpoint will provide the raw data for all the Impressions of Squirrels on your account.

HTTP Request

POST https://api.getsquirrel.co/api/v2/stats/impressions

Query Parameters

Property	Description
start_date	The start date for the interval of data to get statistics. ( date format: YYYY-MM-DD, example: 2023-01-01 )
end_date	End of the date interval to query the stats ( max interval 31 days )
page	The page number to retrieve from the `total_pages`
per_page	Amount of results per page ( max value: 10,000 )

Response

Meta information

Property	Description
total_results	The amount of results the performed query returned
page	The retrieved page
total_pages	The amount of pages generated to be queried considering the amount of results and the per_page parameter

Stats

Property	Description
date	The day the event occurred ( date format: YYYY-MM-DD, example: 2023-01-01 )
count	The amount of times that event happened
squirrel_id	The unique ID for that product on your account. This is the same squirrel_id you can use on the widget to display this product in a webpage, or to use on "little squirrel"
url	The URL referrer where the event occurred ( this information depends on a large number of factors, Sometimes you might just see your domain here ( for example AMP pages dont allow widgets to collect this data )
offer_type	This is the type of the clicked offer, possible values: 'default' ( a normal retailer offer ), 'tbc' ( when the click happened on a "Check Price Here" offer ), 'tds' ( when using the TDS plugin, the click was on a Mobile deal offer )
retailer	The clicked offer's retailer name

Errors

The Squirrel API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid ( A message is returned with the problem explantion ).
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The method doesn't exist.
429	Too Many Requests -- You're making too many requests and going over your RPS ( Requests per second ) allowance ( 1 by default )
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.