curl --request POST \
  --url https://api.reprompt.io/v2/find-places \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_filter": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 1000
  }
}'

{
  "results": [
    {
      "place_id": "plc_123",
      "name": "Blue Bottle Coffee",
      "full_address": "315 Linden St, San Francisco, CA 94102",
      "latitude": 37.775,
      "longitude": -122.4195,
      "category_primary": "coffee_shop",
      "category_alternates": [
        "cafe"
      ],
      "phone_number": "+14158964500",
      "website": "https://bluebottlecoffee.com",
      "open_status": "Open",
      "distance_m": 85.2
    }
  ],
  "metadata": {
    "version": "v0.1.0"
  }
}

Places

Find Places

Search for places within a defined geographic area with optional name and category filters.

This endpoint provides a search experience for finding places of interest (POIs) using various location filters and data sources with optimized spatial indexes for fast queries.

Data Sources:

reprompt (default): Reprompt’s proprietary place database
overture: Overture Maps Foundation open data (71M places)
foursquare: Foursquare OS Places open data

Specify the source using the source parameter (defaults to “reprompt”).

Location Filter Types (choose exactly one):

Lat/Lon + Radius: Point-based search within specified radius (default 500m, max 10km)
GeoJSON Geometry: Area-based search within Polygon or MultiPolygon boundaries
Locality: Search within a city/town (requires country_code)
Postal Code: Search within a postal/ZIP code area (requires country_code)
Region: Search within a state/province (requires country_code)

Optional Filters:

Names: Filter by place name(s) using fuzzy matching (supports Unicode characters)
Categories: Filter by category

Category Schemas by Source:

Reprompt & Overture: Use Overture Maps schema (e.g., “cafe”, “restaurant”, “hospital”)
Foursquare: Use Foursquare category taxonomy (e.g., “Food and Beverage > Restaurant”, “Retail > Grocery Store”)
Invalid categories return 403 with suggestions and schema reference
Case-insensitive matching with fuzzy suggestions for typos

Response Details:

Returns up to 500 places per request
Lat/lon searches include distance_m field and sort by distance
Area searches (geometry/region/postal/locality) sort by name, no distance field
All results include: place_id, name, address, coordinates, category, phone, website
open_status field only available for reprompt source

Authentication:

Required: Authorization: Bearer <API_KEY> header (or apiKey/X-API-Key)

POST

find-places

curl --request POST \
  --url https://api.reprompt.io/v2/find-places \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_filter": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 1000
  },
  "names": [
    "Starbucks"
  ],
  "categories": [
    "cafe"
  ]
}'

{
  "results": [
    {
      "place_id": "plc_123",
      "name": "Blue Bottle Coffee",
      "full_address": "315 Linden St, San Francisco, CA 94102",
      "latitude": 37.775,
      "longitude": -122.4195,
      "category_primary": "coffee_shop",
      "category_alternates": [
        "cafe"
      ],
      "phone_number": "+14158964500",
      "website": "https://bluebottlecoffee.com",
      "open_status": "Open",
      "distance_m": 85.2
    }
  ],
  "metadata": {
    "version": "v0.1.0"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

apiKey

string | null

Body

application/json

location_filter

object

required

Location filter (one of: lat/lon/radius, geometry, region, postal_code, locality)

Show child attributes

names

Place name(s) to search for

Examples:

["Starbucks", "Peet's Coffee"]

"Coffee Shop"

Response

Successfully found places

Response model for find_places endpoint.

results

FindPlaceItem · object[]

required

Array of found places

Show child attributes

metadata

object

Metadata about the find places operation

Show child attributes

⌘I

Placematch

V2 API Reference

Authorizations

Headers

Body

Response