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

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

ParameterTypeDescription
querystring, requiredSearch text, URL-encoded.
sourcesstringComma-separated source identifiers from GET /search/sources.
limitintegerMaximum results per source, 1 to 100. Default 20.
countrystringISO 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.

FieldTypeDescription
titlestringProduct title as the source listed it.
retailer_namestringThe store the listing is at.
urlstringThe listing URL.
preferred_urlstringThe best URL to send a shopper to: a direct retailer page where one is known.
price_centsintegerPrice in the currency's minor unit.
price_displaystringPrice formatted for display, for example "$279.99".
price_currencystringISO 4217 currency code.
image_urlstringProduct image.
brandstringBrand, where the source gives one.
upcstringUPC / barcode, where known.
asinstringAmazon ASIN, where known.
ratingnumberAverage rating from 0 to 5, where shown.
review_countintegerNumber of reviews, where shown.
in_stockbooleanAvailability, where shown.
sourcestringIdentifier of the source that found this listing (see GET /search/sources).
other_sourcesobject[]The same product found by other sources: source, title, price_cents, price_display, url, image_url, retailer_name.
best_price_centsintegerLowest price across this result and its other_sources.
best_price_retailer_namestringThe store with the lowest price.
best_price_sourcestringIdentifier of the source that found the lowest price.

Request metadata

FieldTypeDescription
data.querystringThe query as searched (trimmed).
data.intent.detectedstringThe query category: electronics, groceries, digital_music, digital_video, digital_games, digital_books, books, home_goods, apparel or general.
data.intent.sources_usedstring[]Sources queried for this request.
data.metadata.total_resultsintegerNumber of merged results.
data.metadata.sources_completedstring[]Sources that answered (including with no results).
data.metadata.sources_failedstring[]Sources that errored or timed out.
data.metadata.sources_unavailablestring[]Sources requested or routed to that are not available right now and were not queried.
data.metadata.timing_msintegerTotal time for the request.
meta.request_idstringQuote this when you contact us about a request.
meta.usage.requests_todayintegerRequests used today.
meta.usage.requests_remainingintegerRequests left today.
meta.usage.rate_limit_resetstringWhen 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.

categoryWhat it covers
catalogShopSavvy catalog. Products already in ShopSavvy's catalog, matched by identifier or full text, with the retailer offers ShopSavvy holds for them.
retailerMajor retailers. Product listings searched at large US retailers directly, with price, availability, ratings and review counts where the retailer shows them.
web_searchWeb search. General web search results that point at retailer product pages, which widens coverage to stores no retailer source covers.
answer_engineAI answer engines. Retailer product pages that AI answer engines cite for the query.
digital_mediaDigital media. Music, movies and TV, games and books in digital form, used when the query is about digital media.
groceryGrocery. Grocery and household items, used when the query is about groceries.
independent_storesIndependent 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_codeHTTPMeaning
auth_required401No API key. Send Authorization: Bearer <key> (or the api_key query parameter).
invalid_key_format401The key is not a ShopSavvy key (ss_live_ or ss_test_ followed by 32 letters and digits).
invalid_key401The key is unknown or has been revoked.
scope_denied403The key is valid but does not have Search API access. Ask us to enable it.
no_subscription403Your account has no active Search API subscription, or it has expired.
rate_limit_exceeded429Over your per-minute or per-day limit. retry_after gives the seconds to wait; meta says which limit and when each resets.
invalid_request400query is missing or empty.
no_sources400None of the requested or routed sources are available. The message lists them; check GET /search/sources.
streaming_disabledstream eventStreaming is not enabled on your subscription. Use POST /search, or ask us to enable streaming.
source_failedstream eventOne source failed or timed out. Results from the other sources keep coming.
auth_error500Our authentication check failed. Retry; contact us with the time if it persists.
internal_error500Something 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.