Travel and places · SearchApi

places.search

Searches structured place listings and retrieves original contact, location, category and opening-hour information. Strict radius and rating filters require source evidence; a listing does not confirm booking capacity or suitability.

Operation: POST /v1/capabilities/places.search/execute
operationId: executePlacesSearch
Typical credits: 4
Search deadline: 15 s server-side
Paging: page
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: $0.004 per fetched provider page or fresh place detail; cached details are free. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/places.search/execute, JSON, validated against the PlacesSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of places.search
Field	Type	Required	Default	Constraints and description
query	string	yes		min length 1, max length 300
location	object	no
location.lat	number	yes		min -90, max 90
location.lon	number	yes		min -180, max 180
radius_m	number	no		min 62, max 50000 Strict distance from location; requires location and excludes results without coordinates.
country	string	no		pattern ^[A-Za-z]{2}$
language	string	no		min length 2, max length 12
min_rating	number	no		min 0, max 5
open_now	boolean	no		Require an explicit open or closed provider state at observation time; unknown states do not qualify.
num	integer	no	10	min 1, max 20

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

query must not be blank.
radius_m requires location.

Examples

Surf lessons nearby

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/places.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"surf schools Carcavelos Portugal","num":5}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the PlacesSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of places.search
Key	Type	Presence	Note
address	string	when the source has it
phone	string	when the source has it
type	string	when the source has it
types	string[]	when the source has it
open_state	string	when the source has it
hours	string	when the source has it
website	string	when the source has it
rating	number	when the source has it
reviews	integer	when the source has it
price_level_label	string	when the source has it
coordinates	object	when the source has it
distance_m	number	when the source has it	Only with `location`.
open_now	boolean	when the source has it
source	string	always
fetched_at	string	always

Caveats

Paging stops at 20 provider pages; a filtered page can be empty while has_more is true.

Follow-ups

Paging: Provider page number; more fetches the next page from the source. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (PlacesSearchUpdateParams).
Record actions:
- details: Place contacts, hours, location and source-reported amenities.
Detail behaviour: First details call fetches from the provider (billed as stated); repeats are cached and free. details is a fresh place request: $0.004; repeated calls are cached.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/places.search/execute", {
  body: {
    "query": "surf schools Carcavelos Portugal",
    "num": 5
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);