ASINScope API Documentation for Circana

Overview

This document describes the ASINScope API endpoints provided to Circana for retrieving Amazon product data by ASIN. Two endpoints are available under your subscription:

• /circana/barcodes — UPC and EAN codes for an ASIN list
• /circana/images — Product title and product images for an ASIN list

Both endpoints share a single daily token allowance, but they have separate short-term (per-minute) buckets so heavy usage of one does not throttle the other within a minute.

Daily allowance: 150,000 products/day shared across both endpoints.

Base URLs

https://api.asinscope.com/circana/barcodes
https://api.asinscope.com/circana/images

Authentication

Authentication is identical for both endpoints — an API key passed as a POST parameter in the request body:

{
  "key": "<API_KEY>"
}

Getting Your API Key: You can find and copy your API key from the ASINScope API Dashboard.

Important: Keep your API key secure and do not share it publicly.

Common Request Format

Both endpoints share the same request envelope.

HTTP Method

POST

Headers

Content-Type: application/json

Request Body

{
  "key": "<API_KEY>",
  "asins": [
    "ASIN1",
    "ASIN2",
    "ASIN3"
  ]
}

Constraints (shared by both endpoints):

• Maximum 100 ASINs per request
• ASINs must be valid Amazon.com product identifiers
• ASINs should be provided as strings

---

Endpoint: Barcodes Lookup

POST https://api.asinscope.com/circana/barcodes

Returns UPC and EAN codes for each ASIN, including primary values and full associated lists.

Example Request

curl --location 'https://api.asinscope.com/circana/barcodes' \
--header 'Content-Type: application/json' \
--data '{
    "key": "<API_KEY>",
    "asins": ["B0086FFHLS", "B00NNUMI86"]
}'

Response Format

{
  "items": [
    {
      "asin": "string",
      "title": "string",
      "upc": "string | null",
      "upcList": ["string"],
      "ean": "string | null",
      "eanList": ["string"]
    }
  ],
  "dailyTokensLeft": number,
  "msBeforeNextDailyToken": number
}

Field Descriptions

For each item:

• asin — The Amazon Standard Identification Number
• title — Product title from the Amazon listing
• upc — Primary UPC currently assigned (null if not available)
• upcList — Array of all associated UPC codes (empty array if none)
• ean — Primary EAN currently assigned (null if not available)
• eanList — Array of all associated EAN codes (empty array if none)

dailyTokensLeft — Remaining tokens in the shared daily allowance after this call. msBeforeNextDailyToken — Milliseconds until the daily quota resets (UTC midnight).

Understanding UPC/EAN Fields

• Individual fields (upc, ean): Show the primary barcode currently assigned by the seller or Amazon.
• List fields (upcList, eanList): Capture all associated barcodes including those from:
  • Listing merges
  • Product variations
  • Different market options
  • Historical barcode associations

Example Response

{
  "items": [
    {
      "asin": "B00NNUMI86",
      "title": "La Roche-Posay Lipikar AP+ Triple Repair Moisturizing Cream...",
      "upc": null,
      "upcList": [],
      "ean": null,
      "eanList": ["3337872418587"]
    },
    {
      "asin": "B0086FFHLS",
      "title": "Philips Monster Vent TMV-3P Brush Reinforced Bristles...",
      "upc": "631102001550",
      "upcList": ["631102001550"],
      "ean": "0631102001550",
      "eanList": ["0631102001550"]
    }
  ],
  "dailyTokensLeft": 998,
  "msBeforeNextDailyToken": 86378782
}

Token Counting

The barcodes endpoint counts requests in multiples of 10:

• 1–10 ASINs = 10 tokens
• 11–20 ASINs = 20 tokens
• 21–30 ASINs = 30 tokens
• … and so on

To minimize cost, batch in groups of 10 whenever possible.

---

Endpoint: Images Lookup

POST https://api.asinscope.com/circana/images

Returns product title and product image URLs for each ASIN. Use this when you need visuals (e.g. catalog galleries, product cards) without the rest of the product payload.

Example Request

curl --location 'https://api.asinscope.com/circana/images' \
--header 'Content-Type: application/json' \
--data '{
    "key": "<API_KEY>",
    "asins": ["B0086FFHLS", "B00NNUMI86"]
}'

Response Format

{
  "items": [
    {
      "asin": "string",
      "title": "string | null",
      "images": ["string"]
    }
  ],
  "dailyTokensLeft": number,
  "msBeforeNextDailyToken": number
}

Field Descriptions

For each item:

• asin — The Amazon Standard Identification Number
• title — Product title from the Amazon listing (null if the product is unknown)
• images — Array of product image URLs. Order follows what Amazon publishes; the first entry is typically the main listing image. Empty array if no images are available.

dailyTokensLeft — Remaining tokens in the shared daily allowance after this call. msBeforeNextDailyToken — Milliseconds until the daily quota resets (UTC midnight).

Example Response

{
  "items": [
    {
      "asin": "B00NNUMI86",
      "title": "La Roche-Posay Lipikar AP+ Triple Repair Moisturizing Cream...",
      "images": [
        "https://m.media-amazon.com/images/I/71abc...jpg",
        "https://m.media-amazon.com/images/I/81xyz...jpg"
      ]
    },
    {
      "asin": "B0086FFHLS",
      "title": "Philips Monster Vent TMV-3P Brush Reinforced Bristles...",
      "images": [
        "https://m.media-amazon.com/images/I/61def...jpg"
      ]
    }
  ],
  "dailyTokensLeft": 997,
  "msBeforeNextDailyToken": 86378500
}

