# Searching the catalog

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](/docs/syncing-the-catalog.md)).

## 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.