How It Works

Neural retrieval, geography, and reranking over synthetic place docs.

Natural-Language Local Discovery

Exa Places treats every place as a rich sparse document: categories, address parts, geo coordinates, website text, amenities, atmosphere, and synthetic business details. A query like vibey coffee shops near Dolores Park in SF can match intent and location even when no exact category says "vibey".

Neural + hybrid retrieval

Hybrid mode blends exact keyword evidence with semantic sparse-doc matches so fuzzy needs like quiet, dog-friendly, or date-night can rank naturally.

Geographic constraints

The API parses addresses, neighborhoods, and cities, then applies a circle filter. Drawn map regions are sent with the same request shape.

Candidate filtering

The service fetches about 30 candidates, filters by geography when present, and keeps enough evidence for the map and result cards.

Reranked explanations

The final order uses semantic fit, distance, and category evidence, then emits a short why-this-matched reason for each place.

Demo Request

The public endpoint streams Server-Sent Events for the search trace, candidate previews, normalized place objects, map bounds, and the final done event.

POST /places-demo/api/search-stream
Content-Type: application/json

{
  "query": "vibey coffee shops near Dolores Park in SF",
  "mode": "hybrid",
  "limit": 10,
  "candidates": 30,
  "rerank": true
}

Stream Events

data: {"type":"plan","steps":[...]}
data: {"type":"step-start","stepIndex":0}
data: {"type":"candidate","candidate":{...}}
data: {"type":"place","place":{...}}
data: {"type":"map-bounds","bounds":{...}}
data: {"type":"done","totalPlaces":10}

Normalized Place

{
  "entityId": "sf-coffee-ritual",
  "name": "Ritual Coffee Roasters Valencia",
  "address": "1026 Valencia St",
  "city": "San Francisco",
  "region": "CA",
  "country": "US",
  "lat": 37.7565,
  "lng": -122.4212,
  "categoryLeaf": ["Coffee Shop", "Cafe"],
  "status": "open",
  "score": 0.944,
  "rank": 1,
  "rerankReason": "Matches vibey, coffee, natural light..."
}

Public Proxy Boundary

The route can proxy a private Places search endpoint throughPLACES_SEARCH_ENDPOINTandPLACES_SEARCH_TOKEN. It validates request shape, tags calls withx-exa-integration: places-demo, applies a per-minute rate limit, and only exposes normalized snippets intended for this demo.