> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Product Search

> Find products available at nearby physical retail stores, ranked by proximity and inventory confidence.

Closient returns products at physical stores near a location. Results are
ranked by geographic proximity first, then inventory confidence. Relevance is
a gate (minimum threshold), not the sort key — if nothing local is relevant,
online alternatives surface clearly separated below.

## When to use

The user has a product in mind and wants to know where to buy it near them.
For identity lookups (barcode → product), use `resolve-gtin`. For deep stock
checks on a known GTIN, use `check-product-availability`.

## Endpoint

```
POST /search/api/v1/search/session
Content-Type: application/json

{
  "query": "organic oat milk",
  "latitude": 48.4284,
  "longitude": -123.3656,
  "radius_km": 10
}
```

Session-based so conversational follow-ups can refine constraints without
re-sending the whole query.

## Required inputs

* `query` — free-text
* `latitude`, `longitude` — decimal degrees

## Optional constraints

* `radius_km` — default 10, max 50
* `in_stock` — only include offers reporting in stock
* `certification` — e.g. `organic`, `non-gmo`, `vegan`

## Response

Array of hits; each hit has `product` (gtin, name, brand), `store` (name,
address, distance\_km), `offer` (price, stock\_status, last\_checked\_at). Take
`product.gtin` from any hit and pair with `resolve-gtin` for full detail.

## Refinement

`POST /search/api/v1/search/session/{session_id}/refine` with updated
constraints. Keeps previous results as context.

## Related skills

* `resolve-gtin` — structured product detail for a GTIN from any hit
* `check-product-availability` — deeper stock check for a known GTIN
* `dietary-filter-search` — search with allergen/dietary constraints