Documentation

One authentication scheme, two endpoints per marketplace, JSON in and out.

Authentication

Every request carries your key as a bearer token. Generate keys in the dashboard.

Authorization: Bearer gd_live_xxxxxxxxxxxxxxxxxxxx

Keys are shown once at creation. If you lose one, revoke it and generate another.

Base URL

https://api.gravitrondata.com

Endpoints

Method	Path	Returns
GET	`/v1/walmart/product`	Full product record
GET	`/v1/walmart/price`	Price, availability and seller only

Parameters

Name	Required	Description
`item_id`	One of the two	Marketplace item ID, e.g. `650209444`
`url`	One of the two	Full product URL

Example

curl https://api.gravitrondata.com/v1/walmart/price \
  -H "Authorization: Bearer gd_live_..." \
  -G --data-urlencode "item_id=974282675"

{
  "walmart_item_id": "974282675",
  "title": "L'Oreal Paris Lumi Glotion Liquid Face and Body Highlighter",
  "price": {
    "current": 14.97, "was": 17.99, "unit": 14.97,
    "currency": "USD", "is_reduced": true, "display": "$14.97"
  },
  "availability": {
    "in_stock": true, "status": "IN_STOCK", "transactable_offers": 1
  },
  "seller": {
    "name": "Walmart.com", "is_walmart": true,
    "rating": 4.29, "review_count": 3620
  }
}

Response headers

Header	Meaning
`X-Credits-Remaining`	Your balance after this call
`X-Credits-Charged`	`1` if this call cost a credit, `0` if not

Status codes

Code	Meaning	Charged
`200`	Product data returned	Yes
`400`	Missing or invalid parameters	No
`401`	Missing, invalid or revoked key	No
`402`	Out of credits	No
`404`	No product at that ID	Yes — a real answer
`429`	Rate limit exceeded	No
`501`	That marketplace is not live yet	No
`502`/`503`	Lookup failed on our side	No — credit returned

Retry once on 5xx

These are live fetches of real marketplace pages, and roughly 1 in 20 cold lookups fails. You are never charged for those, and a single retry almost always succeeds. Build one retry into your client.

import requests, time

def lookup(item_id, key, attempts=2):
    for i in range(attempts):
        r = requests.get(
            "https://api.gravitrondata.com/v1/walmart/price",
            params={"item_id": item_id},
            headers={"Authorization": f"Bearer {key}"}, timeout=90)
        if r.status_code < 500:
            return r.json()
        time.sleep(1)
    r.raise_for_status()

Rate limits

Limits are per account and depend on the largest bundle you have purchased: 5/min on the free trial, then 10, 20 or 40 requests per minute. Exceeding the limit returns 429 and costs nothing.