Shops
Your crossed-out prices and product pages, checked against the brand's own site. Read the results over the API.
https://api.trawl.meAuthentication
Send a developer API key as a bearer token. Every route is a read: nothing here changes your data.
The key
trawl:shops:read. In the web app, create it with the access “Shops data, read only” (preselected in a Shops organization). “Read only” cannot call Shops routes. A key made before this choice has full access.Errors
401403404422429curl "https://api.trawl.me/api/shops/matches?status=too_high" \
-H "Authorization: Bearer $TRAWL_API_KEY"{
"type": "success",
"message": "…",
"data": …
}Read everything, each day
Your catalog is read each morning, each brand's site at least every 7 days. You have nothing to start: read the result.
- Read
summary. Go on whencheckedAtis today and at least 10 minutes old. - Read
sales. - For each sale, read
matches?sale={handle}&perPage=200until a page comes back short. - For its brand pages, read the same with
group=product&include=pages. - Read
summaryagain. IfcheckedAtmoved, start over.
Load variants by variantKey, brand pages by productId.
What you no longer read has left its sale. Keep your own history if you need one.
A match with no catalog.sale shows only in a list without sale.
Fix lines land later than the check: read fixes?since=.
const get = async (path) => {
const res = await fetch(`https://api.trawl.me/api/shops${path}`, {
headers: { Authorization: `Bearer ${process.env.TRAWL_API_KEY}` },
});
return (await res.json()).data;
};
const { checkedAt } = await get("/summary");
for (const sale of await get("/sales")) {
for (let page = 0; ; page += 1) {
const rows = await get(
`/matches?sale=${sale.handle}&perPage=200&page=${page}`,
);
save(rows); // by variantKey
if (rows.length < 200) break;
}
}
const after = await get("/summary");
if (after.checkedAt !== checkedAt) { /* start over */ }Latest check
GET /api/shops/summary
The counts of the latest check, and the brands Trawl does not cover yet.
Returns
checkedAtdatebyStatusobjectmatchedintegertooHighGapnumbernotCoveredarraykpiobjectcurl "https://api.trawl.me/api/shops/summary" \
-H "Authorization: Bearer $TRAWL_API_KEY"{
"type": "success",
"message": "shop summary",
"data": {
"variants": 1240,
"products": 612,
"byStatus": {
"too_high": 86,
"ok": 702,
"not_found": 318,
"name_only": 41,
"not_comparable": 93
},
"matched": 788,
"tooHighGap": 1842.5,
"notCovered": [{ "vendor": "Ostra", "variants": 57 }, …],
"byVendor": […],
"checkedAt": "2026-11-03T07:04:00.000Z",
"kpi": {
"brands": { "onSale": 24, "comparable": 22, "covered": 19, … },
"products": { "onSale": 612, "matched": 391, … },
"price": { "judged": 788, "tooHigh": 86, "tooHighPct": 10.9, … },
"listing": { "rated": 240, "brandBetter": 96, … }
}
}
}Sales
GET /api/shops/sales
Your sales in your home page's order, then the ones off the home, latest start first.
Returns
handlestringsale on matches.positionintegernull off the home.kpiobjectsummary, for this sale.curl "https://api.trawl.me/api/shops/sales" \
-H "Authorization: Bearer $TRAWL_API_KEY"{
"type": "success",
"message": "shop sales",
"data": [
{
"handle": "northfold",
"title": "Northfold",
"image": "https://your-shop.example/northfold.jpg",
"startAt": "2026-11-01T08:00:00.000Z",
"endAt": "2026-11-09T22:00:00.000Z",
"discountLabel": "-50%",
"position": 0,
"kpi": { "brands": { … }, "products": { … }, "price": { … }, "listing": { … } }
}
]
}List matches
GET /api/shops/matches
One match per variant, biggest gap first. data is a bare array: read until a page comes back short.
Parameters
statusenumlistingenumconfidenceenumhigh, medium or low. With group=product, lists only the variants at that level.cheaperbooleantrue: only what is cheaper at the brand. Combines with the other filters. Cheaper at the brandsalestringsearchstringsortenumgap by default. impact: too high first, then pages where the brand tells more.groupenumproduct: one row per product, with its variants. Those carry no price or verdict.includeenumpages: adds the brand page. Needs group=product.pageintegerperPageinteger422.formatenumcsv: every match of the filter, unpaged, one row per variant.curl "https://api.trawl.me/api/shops/matches?sale=northfold" \
-H "Authorization: Bearer $TRAWL_API_KEY"{
"type": "success",
"message": "shop match list",
"data": [
{
"id": "6a1f3c9e2b7d4e0012ab34cd",
"variantKey": "[\"8841203\"]|4410",
"status": "too_high",
"confidence": "high",
"gap": 34,
"gapPct": 35.8,
…
}
]
}One match
GET /api/shops/matches/:id
A match with both product pages side by side.
Adds to the match
pagesobjectcatalog and brand. null: no page read. Check readable before you use one.listingPointsobjecttotal.fixesobjectA page has gallery, description, factList, sectionTexts and text among its fields.
Section texts stop at 300 characters. text holds the page, up to 7,000.
curl "https://api.trawl.me/api/shops/matches/6a1f3c9e2b7d4e0012ab34cd" \
-H "Authorization: Bearer $TRAWL_API_KEY"{
"type": "success",
"message": "shop match",
"data": {
"id": "6a1f3c9e2b7d4e0012ab34cd",
…
"pages": {
"catalog": { "url": "https://your-shop.example/products/merino-crew-sweater", "readable": true, … },
"brand": {
"url": "https://northfold.example/crew",
"readable": true,
"photos": 6,
"facts": 5,
"sections": ["composition", "care"],
"sectionTexts": { "composition": "100% merino wool." },
…
}
},
"listingPoints": {
"sections": 1,
"photos": 2,
"resolution": 0,
"facts": 1,
"fixes": 8,
"keyFacts": 2,
"total": 12
},
"fixes": { … }
}
}List fixes
GET /api/shops/fixes
The lines to add to your product pages, quoted from the brand. One entry per pair of pages.
Parameters
productIdstringsinceISO date422.pageintegerperPageinteger422.formatenumcsv: one row per line to add, unpaged.Each change
kindenumconflict, missing_info, longer_description or missing_photo.sectionstringlinestringsourcestringcurrentstringconflict only.whystringurlstringmissing_photo.curl "https://api.trawl.me/api/shops/fixes?since=2026-11-03" \
-H "Authorization: Bearer $TRAWL_API_KEY"{
"type": "success",
"message": "shop fixes",
"data": [
{
"productId": "8841203",
"handle": "merino-crew-sweater",
"url": "https://your-shop.example/products/merino-crew-sweater",
"title": "Merino crew sweater",
"vendor": "Northfold",
"brandUrl": "https://northfold.example/crew",
"at": "2026-11-03T07:12:00.000Z",
"variants": [{ "variantId": "4410", "sku": "NF-CREW-M", "barcode": "3700000000013" }],
"changes": [
{
"kind": "missing_info",
"section": "Composition",
"line": "Composition: 100% merino wool.",
"source": "100% merino wool.",
"current": null,
"why": "Buyers look for it."
},
{
"kind": "missing_info",
"section": "Care",
"line": "Hand wash cold.",
"source": "Hand wash cold.",
"current": null,
"why": "Only the brand says it."
},
…,
{ "kind": "missing_photo", "url": "https://northfold.example/crew-back.jpg" }
]
}
]
}The match object
Each row says how old it is. The list leaves out the fix lines.
Fields
variantKeystringproductIdstringvendorstringstatusenumreasonenummatchedByenumconfidenceenumnull. Confidencecatalogobjectcrossed is your crossed-out price. seenAt: last read of your catalog.brandobjectfull is the higher of price and compareAt. seenAt: last time we saw it. available: false when sold out at the brand, no field when its page does not say.brandCheaperobjectgapnumbergapPctnumberlistingenumfirstTooHighAtdatecheckedAtdate{
"id": "6a1f3c9e2b7d4e0012ab34cd",
"variantKey": "[\"8841203\"]|4410",
"productId": "8841203",
"vendor": "Northfold",
"status": "too_high",
"reason": null,
"matchedBy": "barcode",
"confidence": "high",
"catalog": {
"title": "Merino crew sweater",
"variantTitle": "M",
"sku": "NF-CREW-M",
"barcode": "3700000000013",
"url": "https://your-shop.example/products/merino-crew-sweater",
"price": 59,
"crossed": 129,
"currency": "EUR",
"seenAt": "2026-11-03T06:02:00.000Z",
"sale": {
"handle": "northfold",
"title": "Northfold",
"position": 0,
…
},
"image": "https://your-shop.example/crew.jpg"
},
"brand": {
"name": "Northfold",
"title": "Crew sweater in merino",
"variantTitle": "M",
"sku": "NF-CREW-M",
"barcode": "3700000000013",
"url": "https://northfold.example/crew",
"image": "https://northfold.example/crew.jpg",
"price": 95,
"compareAt": null,
"full": 95,
"currency": "EUR",
"seenAt": "2026-11-02T05:40:00.000Z",
"gone": false
},
"brandCheaper": null,
"gap": 34,
"gapPct": 35.8,
"listing": "brand_better",
"firstTooHighAt": "2026-10-28T07:10:00.000Z",
"checkedAt": "2026-11-03T07:04:00.000Z"
}Statuses
too_highoknot_foundnot_comparablename_onlycurl "https://api.trawl.me/api/shops/matches?status=too_high" \
-H "Authorization: Bearer $TRAWL_API_KEY"Reasons
Why a match has no price verdict.
brand_not_coverednot_at_brandmatch_missedno_refsku_not_on_sitename_onlyvariant_unclearpack_mismatchstarting_pricesecond_handother_productbrand_gone{
"status": "not_found",
"reason": "not_at_brand",
"matchedBy": null,
"confidence": null,
"gap": null
}Cheaper at the brand
too_high compares your crossed-out price with the brand's full price. brandCheaper compares your sale price with the brand's current price. It adds no status: a row is ok or too_high and can be cheaper at the brand as well.
A row counts when
ok or too_high, so a pack, a starting price or an item the brand no longer sells never counts.brand.available is not false.too_high.gapEur is the difference, gapPct its share of your price, seenAt the date we read the brand's price: a promotion can have ended since.
With group=product, a product is cheaper when one of its listed variants is, and its figure is the biggest gap.
curl "https://api.trawl.me/api/shops/matches?cheaper=true" \
-H "Authorization: Bearer $TRAWL_API_KEY"{
"status": "ok",
"catalog": { "price": 80, … },
"brand": { "price": 60, … },
"brandCheaper": {
"gapEur": 20,
"gapPct": 25,
"seenAt": "2026-11-02T05:40:00.000Z"
}
}How a match is made
Strongest proof first, against the brand's own site. One market and currency: France, euros.
barcodeskusku-stem, sku-segsku-sizesku-withinname-size, name-pricename, name-fuzzy, name-modelA reference match is not enough alone. When the two items look different, Pinch reads both, and only a clear yes keeps the pair.
Two pack sizes, "from" prices, professional and subscription prices, and a brand price of 0 are never judged.
curl "https://api.trawl.me/api/shops/matches?search=NF-CREW-M" \
-H "Authorization: Bearer $TRAWL_API_KEY"Confidence
A level, not a percentage. You set your own rule for what reaches a product page.
highmediumlownullWith group=product, a product's confidence is the lowest of the variants listed.
curl "https://api.trawl.me/api/shops/matches?confidence=high&status=too_high" \
-H "Authorization: Bearer $TRAWL_API_KEY"Page verdicts
Which product page tells the buyer more.
brand_betterfixes.sameshop_betternullSize advice, usage tips, warnings and claims are left out. "Made in China" is never suggested.
curl "https://api.trawl.me/api/shops/matches?listing=brand_better&sort=impact" \
-H "Authorization: Bearer $TRAWL_API_KEY"CSV
Add format=csv to matches or fixes. Unpaged. A scraped text that starts like a formula stays text.
curl "https://api.trawl.me/api/shops/matches?sale=northfold&format=csv" \
-H "Authorization: Bearer $TRAWL_API_KEY" \
-o matches.csvproduct_id, vendor, status, reason, matched_by,
title, variant, sku, barcode, price, crossed, url,
brand, brand_title, brand_price, brand_compare_at,
brand_full, brand_url, brand_seen_at, brand_gone,
gap_eur, gap_pct, listing, too_high_since,
checked_at, confidence, brand_available,
cheaper_eur, cheaper_pct