Skip to main content
GET
Find the best price for a product across retailers

Query Parameters

q
string

Search query (product name, keyword, or brand + model). Required unless product_uid or entity_uid is supplied. At least one word needs two or more letters or digits (LG, 3M and HP are enough): a shorter query, such as a single letter, is refused before payment with a 400.

Minimum string length: 1
product_uid
string

Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.

Minimum string length: 1
entity_uid
string

Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.

Minimum string length: 1
country
enum<string>
default:us

Country (us or ca)

Available options:
us,
ca
retailer
enum<string>

Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)

Available options:
amazon,
walmart,
target,
bestbuy,
homedepot,
costco,
ikea,
samsclub,
cvs,
dillards
limit
integer
default:10

Max results to return (default 10, min 1, max 50)

Required range: 1 <= x <= 50
strict
boolean
default:false

When true, restrict the comparison to entity-verified listings of the matched product (match_type 'entity' only). Default false also includes title-match rows — useful for broad queries, but may mix product variants.

publish_id
string

Optional. Pin the answer to a serving publish: pass meta.publish_id from an earlier answer. When the served snapshot has moved on, or cannot be confirmed, the request is answered 409 PUBLISH_CHANGED naming the current publish, before any payment challenge and free. Use it to keep several answers on one snapshot.

Minimum string length: 1
retailer_id
string

A chain by id, from GET /v1/ontology/resolve (a retailer match's id): the chain (seller_norm) whatever lane its listings were scraped through, never a lane. retailer= matches the scrape lane, so a Shopify store's chain can only be asked for by id (#1090). Send it instead of retailer=, not with it.

Pattern: ^retailer:[a-z0-9]{1,64}$

Response

Best price result

query
string
dropped_terms
string[] | null

Non-null when no product matched the query as written and retrieval had to drop these trailing terms to resolve one. Treat the result as an answer to the SHORTENED query: NOBULL Laces black returning these terms as ['black'] means the black variant was not found, only NOBULL Laces.

country
string
currency
string
product_uid
string
entity_uid
string | null
scope
enum<string>

'entity' = prices span the resolved product's cross-platform entity; 'listing' = the product belongs to no multi-member entity, so only its own listing is priced.

Available options:
entity,
listing
member_count
integer

Listings in the entity, as the pipeline groups them. Not the number of offers compared: for a named listing its own store's other listings are in this count and not in best_price / other_prices.

match_suspect
boolean

True when the pipeline has already flagged this entity as welding together materially different products (intra_entity_incoherent). The comparison set — and therefore the headline price — may span variants that are not substitutes; prefer strict=true or a product_uid when this is set.

retailers_compared
integer

Distinct retailers spanned by best_price + other_prices. 1 means no cross-retailer comparison was possible for this product — it is the cheapest listing found, not the cheapest anywhere. Most direct-to-consumer products are sold by a single merchant and can never exceed 1; named-retailer products are roughly 48x likelier to support a real comparison. related_matches are excluded from this count because they are title matches on other entities, not prices for this product.

resolved_product
object

The product this answer is about: the one the request resolved to. It carries the product's image and a description excerpt (detail answers only).

gpc
object | null
brand_presence
object | null

Where the resolved product's BRAND is and is not sold, in country, from serving.brand_retailer_presence (a Shopify store is named by its URL host there; own_store marks the brand's own storefront) and the same denominator /v1/ontology/neighbors uses for an absence. not_observed_at lists chains that have a priced listing on the shelves where the brand lives and none of the brand: say 'not seen at X' only for those. Null when unknown (the table is not yet published, the brand has no row, or the read failed); an empty list means none. Brand-level: brand ids collide across shelves by design (Mars confectionery and Mars petcare are one id), so rows span every shelf the brand is on.

similar_products
object[] | null

The products most like the resolved product, best first (at most 5), from serving.entity_similars: other brands and the same brand together (same_brand says which). Pass entity_uid to best-price to price one. Null when unknown (no entity, the table is not yet published, or the read failed); an empty list means none. A neighbour, not an identity: never evidence two listings are the same product.

headline_price
number | null

The price of the product page the named listing belongs to, by the store's own order of its variants: the store's default variant when it is buyable, otherwise the first buyable variant after it; a sold-out variant never headlines while another is buyable. With every variant sold out it is the first listed variant's price, which cannot be bought today (price_range.variants then counts the sold-out ones). A flagged price or a $0.01 / $99,999 placeholder is never the headline. It is not best_price: that is the named listing's own offer (and the cheapest across stores for the entity), this is the product's. Null when the product has a single listing, so there is no variant to choose between, or no believable price. Present only when the answer names one listing (product_uid, or a q that resolves to one; not entity_uid alone), and only when the product-price feed is switched on and published: otherwise the key is absent, which means not asked, where null means asked and none.

price_range
object | null

The cheapest and dearest believable price among the product's buyable variants (among all priced ones when none is buyable), and how many variants that is over. A sold-out bundle does not stretch the range of a product whose other variants are in stock. Same presence rules as headline_price; null when the product has a single listing or no believable price.

best_price
object
stale_offers
integer

How many of the compared offers (best_price and other_prices) are not current offers. An offer is not current when its last reading said out of stock and that reading is older than its listing's own window: 1.5 times how often we refresh that listing, and never less than 7 days (30 days for a listing with no refresh cadence); Shopify and Google Shopping listings are not judged by that rule. Nor is it current, in stock or not, when its price was observed more than 30 days ago and its retailer's feed (the lane and the chain: a Shopify store is its own) has had no price read in 30 days; a live retailer's older offers keep the rule above. A stale offer is shown, flagged current: false and stale: true with its last_seen_at date and a price_note ("last seen 2026-07-14"), and sorted after the current offers; it is left out of every price statistic and counted in stale_offers.

per_unit
object

The price per unit across the offers compared (best_price and other_prices that are current and unflagged; not related_matches). best_price above is still the lowest PACK price. count is per pack_count; size is per fl oz / oz where an offer states count and size. Withheld below a floor of 3 offers and 30% of those compared (status not_enough_data); unknown until the pipeline's first publish that carries the pack columns.

other_prices
object[]

The other offers compared with best_price: other stores' listings in the entity. For a named listing, its own store's other listings are not among them; with entity_uid alone they are.

Title-matched rows OUTSIDE the resolved entity. Not price comparisons for the same product — a cheaper row here may be a different product, and a genuinely identical SKU can also land here when entity resolution split it across retailers.

lower_uncompared
object | null

A cheaper new in-stock listing in related_matches whose title contains the query, present only when best_price is the only offer compared and the listing's price is at least a third of that offer. It was not part of the comparison: entity resolution left it in another entity (#1374). Null when the headline already compares more than one offer, or no such listing is among the related matches. An accessory or a refurbished unit does not qualify.

meta
object
resolved
object | null