Search API reference
The Universal Product Search API takes a shopper's keyword query, searches the sources that fit it in parallel, and returns one merged list of matching products sorted by price, with every store each product was found at. It is sold on a quote, by monthly query volume, with access set up per company. Request access. For lookups by barcode, ASIN or URL with price history, use the Data API.
Base URL and authentication
All endpoints live under https://api.shopsavvy.com/enterprise/api/v1 and return JSON (the stream returns text/event-stream).
Send your ShopSavvy API key as Authorization: Bearer <key> (an api_key query parameter also works, for clients that cannot set headers, such as a browser EventSource). Keys start with ss_live_ or ss_test_. The key needs Search API access, and your account needs an active Search API subscription; both are set up when your contract starts.
Rate limits
Each subscription has a per-minute and a per-day request limit, set in your contract. Every successful response reports the daily position in meta.usage, and GET /usage shows both limits. Over a limit you get HTTP 429 with error_code rate_limit_exceeded, retry_after in seconds, and meta naming the limit hit and when each resets. Wait retry_after seconds before retrying.
Endpoints
POST /search
Search every relevant source and get one merged, price-sorted result list.
Classifies the query (electronics, groceries, books, apparel and so on), picks the sources that fit, queries them in parallel and merges the same product found by several sources into one result with every price it was seen at. Results are sorted by price. The call returns when every source has answered or timed out.
JSON body
| Parameter | Type | Description |
|---|---|---|
query | string, required | What the shopper typed: a product name, brand and model, or a description. |
sources | string[] | Source identifiers from GET /search/sources to use instead of automatic routing. Unknown identifiers are ignored; known but unavailable ones are reported in metadata.sources_unavailable. |
limit | integer | Maximum results per source, 1 to 100. Default 20. |
timeout_ms | integer | How long to wait for each source, 5,000 to 60,000 ms. Default 30,000. A source that runs out of time is listed in metadata.sources_failed. |
country | string | ISO 3166 two-letter country code for sources that support a marketplace or shipping country. Default "us". Anything that is not two letters is treated as "us". |
curl -X POST https://api.shopsavvy.com/enterprise/api/v1/search \
-H "Authorization: Bearer $SHOPSAVVY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "sony wh-1000xm5", "limit": 10}'GET /search/stream
The same search as Server-Sent Events, so results render as each source answers.
Takes the same inputs as POST /search as query parameters and streams events: routing first, then source_results and merged_update as each source answers, then complete with the same payload as POST /search. Streaming is enabled per subscription.
Query parameters
| Parameter | Type | Description |
|---|---|---|
query | string, required | Search text, URL-encoded. |
sources | string | Comma-separated source identifiers from GET /search/sources. |
limit | integer | Maximum results per source, 1 to 100. Default 20. |
country | string | ISO 3166 two-letter country code. Default "us". |
curl -N "https://api.shopsavvy.com/enterprise/api/v1/search/stream?query=sony%20wh-1000xm5&limit=10" \
-H "Authorization: Bearer $SHOPSAVVY_API_KEY"GET /search/sources
List the sources your key can use, with each one's category and whether it is available right now.
Returns every source by identifier, with its category (see Source categories), a one-line description and an available flag. Use these identifiers in the sources parameter. Availability can change without notice; a request for an unavailable source is reported, never silently dropped.
curl https://api.shopsavvy.com/enterprise/api/v1/search/sources \
-H "Authorization: Bearer $SHOPSAVVY_API_KEY"GET /usage
Your subscription limits and how much of them you have used.
Returns your per-minute and per-day request limits, whether streaming is enabled, the subscription expiry date, and request counts for today and this month with what remains of today's and this minute's allowance.
curl https://api.shopsavvy.com/enterprise/api/v1/usage \
-H "Authorization: Bearer $SHOPSAVVY_API_KEY"Response
A successful search returns success: true, the merged data.products sorted by price, and metadata about what was searched. Identifiers in angle brackets below stand for values from GET /search/sources.
{
"success": true,
"data": {
"query": "sony wh-1000xm5",
"intent": { "detected": "electronics", "sources_used": ["<source>", "<source>"] },
"products": [
{
"title": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
"retailer_name": "<store>",
"url": "https://...",
"price_cents": 27999,
"price_display": "$279.99",
"price_currency": "USD",
"source": "<source>",
"other_sources": [
{ "source": "<source>", "retailer_name": "<store>", "price_cents": 29999, "price_display": "$299.99", "url": "https://..." }
],
"best_price_cents": 27999,
"best_price_retailer_name": "<store>"
}
],
"metadata": {
"total_results": 1,
"sources_queried": 2,
"sources_completed": ["<source>", "<source>"],
"sources_failed": [],
"sources_unavailable": [],
"timing_ms": 4210
}
},
"meta": {
"request_id": "es_...",
"usage": { "requests_today": 12, "requests_remaining": 9988, "rate_limit_reset": "2026-10-13T00:00:00.000Z" }
}
}Product fields
Fields appear when the source provides them. Other fields may appear; they are not part of the contract and can change.
| Field | Type | Description |
|---|---|---|
title | string | Product title as the source listed it. |
retailer_name | string | The store the listing is at. |
url | string | The listing URL. |
preferred_url | string | The best URL to send a shopper to: a direct retailer page where one is known. |
price_cents | integer | Price in the currency's minor unit. |
price_display | string | Price formatted for display, for example "$279.99". |
price_currency | string | ISO 4217 currency code. |
image_url | string | Product image. |
brand | string | Brand, where the source gives one. |
upc | string | UPC / barcode, where known. |
asin | string | Amazon ASIN, where known. |
rating | number | Average rating from 0 to 5, where shown. |
review_count | integer | Number of reviews, where shown. |
in_stock | boolean | Availability, where shown. |
source | string | Identifier of the source that found this listing (see GET /search/sources). |
other_sources | object[] | The same product found by other sources: source, title, price_cents, price_display, url, image_url, retailer_name. |
best_price_cents | integer | Lowest price across this result and its other_sources. |
best_price_retailer_name | string | The store with the lowest price. |
best_price_source | string | Identifier of the source that found the lowest price. |
Request metadata
| Field | Type | Description |
|---|---|---|
data.query | string | The query as searched (trimmed). |
data.intent.detected | string | The query category: electronics, groceries, digital_music, digital_video, digital_games, digital_books, books, home_goods, apparel or general. |
data.intent.sources_used | string[] | Sources queried for this request. |
data.metadata.total_results | integer | Number of merged results. |
data.metadata.sources_completed | string[] | Sources that answered (including with no results). |
data.metadata.sources_failed | string[] | Sources that errored or timed out. |
data.metadata.sources_unavailable | string[] | Sources requested or routed to that are not available right now and were not queried. |
data.metadata.timing_ms | integer | Total time for the request. |
meta.request_id | string | Quote this when you contact us about a request. |
meta.usage.requests_today | integer | Requests used today. |
meta.usage.requests_remaining | integer | Requests left today. |
meta.usage.rate_limit_reset | string | When the daily allowance resets (ISO 8601). |
Streaming events
GET /search/stream sends these Server-Sent Events, in this order:
routing: Sent first: intent, the sources being queried, sources_unavailable and a short reasoning string.source_results: A source answered with results: source, products_count, timing_ms.merged_update: The full merged, price-sorted list so far (products) and stats (total, sources_completed). Replace what you rendered with it.error: Either one source failed (source + error_code source_failed; the stream continues) or the request cannot run (error_code without a source; the stream ends).complete: Last event: the same query, intent, products and metadata as POST /search.
Source categories
By default each query is routed to the sources that fit its category. GET /search/sources lists every source your key can use, with one of these categories and whether it is available right now.
| category | What it covers |
|---|---|
catalog | ShopSavvy catalog. Products already in ShopSavvy's catalog, matched by identifier or full text, with the retailer offers ShopSavvy holds for them. |
retailer | Major retailers. Product listings searched at large US retailers directly, with price, availability, ratings and review counts where the retailer shows them. |
web_search | Web search. General web search results that point at retailer product pages, which widens coverage to stores no retailer source covers. |
answer_engine | AI answer engines. Retailer product pages that AI answer engines cite for the query. |
digital_media | Digital media. Music, movies and TV, games and books in digital form, used when the query is about digital media. |
grocery | Grocery. Grocery and household items, used when the query is about groceries. |
independent_stores | Independent online stores. Products from independent online stores, which widens coverage beyond the large retailers. |
Errors
Errors are JSON: {"success": false, "error": "<message>", "error_code": "<code>"}. Branch on error_code; the message text can change. On the stream, errors arrive as error events with the same error_code.
| error_code | HTTP | Meaning |
|---|---|---|
auth_required | 401 | No API key. Send Authorization: Bearer <key> (or the api_key query parameter). |
invalid_key_format | 401 | The key is not a ShopSavvy key (ss_live_ or ss_test_ followed by 32 letters and digits). |
invalid_key | 401 | The key is unknown or has been revoked. |
scope_denied | 403 | The key is valid but does not have Search API access. Ask us to enable it. |
no_subscription | 403 | Your account has no active Search API subscription, or it has expired. |
rate_limit_exceeded | 429 | Over your per-minute or per-day limit. retry_after gives the seconds to wait; meta says which limit and when each resets. |
invalid_request | 400 | query is missing or empty. |
no_sources | 400 | None of the requested or routed sources are available. The message lists them; check GET /search/sources. |
streaming_disabled | stream event | Streaming is not enabled on your subscription. Use POST /search, or ask us to enable streaming. |
source_failed | stream event | One source failed or timed out. Results from the other sources keep coming. |
auth_error | 500 | Our authentication check failed. Retry; contact us with the time if it persists. |
internal_error | 500 | Something failed on our side. Retry; contact us with meta.request_id if it persists. |
Pricing and access
The Search API is priced by quote, on your monthly query volume. There is no self-serve signup. Tell us what you are building and we reply within one business day.