Table of Contents

API Documentation

The E-commerce Scraper API provides access to product categories and details from major retailers including Amazon, Walmart, Costco, Best Buy, Home Depot, and Target.

Base URL: https://scrapper.anora.dev/api

Authentication

Currently, no authentication is required to access the API endpoints.

Endpoints

GET /categories/{retailer}

Retrieve product categories for a specified retailer.

Path Parameters:
  • retailer (string, required): One of amazon, walmart, costco, bestbuy, homedepot, target
Query Parameters:
  • limit (integer, optional): Maximum number of categories (default: 50, max: 100)
Example Request:
GET https://scrapper.anora.dev/api/categories/amazon?limit=10
Example Response:
{
  "retailer": "amazon",
  "categories": [
    {
      "category_id": "amazon_node_123",
      "name": "Electronics",
      "parent_category": null,
      "retailer": "amazon",
      "url": "https://www.amazon.com/electronics"
    }
  ],
  "count": 1,
  "limit": 10
}

GET /products/{retailer}

Retrieve product details for a specified retailer and category.

Path Parameters:
  • retailer (string, required): One of amazon, walmart, costco, bestbuy, homedepot, target
Query Parameters:
  • category_id (string, required): Category identifier from categories endpoint
  • limit (integer, optional): Maximum number of products (default: 20, max: 50)
Example Request:
GET https://scrapper.anora.dev/api/products/walmart?category_id=walmart_cat_123&limit=5
Example Response:
{
  "retailer": "walmart",
  "category_id": "walmart_cat_123",
  "products": [
    {
      "product_id": "123456789",
      "name": "Sample Product",
      "category_id": "walmart_cat_123",
      "retailer": "walmart",
      "price": 29.99,
      "description": "Product description",
      "image_url": "https://example.com/image.jpg",
      "url": "https://www.walmart.com/product/123"
    }
  ],
  "count": 1,
  "limit": 5
}

GET /retailers

Get list of supported retailers and their configuration.

Example Request:
GET https://scrapper.anora.dev/api/retailers
Example Response:
{
  "supported_retailers": [
    {
      "name": "amazon",
      "base_url": "https://www.amazon.com",
      "rate_limit": 0.5
    }
  ],
  "count": 6
}

GET /status

Get API health status and configuration information.

Example Request:
GET https://scrapper.anora.dev/api/status
Example Response:
{
  "status": "healthy",
  "supported_retailers": ["amazon", "walmart", "costco", "bestbuy", "homedepot", "target"],
  "proxy_stats": {
    "total_proxies": 100,
    "bad_proxies": 5,
    "using_proxies": true
  },
  "rate_limits": {
    "amazon": 0.5,
    "walmart": 1.0
  }
}

Data Schemas

Category Schema
Field Type Description
category_id string Unique identifier for the category
name string Category name
parent_category string | null Parent category name or null
retailer string Retailer name
url string Category page URL
Product Schema
Field Type Description
product_id string Unique product identifier (ASIN, SKU, etc.)
name string Product title
category_id string Associated category ID
retailer string Retailer name
price float | null Price in USD
description string | null Product description
image_url string | null Product image URL
url string Product page URL

Error Handling

The API uses standard HTTP status codes and returns error information in JSON format.

Common Error Responses
Status Code Description Example Response
400 Bad Request {"error": "category_id parameter is required"}
404 Not Found {"error": "Endpoint not found"}
500 Internal Server Error {"error": "Internal server error", "message": "..."}

Rate Limits

The API implements rate limiting per retailer to comply with scraping policies:

Current Rate Limits
Retailer Requests per Second Notes
Amazon 0.5 Conservative rate to avoid detection
Walmart 1.0 Standard rate limiting
Costco 1.0 Standard rate limiting
Bestbuy 1.0 Standard rate limiting
Homedepot 1.0 Standard rate limiting
Target 1.0 Standard rate limiting
Note: Rate limits are enforced server-side. Exceeding limits may result in temporary blocking or degraded performance.