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'. |
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 |
used_offers | An array of Offers objects, this array contains only offers that were flagged as "Used" |
refurbished_offers | An array of Offers objects, this array contains only offers that were flagged as "Refurbished" |
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. |
image_url | An URL for an image provided by the retailer, could be different from the image Squirrel provides. |
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: 1,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: 1,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 |
Squirrel Notify Alerts
You can set up email and webhook alerts to track when a price drops for a specific Squirrel.
The Squirrel API allows you to manage your Squirrel Notify system.
Via the API you're able to create, deactivate or check the status of an alert
Alert Object
Property | Description |
---|---|
id | Internal offer id |
name | Name of the user that requested the alert |
squirrel_id | Squirrel associated with the request |
squirrel_page_url | URL of the page where the alert was requested |
country | ISO of the alert's country |
alert_type_id | Type of alert ( Possible values: 1 - Back In Stock, 2 - Price drop ) |
alert_method_id | Method to fulfill the alert when triggered ( Possible values: 1 - Email, 2 - Webhook) |
alert_method_value | Target value of the alert (for example: 350.00 (when the alert is for price)) |
created_at | Date the alert was created |
updated_at | Date when the alert was last updated |
active | Alert status ( 1 - Active, 0 - Inactive ) |
retailer | Retailer object for when the alert is targeted to a particular retailer |
Create an alert
HTTP Request
POST https://api.getsquirrel.co/api/v2/alerts
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. |
country | string | ISO code of the country. |
alert_type_id | integer | Type of alert ( Possible values: 1 - Back In Stock, 2 - Price drop ) |
alert_method_id | integer | Method to fulfill the alert when triggered ( Possible values: 1 - Email, 2 - Webhook) |
value_type | string | Type of the value for the alert ( Possible values: percentage, price ) |
alert_value | string | Value for the alert ( example: 10 ( 10% for when 'value_type' is 'percentage') |
retailer_id | integer | ID of the retailer to target the alert (if empty, any retailer available for the squirrel will be targeted) |
user_name | string | Name of the targeted user |
user_email | string | If 'alert_method_id' is email, this is the email that will be used to alert the user |
first_email | integer | Option for the Squirrel system to send an email to the user when the alert is created (1 - Send, 0 - Ignore) |
Query Parameters
An alert object
Check an alert
GET https://api.getsquirrel.co/api/v2/alerts/{alert_id}
Delete an alert
DELETE https://api.getsquirrel.co/api/v2/alerts/{alert_id}
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. |