> ## Documentation Index > Fetch the complete documentation index at: https://syncupai-preview-playground-prefills.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Find Places > Search for places within a defined geographic area with optional name and category filters. ## OpenAPI ````yaml openapi-v2.json post /find-places openapi: 3.1.0 info: title: Reprompt API v2 version: '2.0' servers: - url: https://reprompt-mikhail--reprompt-fastapi-fastapi-app-dev.modal.run/v2 description: V2 API server security: [] tags: - name: Enrichments description: Use AI to enrich place data with various attributes - name: Places description: Find, match, and check existence of places paths: /find-places: post: tags: - Places - Places summary: Find Places description: >- Search for places within a defined geographic area with optional name and category filters. operationId: find_places_find_places_post parameters: - name: org_slug in: query required: false schema: anyOf: - type: string - type: 'null' title: Org Slug - name: apiKey in: header required: false schema: anyOf: - type: string - type: 'null' title: Apikey requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FindPlacesRequest' examples: lat_lon_radius: summary: Search near coordinates description: >- Point-based search within specified radius. Returns results sorted by distance. value: location_filter: latitude: 37.7749 longitude: -122.4194 radius: 1000 names: - Starbucks categories: - cafe geometry_polygon: summary: Search within polygon description: Area-based search within GeoJSON polygon boundaries. value: location_filter: geometry: type: Polygon coordinates: - - - -122.4194 - 37.7749 - - -122.4094 - 37.7749 - - -122.4094 - 37.7849 - - -122.4194 - 37.7849 - - -122.4194 - 37.7749 categories: - restaurant locality: summary: Search within a city description: Search all places within a city/town boundary. value: location_filter: locality: San Francisco country_code: US names: Coffee Shop postal_code: summary: Search within a postal code description: Search all places within a postal/ZIP code area. value: location_filter: postal_code: '94102' country_code: US categories: - retail region: summary: Search within a state/region description: Search all places within a state or province boundary. value: location_filter: region: CA country_code: US categories: - hospital responses: '200': description: Successfully found places content: application/json: schema: $ref: '#/components/schemas/FindPlacesResponse' examples: nearby_results: summary: Results mode - Near coordinates description: >- Default output mode. Returns results sorted by distance with distance_m field. value: 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 polygon_results: summary: Results mode - Within polygon description: >- Area-based search. Results sorted by name, no distance_m field. value: results: - place_id: plc_456 name: McDonald's full_address: 1528 Broadway, New York, NY 10036 latitude: 40.7589 longitude: -73.9851 category_primary: fast_food category_alternates: - restaurant open_status: Open metadata: total_results: 1 version: v0.1.0 '400': description: Invalid input or validation error content: application/json: schema: $ref: '#/components/schemas/FindPlacesErrorResponse' examples: validation_error: summary: Validation error value: error: validation_error message: Invalid request parameters details: - loc: - body - location_filter msg: Must provide one location filter type type: value_error workbook_size_limit: summary: Workbook size limit exceeded description: >- Workbooks are limited to 20,001 rows. Use Dataset mode for larger result sets. value: detail: >- Found 48,668 results but workbooks are limited to 20,001 rows. Please use Dataset mode for large result sets or refine your search filters. no_results: summary: No results found description: Cannot create dataset or workbook with zero results. value: detail: >- No results found. Cannot create workbook with 0 places. Please adjust your search filters. '403': description: Category resolution failed content: application/json: schema: $ref: '#/components/schemas/FindPlacesErrorResponse' '422': description: Processing error content: application/json: schema: $ref: '#/components/schemas/FindPlacesErrorResponse' '500': description: Internal error with error ID for support tracking content: application/json: schema: $ref: '#/components/schemas/FindPlacesErrorResponse' examples: internal_error: summary: Internal error with error ID description: >- An unexpected error occurred. The error ID can be provided to support for troubleshooting. value: error: internal_error message: >- An internal error occurred while processing your request. Please contact support with error ID: 5b15d005-4102-4bbc-a0b8-d01490765276 error_id: 5b15d005-4102-4bbc-a0b8-d01490765276 '502': description: External service error content: application/json: schema: $ref: '#/components/schemas/FindPlacesErrorResponse' security: - bearerAuth: [] components: schemas: FindPlacesRequest: properties: location_filter: $ref: '#/components/schemas/LocationFilter' description: >- 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: anyOf: - items: type: string type: array - type: string - type: 'null' title: Names description: Place name(s) to search for examples: - - Starbucks - Peet's Coffee - Coffee Shop categories: anyOf: - items: type: string type: array - type: string - type: 'null' title: Categories description: >- Category/categories to filter by. **Category Schemas by Source:** **Reprompt & Overture**: Use [Overture Maps schema](https://docs.overturemaps.org/schema/concepts/by-theme/places/) (e.g., 'cafe', 'restaurant', 'hospital'). **Foursquare**: Use [Foursquare category taxonomy](https://docs.foursquare.com/data-products/docs/categories) (e.g., 'Food and Beverage > Restaurant', 'Retail > Grocery Store'). We will match against all the child categories of parent categories. examples: - - cafe - restaurant - cafe source: $ref: '#/components/schemas/PlacematchSource' description: >- Data source to search: reprompt (default), overture, or foursquare. Reprompt supports multiple backends for finding places: - **[Foursquare OS Places](https://opensource.foursquare.com/os-places/)** - amazing open data project with 100M+ global POIs (Apache 2.0 license) - **[Overture Places](https://overturemaps.org/)** - 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](https://docs.overturemaps.org/schema/concepts/by-theme/places/) (e.g., "cafe", "restaurant", "hospital") - **Foursquare**: Use [Foursquare category taxonomy](https://docs.foursquare.com/data-products/docs/categories) (e.g., "Food and Beverage > Restaurant", "Retail > Grocery Store") - We will match against all the child categories of parent categories. default: reprompt destination: $ref: '#/components/schemas/Destination' description: |- 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. include_in_schema: false additionalProperties: false type: object required: - location_filter title: FindPlacesRequest FindPlacesResponse: properties: results: items: $ref: '#/components/schemas/FindPlaceItem' type: array title: Results description: Array of found places (up to 500) metadata: anyOf: - $ref: '#/components/schemas/FindPlacesMetadataDataset' - $ref: '#/components/schemas/FindPlacesMetadataWorkbook' - $ref: '#/components/schemas/FindPlacesMetadataDefault' title: Metadata description: Metadata about the find places operation type: object required: - results - metadata title: FindPlacesResponse description: >- 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 FindPlacesErrorResponse: properties: error: type: string title: Error description: Short machine-readable error type message: type: string title: Message description: Human-readable error message details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Additional error details if available type: object required: - error - message title: FindPlacesErrorResponse description: Error response schema for the Find Places API. LocationFilter: properties: latitude: anyOf: - type: number maximum: 90 minimum: -90 - type: 'null' title: Latitude description: Latitude coordinate examples: - 37.7749 longitude: anyOf: - type: number maximum: 180 minimum: -180 - type: 'null' title: Longitude description: Longitude coordinate examples: - -122.4194 radius: type: integer maximum: 10000 minimum: 0 title: Radius description: Search radius in meters default: 500 examples: - 500 - 1000 geometry: anyOf: - additionalProperties: true type: object - type: 'null' title: Geometry description: GeoJSON geometry object (Polygon, MultiPolygon, etc.) examples: - coordinates: - - - -122.4194 - 37.7749 - - -122.4094 - 37.7749 - - -122.4094 - 37.7849 - - -122.4194 - 37.7849 - - -122.4194 - 37.7749 type: Polygon region: anyOf: - type: string - type: 'null' title: Region description: Region/state name examples: - California - New York postal_code: anyOf: - type: string - type: 'null' title: Postal Code description: Postal/ZIP code examples: - '94102' - '10001' locality: anyOf: - type: string - type: 'null' title: Locality description: City or town name examples: - San Francisco - New York country_code: anyOf: - type: string maxLength: 2 minLength: 2 - type: 'null' title: Country Code description: ISO 3166-1 alpha-2 country code examples: - US - CA - GB additionalProperties: false type: object title: LocationFilter description: >- Location filter for place search. Supports multiple filter types (mutually exclusive): 1. Lat/Lon/Radius: Provide latitude, longitude, and optionally radius (default 500m) 2. Geometry: Provide geometry as GeoJSON object, optionally with country_code to skip reverse geocoding 3. Region: Provide region and country_code 4. Postal Code: Provide postal_code (and optionally country_code) 5. Locality: Provide locality and country_code Note: For geometry searches, providing country_code improves accuracy (especially for countries like Italy or Vietnam where bounding box center method doesn't work well) and reduces latency by skipping reverse geocoding. PlacematchSource: type: string enum: - reprompt - overture - foursquare title: PlacematchSource description: >- Supported data sources for place matching and search. These sources are available across both the placematch API (for entity resolution) and the find-places API (for geographic search). Destination: properties: workbook: anyOf: - $ref: '#/components/schemas/WorkbookDestination' - type: 'null' description: Export results to a Reprompt workbook table dataset: anyOf: - $ref: '#/components/schemas/DatasetDestination' - type: 'null' description: Export results to Reprompt dataset batches additionalProperties: false type: object title: Destination description: >- Destination configuration for find-places results. Specify exactly one destination type (workbook or dataset), or omit for default behavior (return results directly). Each destination supports a 'maximum' parameter to limit the number of results exported. When maximum is set and total_count > maximum, results are randomly sampled from the entire dataset. FindPlaceItem: properties: place_id: type: string title: Place Id description: The ID of the place name: type: string title: Name description: The name of the place full_address: type: string title: Full Address description: The full address of the place latitude: type: number maximum: 90 minimum: -90 title: Latitude description: The latitude of the place longitude: type: number maximum: 180 minimum: -180 title: Longitude description: The longitude of the place category_primary: type: string title: Category Primary description: The primary category of the place category_alternates: items: type: string type: array title: Category Alternates description: The alternate categories of the place phone: anyOf: - type: string - type: 'null' title: Phone description: The phone number of the place website: anyOf: - type: string - type: 'null' title: Website description: The website of the place operating_status: anyOf: - type: string - type: 'null' title: Operating Status description: The operating status of the place distance_m: anyOf: - type: number - type: 'null' title: Distance M description: Distance in meters from search point source: anyOf: - $ref: '#/components/schemas/PlacematchSource' - type: 'null' description: The data source of the place (foursquare, overture, reprompt) type: object required: - place_id - name - full_address - latitude - longitude - category_primary title: FindPlaceItem description: A found place from find_places search results. FindPlacesMetadataDataset: properties: total_results: type: integer minimum: 0 title: Total Results description: Total number of places found version: type: string title: Version description: The API version used default: v0.1.0 datasets: $ref: '#/components/schemas/DatasetsInfo' description: Information about created Reprompt batches type: object required: - total_results - datasets title: FindPlacesMetadataDataset description: Metadata when destination is 'dataset'. FindPlacesMetadataWorkbook: properties: total_results: type: integer minimum: 0 title: Total Results description: Total number of places found version: type: string title: Version description: The API version used default: v0.1.0 workbook: $ref: '#/components/schemas/WorkbookInfo' description: Information about created workbook table type: object required: - total_results - workbook title: FindPlacesMetadataWorkbook description: Metadata when destination is 'workbook'. FindPlacesMetadataDefault: properties: total_results: type: integer minimum: 0 title: Total Results description: Total number of places found version: type: string title: Version description: The API version used default: v0.1.0 type: object required: - total_results title: FindPlacesMetadataDefault description: Metadata for default output mode (no destination specified). WorkbookDestination: properties: maximum: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Maximum description: >- Maximum number of rows to export. If not specified, exports all results up to 20,001 rows. additionalProperties: false type: object title: WorkbookDestination description: Export results to a Reprompt workbook. DatasetDestination: properties: maximum: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Maximum description: >- Maximum number of results to export. If not specified, exports all results up to 10,000,000 results. additionalProperties: false type: object title: DatasetDestination description: Export results to Reprompt dataset batches. DatasetsInfo: properties: outputs: items: $ref: '#/components/schemas/DatasetOutput' type: array title: Outputs description: Array of created batch links metadata: $ref: '#/components/schemas/DatasetsMetadata' description: Batch creation configuration type: object required: - outputs - metadata title: DatasetsInfo description: Dataset information when destination is 'dataset'. WorkbookInfo: properties: table_id: type: string title: Table Id description: UUID of the created workbook name: type: string title: Name description: Name of the workbook url: type: string title: Url description: URL to view the workbook in Reprompt app row_count: type: integer minimum: 0 title: Row Count description: Number of rows in the workbook capped: type: boolean title: Capped description: Whether results were capped due to row limit total_found: type: integer minimum: 0 title: Total Found description: Total results found before capping type: object required: - table_id - name - url - row_count - capped - total_found title: WorkbookInfo description: Workbook information when destination is 'workbook'. DatasetOutput: properties: batch_id: type: string title: Batch Id description: UUID of the created batch batch_name: type: string title: Batch Name description: Name of the batch url: type: string title: Url description: URL to manage the batch in Reprompt app jobs_count: type: integer minimum: 0 title: Jobs Count description: Number of jobs in this batch type: object required: - batch_id - batch_name - url - jobs_count title: DatasetOutput description: A single dataset output representing a created Reprompt batch. DatasetsMetadata: properties: num_batches: type: integer minimum: 1 title: Num Batches description: Number of batches created max_jobs_per_batch: type: integer maximum: 50000 minimum: 1 title: Max Jobs Per Batch description: Max jobs per batch used type: object required: - num_batches - max_jobs_per_batch title: DatasetsMetadata description: Metadata about batch creation configuration. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Bearer token in the format: Bearer YOUR_API_KEY' ````