# Search places

### Search places

`POST /api/v1/places/search`

Operation ID: `searchPlaces`

Build a list of businesses and locations. Pass a query for text search, or a location (and optional type) for nearby search. Page text-search results with the returned cursor. The response includes remainingUsage.

**Request body** (required)

- `query` (string, optional): Free-text query, e.g. "dentists in Munich". Required unless `location` is set.
- `location` (object, optional): Center point. Required unless `query` is set. Without a query this is a nearby search inside the radius.
  - `latitude` (number, required)
  - `longitude` (number, required)
- `radiusMeters` (integer, optional): Radius when `location` is set. Defaults to 50 km. Nearby search stays inside this circle; text search is biased toward it.
- `type` (string, optional): A Google Places type such as `restaurant` or `dentist`.
- `language` (string, optional): BCP-47 language code for names and addresses.
- `region` (string, optional): CLDR region code that biases results, e.g. `DE`.
- `cursor` (string, optional): Text-search pagination cursor. Nearby search does not page.
- `limit` (integer, optional)

**200**: Place hits, an optional cursor, and the remaining Places calls.

- `hits` (object[], required)
- `cursor` (string | null, required)
- `remainingUsage` (object, required): Remaining Search Places calls for this workspace, in the same shape as a connected account remainingUsage.
  - `hour` (integer | null, required): Remaining hourly allowance. Null because Places has no hourly cap.
  - `day` (integer, required): Calls left before the next cap. The fewer of the calls left today and the calls left this month.
  - `week` (integer | null, required): Remaining weekly allowance. Null because Places has no weekly cap.
- `requestId` (string · uuid, required): Id of this request, for support and troubleshooting

**Errors**

- `400`: Bad request
- `401`: Unauthorized: missing or invalid API key
- `403`: Forbidden
- `404`: Not found
- `422`: Invalid request payload