Docs/Getting Started

Getting Started

Extract real-time product data - prices, variants, ratings, images - from Amazon.in and other supported storefronts with a single HTTP request.

Base URL

All API requests go to the following base URL:

text

https://api.pricium.store

Authentication

Every request must include your API key in the X-API-Key header. You can find your key in the Dashboard.

Keep your key secret. Never expose it in client-side code or public repositories. Rotate immediately if compromised.

http

X-API-Key: pk_live_YOUR_API_KEY

Scrape Endpoint

Scrape a product page and get structured data back - including all variant prices, availability, images, ratings, and dimensions.

POST/scrape

200 OK

Request Body

Parameter	Type	Required	Description
`url`	string	required	Full URL of the product page to scrape. Supported domains: amazon.in, flipkart.com, amazon.com, ebay.com, walmart.com, aliexpress.com, bigbasket.com, gymshark.com (Shopify), and more.
`latitude`	number	optional	Latitude for location-based pricing (e.g. delivery pin-code inference). Defaults to a generic India location if omitted.
`longitude`	number	optional	Longitude for location-based pricing. Should be passed together with latitude.

Examples

cURL

curl --location 'https://api.pricium.store/scrape' \
--header 'X-API-Key: pk_live_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "url": "https://www.amazon.in/dp/B0CVVFX2GB",
  "latitude": 12.88603214347042,
  "longitude": 77.67313031967782
}'

JavaScript / TypeScript

const response = await fetch("https://api.pricium.store/scrape", {
  method: "POST",
  headers: {
    "X-API-Key": "pk_live_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.amazon.in/dp/B0CVVFX2GB",
    latitude: 12.88603214347042,
    longitude: 77.67313031967782,
  }),
});

const data = await response.json();
console.log(data);

Python

import httpx

response = httpx.post(
    "https://api.pricium.store/scrape",
    headers={
        "X-API-Key": "pk_live_YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://www.amazon.in/dp/B0CVVFX2GB",
        "latitude": 12.88603214347042,
        "longitude": 77.67313031967782,
    },
)

data = response.json()
print(data)

Search Endpoint

Search supported storefronts (Amazon India, Flipkart, etc.) by query keyword and fetch structured product summaries, matching brands, active and invalid diagnostic filters, and dynamic sorting.

GET/search

200 OK

Query Parameters

Parameter	Type	Required	Description
`q`	string	required	Search query keyword or phrase (e.g. 'iphone 15').
`domain`	string	required	Target retail domain to search (e.g. 'amazon.in' or 'flipkart.com').
`page`	number	optional	Result page number (1-10). Defaults to 1.
`brand`	string	optional	Filter results by brand name (comma-separated list).

Examples

cURL

curl --location 'https://api.pricium.store/search?q=iphone+15&domain=amazon.in&page=1' \
--header 'X-API-Key: pk_live_YOUR_API_KEY'

JavaScript / TypeScript

const response = await fetch("https://api.pricium.store/search?q=iphone+15&domain=amazon.in&page=1", {
  method: "GET",
  headers: {
    "X-API-Key": "pk_live_YOUR_API_KEY",
  },
});

const data = await response.json();
console.log(data);

Python

import httpx

response = httpx.get(
    "https://api.pricium.store/search",
    headers={
        "X-API-Key": "pk_live_YOUR_API_KEY",
    },
    params={
        "q": "iphone 15",
        "domain": "amazon.in",
        "page": 1,
    },
)

data = response.json()
print(data)

Response

A successful response returns 200 OK with a JSON body containing three top-level keys: success, data, and meta.

Top-level fields

Field	Type	Description
`success`	boolean	true when the scrape completed without errors.
`domain`	string	Detected domain of the product URL (e.g. amazon.in).
`data`	object	Structured product data. See data object below.
`meta`	object	Echo of the request inputs (url, latitude, longitude, domain).

`data` object

Field	Type	Description
`product_name`	string	Full product title as listed on the storefront.
`brand`	string	Brand name extracted from the product page.
`rating`	string	Average customer rating (e.g. "3.7").
`rating_count`	string	Total number of ratings.
`mrp`	string	Maximum retail price with currency symbol (e.g. "₹1,999").
`discount_percent`	string	Discount percentage off the MRP.
`category`	string	Breadcrumb category path separated by >.
`image_url`	string	Primary product image URL.
`feature_bullets`	string[]	Key feature bullet points from the listing.
`badges`	string[]	Badges shown on the listing (e.g. Best Seller, Amazon's Choice).
`dimension_names`	string[]	Names of the variant dimensions (e.g. ["Size", "Colour"]).
`variations`	Variation[]	All purchasable variants with individual prices, images, and availability.

`Variation` object

Each entry in data.variations describes one purchasable SKU. Dimension values are stored in the variation_attributes map.

Field	Type	Description
`variation_attributes`	object	Map of dimension values (e.g. {"Size": "M", "Colour": "Green"}).
`images`	string[]	Image URLs for this specific variant.
`price`	number \| null	Current selling price as a number. null when the variant is unavailable.
`price_formatted`	string \| null	Price with currency symbol (e.g. "₹940"). null when unavailable.
`is_available`	boolean	Whether this variant is currently in stock and purchasable.
`url`	string	Direct URL to this specific variant SKU.

Example Response

JSON

{
  "success": true,
  "domain": "amazon.in",
  "data": {
    "product_name": "U.S. Polo Assn. Men Shirt",
    "brand": "U.S. Polo Assn.",
    "rating": "3.7",
    "rating_count": "12",
    "mrp": "₹1,999",
    "discount_percent": "37",
    "category": "Clothing & Accessories > Men > T-shirts, Polos & Shirts > Shirts",
    "image_url": "https://m.media-amazon.com/images/I/71AIw7PY+BL._SL1500_.jpg",
    "feature_bullets": [],
    "badges": [],
    "url": "https://www.amazon.in/dp/B0CVVFX2GB",
    "dimension_names": ["Size", "Colour"],
    "variations": [
      {
        "variation_attributes": {
          "Size": "M",
          "Colour": "Green"
        },
        "images": ["https://m.media-amazon.com/images/I/712wlc+tLYL._SL1500_.jpg"],
        "price": 940,
        "price_formatted": "₹940",
        "is_available": true,
        "url": "https://www.amazon.in/dp/B0CV7R8G5Z?th=1"
      },
      {
        "variation_attributes": {
          "Size": "XL",
          "Colour": "Blue"
        },
        "images": ["https://m.media-amazon.com/images/I/71AIw7PY+BL._SL1500_.jpg"],
        "price": null,
        "price_formatted": null,
        "is_available": false,
        "url": "https://www.amazon.in/dp/B0CVVF8GZD?th=1"
      }
      // ... more variations
    ]
  },
  "meta": {
    "domain": "amazon.in",
    "latitude": 12.88603214347042,
    "longitude": 77.67313031967782,
    "url": "https://www.amazon.in/dp/B0CVVFX2GB"
  }
}

Error Handling

When a request fails, the API returns a non-2xx HTTP status and a JSON body with a detail field describing the error.

Status	Meaning
`401`	Missing or invalid X-API-Key header.
`403`	API key exists but does not have permission for this resource.
`422`	Request body failed validation (e.g. missing url field).
`429`	Rate limit exceeded. Back off and retry.
`500`	Scraping failed - the target page may have changed or is unavailable.

Getting Started

Base URL

Authentication

Scrape Endpoint

Request Body

Examples

Search Endpoint

Query Parameters

Examples

Response

Top-level fields

data object

Variation object

Example Response

Error Handling

Next Steps

`data` object

`Variation` object