---
title: "Place search"
method: POST
path: "/v1/places/search"
tags: ["Place Search"]
---

# Place search

`POST /v1/places/search`

## Request

- Base URL: `https://api.parallel.ai`
- URL: `https://api.parallel.ai/v1/places/search`
- Auth: API key in header `x-api-key`

Searches for places such as restaurants, shops and attractions.

## Request body

- PlaceSearchRequest: Place search request: places matching `query` in or near a location.
  - `query` string, required: What to find, e.g. `ramen`, `24 hour pharmacy` or a place's name.
  - `location` string, nullable: Where to search: a city, neighborhood, address or postal code. Set this, `latitude` and `longitude`, or both; a request with neither is rejected.
  - `latitude` number, nullable: Search center latitude; set with `longitude`.
  - `longitude` number, nullable: Search center longitude; set with `latitude`.
  - `max_distance_km` number, nullable: Only places within this many km of the search center. Defaults to the size of `location` when it is a city or postal code, else 25.
  - `open_now` boolean: Only places open at request time, in each place's own time zone. Places whose open state is unknown are left out.
  - `max_results` integer, nullable: Upper bound on results. Defaults to 10; values above the mode's maximum are reduced to it, with a warning.
  - `mode` 'fast' | 'advanced', nullable: `fast`: lowest latency, with fewer results. `advanced` (default): slower, with more complete results.
  - `session_id` string, nullable: Session identifier that groups related calls made as part of a larger task. Echoed back in the response when nonempty; generated by the server if omitted, null, or empty.
  - `client_model` string, nullable: The model generating this request and consuming the results.

## Response `200`

Successful Response

- PlaceSearchResponse: Place search response.
  - `search_id` string, required: Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`
  - `session_id` string, required: Session identifier, echoed back from the request when nonempty; otherwise generated by the server. Pass it to later calls made as part of the same task.
  - `results` PlaceSearchResult[], required: A list of places, ordered by decreasing relevance.
    - `url` string, nullable: The place's own website (its store page for a chain), else its own social media profile, else a public page about the place, such as a directory or guide page. Omitted when the place has none of these.
    - `name` string, required: Place name.
    - `address` string, nullable: Street address.
    - `phone` string, nullable: Phone number.
    - `latitude` number, nullable: Place latitude.
    - `longitude` number, nullable: Place longitude.
    - `distance_km` number, nullable: Distance from the search center.
    - `rating` 'fair' | 'good' | 'great' | 'excellent', nullable: Rating tier. Possible values are fair, good, great, excellent.
    - `price_level` integer, nullable: 1 (`$`) to 4 (`$$$$`).
    - `opening_hours` WeeklyHours: Opening hours per weekday. An empty list means closed that day; a missing day means unknown.
      - `monday` HourInterval[], nullable
        - `opens` string, required
        - `closes` string, required
      - `tuesday` HourInterval[], nullable
        - `opens` string, required
        - `closes` string, required
      - `wednesday` HourInterval[], nullable
        - `opens` string, required
        - `closes` string, required
      - `thursday` HourInterval[], nullable
        - `opens` string, required
        - `closes` string, required
      - `friday` HourInterval[], nullable
        - `opens` string, required
        - `closes` string, required
      - `saturday` HourInterval[], nullable
        - `opens` string, required
        - `closes` string, required
      - `sunday` HourInterval[], nullable
        - `opens` string, required
        - `closes` string, required
    - `timezone` string, nullable: IANA time zone of `opening_hours`, e.g. `Asia/Tokyo`.
    - `open_now` boolean, nullable: Open at request time, when known.
  - `warnings` Warning[], nullable: Warnings for the search request, if any.
    - `type` 'spec_validation_warning' | 'input_validation_warning' | 'warning', required: Type of warning. Note that adding new warning types is considered a backward-compatible change.
    - `message` string, required: Human-readable message.
    - `detail` object, nullable: Optional detail supporting the warning.
  - `usage` UsageItem[], nullable: Usage metrics for the search request.
    - `name` string, required: Name of the SKU.
    - `count` integer, required: Count of the SKU.

## Other responses

- `422`: Request validation error

## Changes

- **2026-11-05** `eae6def9641f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1/places/search/post.md)

---

[API](https://skmtc.dev/parallel-web/apis/parallel-api.md) - [All operations](https://skmtc.dev/parallel-web/apis/parallel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parallel-web/apis/parallel-api/revisions/eae6def9641f?raw)