Skip to main content
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
  }
}
'
{
  "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": {
    "total_results": 1,
    "version": "v0.1.0"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer token in the format: Bearer YOUR_API_KEY

Headers

​
apiKey
string | null

Query Parameters

​
org_slug
string | null

Body

application/json
​
location_filter
LocationFilter · object
required

Location filter for geographic search.

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)
​
names

Place name(s) to search for

Example:
["Starbucks", "Peet's Coffee"]
​
categories

Category/categories to filter by. 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'). We will match against all the child categories of parent categories.

Example:
["cafe", "restaurant"]
​
source
enum<string>
default:reprompt

Data source to search: reprompt (default), overture, or foursquare.

Reprompt supports multiple backends for finding places:

  • Foursquare OS Places - amazing open data project with 100M+ global POIs (Apache 2.0 license)
  • Overture Places - open map data from the Overture Maps Foundation with 64M+ places (CDLA Permissive 2.0)
  • Our index of places we picked up from crawling the web

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.

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")
  • We will match against all the child categories of parent categories.
Available options:
reprompt,
overture,
foursquare
​
destination
Destination · object

Destination configuration for the search results. Specify 'workbook' to export to a Reprompt workbook table, or 'dataset' to export to Reprompt batches. If omitted, results are returned directly in the response.

Response

Successfully found places

Unified response model for find_places endpoint.

Results are always returned (up to 500 places). The metadata structure varies based on destination:

  • Default (no destination): Basic metadata with total_results and version
  • dataset: Includes datasets info with batch links
  • workbook: Includes workbook info with table details
​
results
FindPlaceItem · object[]
required

Array of found places (up to 500)

​
metadata
FindPlacesMetadataDataset · object
required

Metadata when destination is 'dataset'.