Commerce
Share of digital shelf, including the products AI answers name
Shelf tools tell you where you rank in shopping results. None of them tell you which products the answer above those results decided to name — and that is increasingly the shelf a customer sees first.
The shelf now has a layer nobody is measuring
Category monitoring assumes a page of listings: who is in the shopping unit, at what price, in what position. That assumption held while the listing page was the destination. It no longer is.
When a shopper asks an assistant for the best option in a category, a small set of products and stores gets named and the rest of the shelf is invisible. Missing from that set is a commercial outcome, and it does not appear in any listing-position report.
- Price position only means something against the shelf that was actually visible that day.
- A competitor absent from the shopping unit can still be the one the answer names.
- One snapshot is a number; the series is the decision — and the series has to start somewhere.
What the call measures
Step 1
Category keywords, both surfaces
For up to fifty keywords, shopping results and organic results are read for your brand and the competitors you name, and price position is computed against what was on the shelf at that moment.
Step 2
The AI layer of the same query
The AI Overview for those keywords is read too, so the report answers a question a shelf tool cannot: which products and stores the answer cited, and whether yours was among them.
Step 3
The series is yours, and free to read
Every shelf call becomes a point in a time series scoped to your account. GET /v1/commerce/shelf/history returns it at no charge: it serves data you already paid for and calls nothing upstream.
The call, in full
curl -X POST https://api.dataswap.io/v1/commerce/shelf \
-H "Authorization: Bearer $DATASWAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"keywords": ["trail running shoes", "waterproof trail shoes"],
"brand": "example.com",
"competitors": ["competitor-a.com", "competitor-b.com"],
"gl": "pt"
}'brand and keywords are required; competitors is optional and up to ten.
curl "https://api.dataswap.io/v1/commerce/shelf/history?brand=example.com" \
-H "Authorization: Bearer $DATASWAP_API_KEY"A free read of your own captures — the account comes from the key, never from a parameter.
The calls, and what they cost
| Endpoint | What it does | Price |
|---|---|---|
POST /v1/commerce/shelf | Shelf share, price position and AI citations for a set of category keywords. | 10 credits for the synthesis, plus the operations it runs($0.02) |
GET /v1/commerce/shelf/history | The time series of your own shelf captures for a brand. | 0 credits |
POST /v1/commerce/match | Are these two offers the same product? A verdict of same, variant, bundle or different, with the evidence. | 5 credits($0.01) |
POST /v1/shopping | The shopping results themselves, as JSON. Answers 202 with a job_id when the crawl runs long — see the note below. | 3 credits($0.0060) |
Shelf and match are priced per call, not per SKU compared: matching by identifier is resolved without a model and only ambiguous candidates are reasoned over, so the price does not climb with the size of your catalog. Naming a single surface in targets is both cheaper and usually quicker than searching all of them.
1 credit = $0.002 on every plan. Full plans and prepaid packs are on the pricing section.
Read this before you build on it
POST /v1/commerce/match and POST /v1/shopping may answer 202 with a job_id instead of 200. Both run long upstream tasks that routinely exceed the handoff window, so plan for polling GET /v1/jobs/{id} from the first day. Resubmitting starts a second job with a second reservation.
It is not a real-time price feed. Each call is a measurement taken when you make it, at the cadence you choose — there is no streaming price channel and no repricing engine.
The history series starts on your first shelf call. There is no backfill, because we do not hold measurements that were never taken.
Marketplace coverage is what the API reference lists. If your category lives somewhere we do not read, this page will not change that.
Questions we get asked
- Does the price scale with the number of products I compare?
- No. Both shelf and match are priced per call. Identifier matches are resolved deterministically and only the ambiguous remainder is reasoned over, which is what keeps a large catalog from turning into a large bill.
- Why does POST /v1/commerce/match sometimes return 202?
- Because it queries more than one shopping surface and those upstream tasks routinely exceed the handoff window. You get a job_id and a poll_url; no credits are charged until there is a result, and a failed job is refunded.
- Does reading the history cost credits?
- No, it is 0 credits. It serves measurements this account already paid for and makes no upstream call, and the account is taken from your API key rather than from a query parameter.
- Can I monitor a competitor rather than my own brand?
- Yes. brand accepts any brand or domain and competitors takes up to ten more, so a category study that never mentions your own name is a normal use of the endpoint. What is measured is public shelf data either way, and the history series is keyed to the brand you asked about.
- How often should I run it?
- That is your call, and we deliberately do not schedule it for you. Categories with volatile pricing justify a daily capture; most do not, and a weekly series is cheaper and just as readable.
Keep reading
Put the prism to work.
Create an account and get your API key — no card required. Start on the six live bands and the twelve inference tools; the eight new capabilities land on the same key as they ship.