Find Places

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

POST /find-places

cURL

lat_lon_radius

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

200

nearby_results

{
  "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": "[phone]",
      "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)

Show child attributes

names · string[] string

Place name(s) to search for

Example:

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

categories · string[] string

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.

Show child attributes

Response

200

application/json

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)

Show child attributes

metadata · FindPlacesMetadataDataset · object · required

Metadata when destination is 'dataset'.

FindPlacesMetadataDataset

FindPlacesMetadataWorkbook

FindPlacesMetadataDefault

Show child attributes