Build on the Partner API

Searching the catalog

Nobody reads documentation.

Here are the instructions for your agent. Give it this prompt: it reads the guides and the API contract, then walks you through the integration step by step, what to do, where and how.

Download agent instructions

This guide is for builders of a website, app or agent on the Partner API.

To answer one shopper's request, search: one call returns the best matching offers in your inventory scope, ranked the way groupon.com ranks them. Walk the catalog only when your site renders the whole catalog from its own copy (Syncing the catalog).

Search

bash

curl -s "https://api-core.livingsocial.com/partner_storefront/products/search?q=massage%20in%20Chicago&country=US&limit=5" \
  -H "Authorization: Bearer $GROUPON_API_KEY"

Parameter	Meaning
`q`	Required: the shopper's words, 1 to 200 characters. A place in them is understood (`massage in Chicago`)
`country`	Required: `US`
`city`	A US city as people write it (`Austin`, `Austin, TX`), used when the words name no place
`near`	`lat,lng,radiusKm`, radius at most 200: closer offers rank higher
`maxPrice`	Whole US dollars: only offers with an option at or under it
`state`, `category0`, `category1`, `category2`	As on the walk, inside your scope
`limit`	1 to 50, 10 when absent; a conversation needs 3 to 5
`cursor`	The previous page's `nextCursor`

The answer holds data (each item is the same product a walk returns, plus distanceKm when you sent near), nextCursor, hasMore, total (Groupon's estimate of every match, not a count) and asOf. Only offers on sale today are returned, never one that needs a booked time slot.

Rules

Name a place, in the words (massage in Chicago), with city or with near: a search that names none is ranked around Chicago, and a scope limited to other states may then find nothing.
Send the same parameters on every page; only cursor changes. A page can be short while hasMore is true. A cursor lapses after 15 minutes: search again without it.
Each search counts once against your 600 requests a minute, and against 120 searches a minute per storefront. Past either, the answer is RATE_LIMITED with retryAfterSeconds.
UPSTREAM_UNAVAILABLE means the ranking could not answer: retry with backoff.
Read one offer again before you show it with GET /partner_storefront/products/{productId}. An offer that is gone or outside your scope answers INVALID_PRODUCT_ID.
Results come from LivingSocial for Agents' copy of Groupon's catalog, refreshed every two hours. The cart checks price and availability live, so send expectedPrice as always.