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'.