Place Search API Quickstart

The Place Search API finds places of interest matching a query in or near a location. Results include the address, phone number, coordinates, distance from the search center, price level, weekly opening hours, and a rating tier. Use Place Search when an agent or application needs to find, compare or recommend local businesses and points of interest: “coffee near Union Square”, “24 hour pharmacy in 94110”, or “museums in Cambridge, UK that are open now”.

1. Set Up Prerequisites

Generate your API key on Platform, then export it:

export PARALLEL_API_KEY="PARALLEL_API_KEY"

The Python example below uses requests (pip install requests).

2. Execute Your First Place Search

Send what to find as query and where to look as location: one city, neighborhood, address, or postal code per request. To search around a point instead, send latitude and longitude.

Sample Request

curl https://api.parallel.ai/v1/places/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "query": "tacos",
    "location": "Mission District, San Francisco",
    "max_results": 5
  }'

import os

import requests

response = requests.post(
    "https://api.parallel.ai/v1/places/search",
    headers={"x-api-key": os.environ["PARALLEL_API_KEY"]},
    json={
        "query": "tacos",
        "location": "Mission District, San Francisco",
        "max_results": 5,
    },
    timeout=60,
)
response.raise_for_status()

for place in response.json()["results"]:
    rating = f" ({place['rating']})" if "rating" in place else ""
    url = place.get("url", "no link")
    print(f"{place['name']}{rating}: {url}")
    if "address" in place:
        print(f"  {place['address']}")

async function main() {
    const response = await fetch("https://api.parallel.ai/v1/places/search", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": process.env.PARALLEL_API_KEY!,
        },
        body: JSON.stringify({
            query: "tacos",
            location: "Mission District, San Francisco",
            max_results: 5,
        }),
    });
    if (!response.ok) {
        throw new Error(`Place Search failed: ${response.status} ${await response.text()}`);
    }

    const { results } = await response.json();
    for (const place of results) {
        const rating = place.rating ? ` (${place.rating})` : "";
        console.log(`${place.name}${rating}: ${place.url ?? "no link"}`);
        if (place.address) console.log(`  ${place.address}`);
    }
}

main().catch(console.error);

This request uses the default advanced mode. Add "mode": "fast" for the lowest latency and cost. See Place Search Modes.

Request Options

open_now: only places open at request time, in each place’s own time zone. Places with unknown hours are left out.
max_distance_km: only places within this distance of the search center.
max_results: up to 20 (default 10).
mode: advanced (default) or fast.

Without max_distance_km, the search radius fits the location, up to 25 km. See Best Practices for every request field.

Sample Response

The API returns a JSON response with the following structure. The results array below is shortened to one place. Fields that are not known for a place, such as its rating, are left out.

{
  "search_id": "search_e3584cbd6545a489f43cff43737d52cc",
  "session_id": "session_e3584cbd6545a489f43cff43737d52cc",
  "results": [
    {
      "url": "https://www.laoaxaquenaca.com/",
      "name": "La Oaxaqueña",
      "address": "2128 Mission St, San Francisco, CA 94110",
      "phone": "(415) 714-9119",
      "latitude": 37.7629157,
      "longitude": -122.4197557,
      "distance_km": 0.22,
      "rating": "excellent",
      "opening_hours": {
        "monday": [{"opens": "11:00", "closes": "02:30"}],
        "tuesday": [{"opens": "11:00", "closes": "02:30"}],
        "wednesday": [{"opens": "11:00", "closes": "02:30"}],
        "thursday": [{"opens": "11:00", "closes": "02:30"}],
        "friday": [{"opens": "11:00", "closes": "02:30"}],
        "saturday": [{"opens": "11:00", "closes": "02:30"}],
        "sunday": [{"opens": "11:00", "closes": "02:30"}]
      },
      "timezone": "America/Los_Angeles",
      "open_now": true
    }
  ],
  "usage": [{"name": "sku_search", "count": 1}]
}

Next Steps

Best Practices: every request field, and how to write queries and locations
Place Search Modes: choose between fast and advanced
Pricing: per-request cost for each mode
Rate Limits: default quotas per product

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

Place Search API Quickstart

1. Set Up Prerequisites

2. Execute Your First Place Search

Sample Request

Request Options

Sample Response

Next Steps

​1. Set Up Prerequisites

​2. Execute Your First Place Search

​Sample Request

​Request Options

​Sample Response

​Next Steps

1. Set Up Prerequisites

2. Execute Your First Place Search

Sample Request

Request Options

Sample Response

Next Steps