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

# Place Search

> Search for places around the user and get place cards, with optional web results.

For AI agents: [docs.octen.ai/capabilities/place-search.md](https://docs.octen.ai/capabilities/place-search.md)

Finding a place to go means checking a map for what is nearby, a website for the opening hours, and local food guides for what is worth trying. A model working from web pages has to read all of them, and spend tokens on every one.

Octen Place Search returns the places that match the query as place cards, with the address, coordinates, contact details, opening status, and rating already in fields.

Pass the location of the request with every query. Without it, a query that names no place is not limited to any area.

For the full list of parameters, see the [Place Search API reference](https://docs.octen.ai/api-reference/place-search.md).

## Why Octen Place Search

* **Structured place data.** Each place comes back as a card: address, coordinates, phone, website, opening hours, and rating.
* **Searches around the user.** Pass the user's coordinates or city, and the search runs around it. With coordinates, every card also carries its distance, and a radius keeps only the places within it.
* **Web results in the same call.** Turn on web results to get pages about the same query alongside the cards.

For general web pages, use [Web Search](https://docs.octen.ai/capabilities/web-search.md). For companies and people, use [Business Search](https://docs.octen.ai/capabilities/business-search.md).

## How It Works

1. Send a query with the location of the request: the user's coordinates or city.
2. Octen finds the places that match the query around that location, or in the place the query names.
3. The response returns a place card for each place, plus ranked web results when you turn them on.

## Scenarios

### Find places nearby

Pass the user's coordinates. Each card carries its distance in meters, and the radius keeps only the places within it.

```bash theme={null}
curl -X POST https://api.octen.ai/place-search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "coffee shops",
    "latitude": 37.788,
    "longitude": -122.4075,
    "radius": 1000
  }'
```

### Search by city

When you know only the user's city, pass it as the user location. Distance is returned only with coordinates.

```json theme={null}
{
  "query": "coffee shops",
  "user_location": {
    "type": "approximate",
    "city": "Austin",
    "region": "Texas",
    "country": "US",
    "timezone": "America/Chicago"
  }
}
```

### Search another area

When the user asks about somewhere else, name the place in the query. The search covers that place instead of the user's location.

```json theme={null}
{
  "query": "ramen restaurants in Shinjuku, Tokyo",
  "latitude": 37.788,
  "longitude": -122.4075
}
```

### Add web results

Get the place cards and the pages that discuss them in one call. The location applies to web results too, and highlights are on by default.

```json theme={null}
{
  "query": "family-friendly restaurants",
  "user_location": {
    "type": "approximate",
    "city": "Chicago",
    "region": "Illinois",
    "country": "US",
    "timezone": "America/Chicago"
  },
  "web_search": { "enable": true, "count": 5 }
}
```

### Get the original text

For the complete page text of the web results, turn on full content.

```json theme={null}
{
  "query": "museums",
  "latitude": 51.5194,
  "longitude": -0.127,
  "web_search": {
    "enable": true,
    "full_content": { "enable": true, "max_tokens": 4000 }
  }
}
```

The full content of the first 10 results per search is free; only additional results are billed.

## Next Steps

> **[Try in Console](https://octen.ai/platform/place-search)**
>
> Run Place Search live in the Octen console.

> **[Place Search API Reference](https://docs.octen.ai/api-reference/place-search.md)**
>
> Full request/response schema.

***

Last modified on October 26, 2026


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.