Token Counting

The images endpoint counts requests per ASIN, with no rounding:

• 1 ASIN = 1 token
• 7 ASINs = 7 tokens
• 100 ASINs = 100 tokens

This gives you fine-grained billing for small image fetches that are common in UI scenarios.

---

Rate Limits and Quotas

Shared Daily Allowance

Both endpoints draw from a single daily token bucket of 150,000 tokens / day. The daily counter resets at 00:00 UTC.

Separate Short-Term Buckets

Each endpoint has its own per-minute throttle so traffic on one does not block the other:

Barcodes per-minute limit

500 products / minute. Window-based: any request bringing the trailing-minute total above the cap will receive a 429.

Images per-minute limit

Burst capacity 120, refill rate 60 / minute (1 / second). Token-bucket model: up to 120 image lookups can be made in a quick burst, after which the bucket refills at 60 tokens per minute (1 token per second). This is friendlier than a fixed window for UI patterns where image needs are bursty (e.g. loading a product grid in one go).

Best Practices for Rate Management

1. Batch efficiently: Up to 100 ASINs per request — fewer round trips.
2. For barcodes, batch in tens: Tokens are rounded up to the next 10, so groups of 10, 20, 30, … minimize waste.
3. Monitor dailyTokensLeft: It reflects the shared bucket; both endpoints decrement it.
4. Implement exponential backoff on 429 responses.
5. Use msBeforeNextDailyToken to plan request timing when approaching the daily limit.

---

Error Handling

HTTP Status Codes

• 200 OK — Request successful
• 400 Bad Request — Invalid request format or parameters
• 401 Unauthorized — Invalid or missing API key
• 403 Forbidden — Subscription doesn't include access to this feature
• 429 Too Many Requests — Rate limit exceeded (per-minute or daily)
• 500 Internal Server Error — Server-side error

Error Response Format

All error responses follow a consistent format with statusCode, error, and message:

{
  "statusCode": number,
  "error": "Error Type",
  "message": "Human-readable error description or array of validation messages"
}

message may also be an array of strings for multiple validation errors.

Common Error Scenarios

Missing API Key

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "API key is required in request body"
}

Invalid API Key

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Exceeded Request Size (More than 100 ASINs)

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["Maximum 100 ASINs allowed per request"]
}

Per-minute rate limit exceeded (barcodes)

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Not enough capacity. Required: 10 products, Available: 0 products. Try again in 36 seconds"
}

Per-minute rate limit exceeded (images)

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Not enough capacity. Required: 50 images, Available: 20 images. Try again in 30 seconds"
}

Daily limit exceeded (returned by either endpoint once the shared daily allowance is empty)

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Daily limit reached. Please try again in 320 minutes"
}

---

Integration Examples

Python

import requests

API_KEY = "<API_KEY>"  # https://asinscope.com/en/dashboard/asinscope-api
BARCODES_URL = "https://api.asinscope.com/circana/barcodes"
IMAGES_URL = "https://api.asinscope.com/circana/images"

def post_circana(url, asins):
    """POST a list of ASINs (max 100) to the given Circana endpoint."""
    response = requests.post(
        url,
        headers={"Content-Type": "application/json"},
        json={"key": API_KEY, "asins": asins},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

asins = ["B0086FFHLS", "B00NNUMI86"]

# Barcodes
barcodes = post_circana(BARCODES_URL, asins)
for item in barcodes["items"]:
    print(f"{item['asin']} UPCs={item['upcList']} EANs={item['eanList']}")

# Images
images = post_circana(IMAGES_URL, asins)
for item in images["items"]:
    print(f"{item['asin']} -> {len(item['images'])} image(s); title={item['title']}")

Node.js

const axios = require('axios');

const API_KEY = '<API_KEY>'; // https://asinscope.com/en/dashboard/asinscope-api
const BARCODES_URL = 'https://api.asinscope.com/circana/barcodes';
const IMAGES_URL = 'https://api.asinscope.com/circana/images';

async function postCircana(url, asins) {
    const {data} = await axios.post(
        url,
        {key: API_KEY, asins},
        {headers: {'Content-Type': 'application/json'}, timeout: 30_000}
    );
    return data;
}

(async () => {
    const asins = ['B0086FFHLS', 'B00NNUMI86'];

    const barcodes = await postCircana(BARCODES_URL, asins);
    for (const item of barcodes.items) {
        console.log(`${item.asin} UPCs=${item.upcList} EANs=${item.eanList}`);
    }

    const images = await postCircana(IMAGES_URL, asins);
    for (const item of images.items) {
        console.log(`${item.asin} -> ${item.images.length} image(s); title=${item.title}`);
    }
})();

---

Testing Recommendations

1. Start with small batches: Test with 1–10 ASINs initially.
2. Verify response parsing: Handle null title, empty images/upcList/eanList.
3. Test error scenarios: Confirm your client handles 400/401/429 responses.
4. Monitor performance: Track response times for different batch sizes.
5. Test both endpoints independently: Burst the images endpoint to confirm the token bucket behavior, batch the barcodes endpoint in tens to minimize token cost.

Support

For technical and billing support or questions:

• Email: [email protected]
• Reference ticket: [## 1375 ##]

---

Last Updated: May 2026 Version: 1.1