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

# Place Search API Best Practices

> Request fields, queries and locations for the Parallel Place Search API

For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](https://docs.parallel.ai/llms-full.txt). You may also fetch any page as Markdown by appending `.md` to its URL or sending `Accept: text/markdown`.

For Search and Extract, use `/v1/search` and `/v1/extract` for all new integrations and agent tool calls. Use `/v1beta/search` and `/v1beta/extract` only when maintaining an existing integration that already uses them. The request bodies changed too: on `/v1/extract`, `full_content`, `fetch_policy` and `excerpt_settings` go inside `advanced_settings`, and sending the v1beta top-level `excerpts`, `full_content` and `fetch_policy` to `/v1/extract` returns a 422. Do not substitute `/v1` for the documented FindAll or Ingest endpoint paths.

Send the Place Search API what to find and where to look. The API returns matching places,
best first, each with the best known URL for the place when it has one.

## Request Fields

Send requests to `POST https://api.parallel.ai/v1/places/search` with your API key in the
`x-api-key` header. `query` is required, plus one place to search: `location`, or `latitude` and
`longitude`, or both. All other fields are optional. The API rejects unknown fields.

| Field | Type | Notes | Example |
| - | - | - | - |
| query | string | What to find: a kind of place, a product or service, or a place's name. 1 to 200 characters. | `"tacos"`, `"24 hour pharmacy"`, `"Blue Bottle Coffee"` |
| location | string | A single place to search: a city, neighborhood, address, landmark or postal code. 2 to 200 characters. One location per request. A comma-separated list of places is not supported. | `"Mission District, San Francisco"`, `"94110"`, `"Times Square, New York"` |
| latitude, longitude | number | The search center. Set both or neither. Send with `location` for the most results. | `37.7793`, `-122.4193` |
| max\_distance\_km | number | Only places within this many km of the search center, up to 200. Defaults to a radius that fits `location`, up to 25 km. | `2` |
| open\_now | boolean | Only places open at request time, in each place's own time zone. Defaults to `false`. | `true` |
| max\_results | int | Maximum number of results to return, from 1 to 20. Defaults to 10. Any mode can return fewer when fewer places match. Values above 20 are reduced to 20 with a warning. | `20` |
| mode | string | `advanced` or `fast`. Defaults to `advanced`. See [Modes](https://docs.parallel.ai/place-search/modes.md). | `"fast"` |
| session\_id | string | A string that groups related calls for one task. Up to 1000 characters. The API returns the value you provide, or generates one when you omit it. | `"session_<uuid>"` |
| client\_model | string | The model that creates the request and consumes the results. | `"claude-opus-5"` |

### Example

```json theme={"system"}
{
  "query": "tacos",
  "location": "Mission District, San Francisco",
  "open_now": true,
  "max_results": 20,
  "mode": "advanced"
}
```

## Writing Queries and Locations

* **Put what in `query` and where in `location`.** Send `"query": "tacos"` with
  `"location": "Mission District, San Francisco"`, not `"query": "tacos in the Mission"`. The location sets the
  search area.
* **Send one `location` per request.** The field is a single place. A comma inside the name is
  part of that place (`"Cambridge, MA"`). A comma-separated list of places is not supported,
  even within the 200-character limit. Search each place in its own request.
* **Name the kind of place, or the place itself.** Short queries work best: `"climbing gym"`,
  `"vegan bakery"`, `"Fitzwilliam Museum"`. Leave out words like "best" or "cheap", and use
  `open_now` instead of "open now".
* **Make the location specific enough to place on a map.** Add the city or region to
  neighborhood names: `"Le Marais, Paris"` rather than `"Le Marais"`. Postal codes and street
  addresses work too.
* **Add the region or country to names that exist in several places.** Send
  `"Cambridge, UK"` or `"Cambridge, MA"`, not `"Cambridge"`.
* **Set `max_distance_km` to widen or narrow the search.** Send `1` for walking distance, or a
  larger value to search beyond a small town.
* **Send both `location` and coordinates when you have them.** `latitude` and `longitude` set
  the center exactly, which is best for "near me" searches. `location` helps find more places
  nearby. Keep the two consistent: send the neighborhood or city that contains the point.