openapi-v2.json

{"openapi":"3.1.0","info":{"title":"Reprompt API v2","version":"2.0"},"servers":[{"url":"https://api.reprompt.io/v2","description":"V2 API server"}],"paths":{"/enrich":{"post":{"tags":["Enrichments"],"summary":"Enrich","description":"Enrich a single place live","operationId":"enrich_enrich_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2EnrichRequest"},"examples":{"place_enrichment":{"summary":"Enrich place with attribute","value":{"inputs":{"name":"Joe's Pizza","latitude":40.7359,"longitude":-73.9911,"full_address":"7 Carmine St, New York, NY 10014"},"attribute_key":"closed_permanently"}},"reverse_geocode":{"summary":"Reverse geocode coordinates","value":{"inputs":{"latitude":40.7359,"longitude":-73.9911},"attribute_key":"reverse_geocode"}},"forward_geocode":{"summary":"Forward geocode address","value":{"inputs":{"full_address":"123 Main St, New York, NY 10001"},"attribute_key":"forward_geocode"}},"test_attribute":{"summary":"Test attribute for debugging","value":{"inputs":{"name":"Test Place","latitude":40.7359,"longitude":-73.9911},"attribute_key":"test_attribute"}},"test_api_attribute":{"summary":"Test API attribute with HTTP call","value":{"inputs":{"test_query":"Test Query"},"attribute_key":"test_api_attribute"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/attributes":{"get":{"tags":["Enrichments"],"summary":"List Attributes","description":"List available attributes including custom attributes","operationId":"list_attributes_attributes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2AttributesResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/validate":{"post":{"tags":["Places"],"summary":"Validate Place","description":"Validate if a place exists and has a digital footprint using AI-powered web search and analysis.\n\nGiven a place name and/or address, this endpoint performs comprehensive analysis to determine:\n\n**Digital Footprint Analysis:**\n- Web presence, social media accounts, official websites, and online mentions\n- Strength of digital presence (HIGH, MEDIUM, LOW, NONE)\n\n**Entity Type Classification:**\n- Determines if the query represents a place, address only, person name, geographic area, or other entity type\n\n**Place Definition:**\n- Identifies the type of place: physical storefront, residential, temporary event, digital-only business (e.g., ghost kitchens, eCommerce), etc.\n\n**Place Reality - Location Match Granularity:**\n- **house_number**: Evidence found at exact address including street number (e.g., \"123 Main St\")\n- **nearby**: Evidence found on same street but without exact house number (e.g., \"Main St\" in same city)\n- **broad**: Evidence found in general area/city but at different street or only partial address match\n- **none**: Unable to match the place to any specific location\n\nInput sensitivity: The achievable location_match_granularity depends on how specific the input is.\n- Example \u2014 nearby: Input name=\"Starbucks\", address=\"123 main st san francisco\" \u2192 location_match_granularity: nearby. Web sources may resolve this to an actual Starbucks at \"5075 Main St, San Francisco\". We will still confirm the existence of \"Starbucks, San Francisco\" as a place: it DOES exist, it has HIGH internet presence, and it DOES have a storefront.\n- Example \u2014 broad: Input name=\"Starbucks\", address=\"San Francisco\" (name + city only) \u2192 location_match_granularity: broad. We can confirm the brand exists in the city, but without a specific street/house number from the input, the match stays broad.\n\n**Reprompt Validation Score:**\n\n- The `reprompt_validation_score` (1-9) provides an immediate assessment of whether a place is a legitimate, transactable commercial establishment. Use this score as a \"first pass\" filter before spending credits on deeper enrichments.\n\n**Use Cases:**\n*   **Filter out fraudulent places**: Reject places with low scores before continuing with deeper enrichments.\n*   **Identify non-commercial locations**: Distinguish legitimate businesses with storefronts from legitimate non-commercial locations like parks, landmarks, or residential addresses.\n*   **Verify commercial legitimacy**: Ensure a business is a real operating entity before adding it to your database.\n\n**Scoring Rubric:**\n\n- **Score 9**: Walk-in commercial establishments such as retail stores, restaurants, cafes, bakeries with strong multi-source verification, clear operating hours, and confirmed customer visits.\n- **Score 8**: Membership/appointment-based establishments. Gyms, fitness centers, salons, spas requiring membership or appointments.\n- **Score 7**: Scheduled service businesses. HVAC companies, plumbers, electricians, contractors that operate by appointment and service calls.\n- **Score 6**: Corporate offices and business headquarters. Not customer-facing but legitimate business operations.\n- **Score 5**: Landmarks, parks, monuments. Verified public places but not commercial businesses. Maximum score for non-businesses.\n- **Score 4**: Non-commercial infrastructure. Parking lots, garages, and utility structures that serve a function but are not destinations people visit for goods or services.\n- **Score 3**: Residential addresses. Verified homes, apartments, or residential properties.\n- **Score 1-2**: Minimal or weak evidence. Either found only on unreliable aggregator sites (score 2) or very weak/no verification (score 1).\n\n**Examples:**\n\n**1. Walk-In Commercial - Bakery (Score 9)**\n*   **Name:** Tartine Bakery\n*   **Address:** 600 Guerrero St, San Francisco, CA 94110\n*   **Score:** **9/10**\n*   **Reasoning:** Near perfect score because it is a confirmed bakery/cafe with a physical storefront where customers walk in to purchase baked goods and dine. Strong digital presence with extensive reviews, hours, menu information, and consistent verification across multiple reliable sources.\n\n**2. Membership-Based - Gym (Score 8)**\n*   **Name:** 24 Hour Fitness\n*   **Address:** 1200 Van Ness Ave, San Francisco, CA 94109\n*   **Score:** **8/10**\n*   **Reasoning:** Scores an 8 because it is a verified gym with a physical location where customers visit, but typically requires membership. Strong digital presence with reviews, hours, and contact information across multiple sources.\n\n**3. Scheduled Service Business - Plumbing (Score 7)**\n*   **Name:** One Source Plumbing and Rooter\n*   **Address:** 350 Bay St, Ste 100-178, San Francisco, CA 94133\n*   **Score:** **7/10**\n*   **Reasoning:** Scores a 7 because it is a legitimate service business with good online verification, but it operates by appointment and service calls rather than as a walk-in storefront. Multiple directory listings confirm the business.\n\n**4. Corporate Office (Score 6)**\n*   **Name:** Salesforce Tower\n*   **Address:** 415 Mission St, San Francisco, CA 94105\n*   **Score:** **6/10**\n*   **Reasoning:** Scores a 6 because it is a verified corporate headquarters and office building with strong documentation, but not a customer-facing walk-in business location. Legitimate business operations but not open to general public.\n\n**5. Landmark/Park (Score 5)**\n*   **Name:** Golden Gate Park\n*   **Address:** 501 Stanyan St, San Francisco, CA 94117\n*   **Score:** **5/10**\n*   **Reasoning:** Scores a 5, the maximum for a non-business. It is clearly a real, visitable place (a famous park/landmark) with extensive documentation, but because it is not a commercial entity, it scores in the non-business category.\n\n**6. Non-Commercial Infrastructure - Parking (Score 4)**\n*   **Name:** Sutter Stockton Garage\n*   **Address:** 444 Stockton St, San Francisco, CA 94108\n*   **Score:** **4/10**\n*   **Reasoning:** Scores a 4 because it is a verified parking structure with some online presence, but serves purely as infrastructure. Not a destination people visit for goods or services beyond its utility function.\n\n**7. Residential Address (Score 3)**\n*   **Name:** 81 Noe St\n*   **Address:** 81 Noe St, San Francisco, CA 94114\n*   **Score:** **3/10**\n*   **Reasoning:** Scores a 3 because it is verified as a residential address. The address exists and can be found on real estate sites, but it is not a commercial establishment or business.\n\n**8. Minimal Low-Quality Presence (Score 2)**\n*   **Name:** California Kitchen\n*   **Address:** 2400 W Holcombe Blvd, Houston, TX 77031\n*   **Score:** **2/10**\n*   **Reasoning:** Scores a 2 because evidence exists only on unreliable aggregator sites with minimal verification. No presence on major platforms like Google Maps, Yelp, or official business directories.\n\n**9. Does Not Exist / Fake (Score 1)**\n*   **Name:** LA Fitness\n*   **Address:** 5000 Westheimer Rd, Houston, TX 77063\n*   **Score:** **1/10**\n*   **Reasoning:** Scores a 1 because the name + address combination cannot be found anywhere on reliable sources. While LA Fitness exists at other Houston locations (e.g., 9603 Westheimer Rd), there is no evidence of a location at 5000 Westheimer Rd.\n\n\n**Important Notes:**\n- This endpoint validates place existence and digital presence, but does NOT determine if a place is currently open or closed\n- For open/closed status verification, use the `closed_permanently` enrichment via the `/enrich` endpoint","operationId":"validate_place_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2PlaceValidationRequest"},"examples":{"ghost_kitchen_example":{"summary":"Ghost kitchen with name and address","value":{"name":"Burger Den","address":"12405 Westheimer Rd, Houston, TX 77077"}},"starbucks_example":{"summary":"Nearby match","value":{"name":"Starbucks","address":"Market and 8th st san francisco"}},"pizza_example":{"summary":"Name and city only","value":{"name":"Apple","address":"San francisco"}},"apple_store_example":{"summary":"Exact match","value":{"name":"Apple Store","address":"300 post st San Francisco CA"}},"fictional_example":{"summary":"Fictional place","value":{"name":"Hogwarts school of witchcraft and wizardry","address":"highlands, scotland, Great Britain"}},"address_only_example":{"summary":"Address only (no name)","value":{"address":"123 Main St, San Francisco, CA"}},"no_storefront_example":{"summary":"No storefront","value":{"name":"Syncup AI Inc","address":"201 3rd st, San Francisco, CA"}},"unusual_name_example":{"summary":"Unusual name like store ID","value":{"name":"!!!","address":"2507 r.fernandez, manila, philippines"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/placematch":{"post":{"tags":["Places","Places"],"summary":"Placematch","description":"Match a place against multiple geospatial data sources using AI-powered entity resolution.\nGiven information about a place (address, name, coordinates) we will find the right place. Under the hood we use a combination of name similarity, geographic proximity and distance, category alignment, address components\nto find candidates and match them with our fine-tuned LLM.","operationId":"placematch_endpoint_placematch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacematchRequest"},"examples":{"precise_matching":{"summary":"Precise matching with name+address+coordinates","description":"Most precise matching mode using all available place information","value":{"place":{"name":"Starbucks","full_address":"1585 Broadway, New York, NY 10036","latitude":40.7614327,"longitude":-73.9776216},"match_sources":["reprompt"]}}}}},"required":true},"responses":{"200":{"description":"Successfully matched places","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacematchResponse"},"examples":{"messy_data_cleaned":{"summary":"Messy data matched to Overture","value":{"results":[{"name":"McDonald's","full_address":"1528 Broadway, New York, NY 10036","latitude":40.7589,"longitude":-73.9851,"category":"fast_food","categories":["fast_food","restaurant"],"source":"overture","is_match":true,"confidence":"HIGH","reasoning":"Good match: normalized name similarity and location within acceptable range"}],"metadata":{"total_results":1,"sources_searched":["overture"],"search_radius_meters":200}}}}}}},"400":{"description":"Invalid input or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacematchErrorResponse"},"examples":{"missing_input_error":{"summary":"No input provided","value":{"error":"validation_error","message":"Must provide at least a name OR coordinates","details":{}}},"incomplete_coordinates_error":{"summary":"Only latitude or longitude provided","value":{"error":"validation_error","message":"Both latitude and longitude must be provided together","details":{}}},"address_without_name_error":{"summary":"Address provided without name","value":{"error":"validation_error","message":"Address can only be provided together with a name","details":{"suggestion":"Include place.name when providing place.address"}}}}}}},"422":{"description":"Geocoding failed or processing error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacematchErrorResponse"}}}},"501":{"description":"Feature not yet supported (coordinates-only searches, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacematchErrorResponse"}}}},"502":{"description":"External service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacematchErrorResponse"}}}},"504":{"description":"Request timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacematchErrorResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/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","requestBody":{"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"]}}}}},"required":true},"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"}}}},"502":{"description":"External service 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"}}}}}}},"security":[{"bearerAuth":[]}]}}},"components":{"schemas":{"ConfidenceLevel":{"type":"string","enum":["VERY_HIGH","HIGH","MEDIUM","LOW"],"title":"ConfidenceLevel","description":"Confidence levels for place matching."},"DatasetDestination":{"properties":{"maximum":{"anyOf":[{"type":"integer","exclusiveMinimum":0.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."},"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.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."},"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'."},"DatasetsMetadata":{"properties":{"num_batches":{"type":"integer","minimum":1.0,"title":"Num Batches","description":"Number of batches created"},"max_jobs_per_batch":{"type":"integer","maximum":50000.0,"minimum":1.0,"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."},"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.\n\nSpecify exactly one destination type (workbook or dataset), or omit for default behavior (return results directly).\nEach destination supports a 'maximum' parameter to limit the number of results exported.\nWhen 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.0,"minimum":-90.0,"title":"Latitude","description":"The latitude of the place"},"longitude":{"type":"number","maximum":180.0,"minimum":-180.0,"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."},"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."},"FindPlacesMetadataDataset":{"properties":{"total_results":{"type":"integer","minimum":0.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'."},"FindPlacesMetadataDefault":{"properties":{"total_results":{"type":"integer","minimum":0.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)."},"FindPlacesMetadataWorkbook":{"properties":{"total_results":{"type":"integer","minimum":0.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'."},"FindPlacesRequest":{"properties":{"location_filter":{"$ref":"#/components/schemas/LocationFilter","description":"Location filter for geographic search.\n\n**Location Filter Types (choose exactly one):**\n- **Lat/Lon + Radius**: Point-based search within specified radius (default 500m, max 10km)\n- **GeoJSON Geometry**: Area-based search within Polygon or MultiPolygon boundaries\n- **Locality**: Search within a city/town (requires country_code)\n- **Postal Code**: Search within a postal/ZIP code area (requires country_code)\n- **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.\n\nReprompt supports multiple backends for finding places:\n- **[Foursquare OS Places](https://opensource.foursquare.com/os-places/)** - amazing open data project with 100M+ global POIs (Apache 2.0 license)\n- **[Overture Places](https://overturemaps.org/)** - open map data from the Overture Maps Foundation with 64M+ places (CDLA Permissive 2.0)\n- **Our index** of places we picked up from crawling the web\n\nThis 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.\n\n**Category Schemas by Source:**\n- **Reprompt & Overture**: Use [Overture Maps schema](https://docs.overturemaps.org/schema/concepts/by-theme/places/) (e.g., \"cafe\", \"restaurant\", \"hospital\")\n- **Foursquare**: Use [Foursquare category taxonomy](https://docs.foursquare.com/data-products/docs/categories) (e.g., \"Food and Beverage > Restaurant\", \"Retail > Grocery Store\")\n- 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. \n        Specify 'workbook' to export to a Reprompt workbook table, or 'dataset' to export to Reprompt batches.\n        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.\n\nResults are always returned (up to 500 places). The metadata structure varies based on destination:\n- Default (no destination): Basic metadata with total_results and version\n- dataset: Includes datasets info with batch links\n- workbook: Includes workbook info with table details"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LocationFilter":{"properties":{"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude","description":"Latitude coordinate","examples":[37.7749]},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude","description":"Longitude coordinate","examples":[-122.4194]},"radius":{"type":"integer","maximum":10000.0,"minimum":0.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.\n\nSupports multiple filter types (mutually exclusive):\n1. Lat/Lon/Radius: Provide latitude, longitude, and optionally radius (default 500m)\n2. Geometry: Provide geometry as GeoJSON object, optionally with country_code to skip reverse geocoding\n3. Region: Provide region and country_code\n4. Postal Code: Provide postal_code (and optionally country_code)\n5. Locality: Provide locality and country_code\n\nNote: For geometry searches, providing country_code improves accuracy (especially for countries like Italy\nor Vietnam where bounding box center method doesn't work well) and reduces latency by skipping reverse geocoding."},"PlaceInput":{"properties":{"place_id":{"type":"string","title":"Place Id","description":"Optional place ID for matching","default":""},"name":{"type":"string","title":"Name","description":"Name of the place (required)"},"full_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Address","description":"Address of the place (for more precise matching)"},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude","description":"Latitude coordinate"},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude","description":"Longitude coordinate"},"category_primary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Primary","description":"Primary category of the place"},"category_alternates":{"items":{"type":"string"},"type":"array","title":"Category Alternates","description":"Alternate categories of the place"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Phone number of the place"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Website URL of the place"}},"additionalProperties":false,"type":"object","required":["name"],"title":"PlaceInput","description":"Place object input for placematch - supports coordinates-only, name-only, or name+address+coordinates."},"PlacematchErrorResponse":{"properties":{"error":{"type":"string","title":"Error","description":"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"}},"type":"object","required":["error","message"],"title":"PlacematchErrorResponse","description":"Error response for placematch endpoint."},"PlacematchItem":{"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.0,"minimum":-90.0,"title":"Latitude","description":"The latitude of the place"},"longitude":{"type":"number","maximum":180.0,"minimum":-180.0,"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)"},"is_match":{"type":"boolean","title":"Is Match","description":"Whether this is considered a confident match"},"confidence":{"$ref":"#/components/schemas/ConfidenceLevel","description":"Confidence level based on score thresholds: VERY_HIGH (>0.95), HIGH (>0.9), MEDIUM (>0.8), LOW (>0.5)"},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning","description":"Human-readable explanation of the match"}},"type":"object","required":["place_id","name","full_address","latitude","longitude","category_primary","is_match","confidence"],"title":"PlacematchItem","description":"Matched place item - extends FindPlaceItem with matching metadata."},"PlacematchMetadata":{"properties":{"total_results":{"type":"integer","title":"Total Results","description":"Total number of results returned"},"sources_searched":{"items":{"type":"string"},"type":"array","title":"Sources Searched","description":"Sources that were searched"},"search_radius_meters":{"type":"number","title":"Search Radius Meters","description":"Search radius used"}},"type":"object","required":["total_results","sources_searched","search_radius_meters"],"title":"PlacematchMetadata"},"PlacematchRequest":{"properties":{"place":{"$ref":"#/components/schemas/PlaceInput","description":"Place to match. In order to match places you need to provide one of the following:\n\n- **Name + Address**: Provide `place.name` + `place.full_address`\n- **Name + Address + Coordinates (most accurate)**: Provide `place.name` + `place.full_address` + `place.latitude` + `place.longitude`"},"match_sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/PlacematchSource"},"type":"array"},{"type":"null"}],"title":"Match Sources","description":"Sources to search for matches. Defaults to reprompt if not specified.\n\nReprompt supports multiple backends for matching against:\n\n- **Foursquare OS Places** - amazing open data project with 100M+ global POIs (Apache 2.0 license)\n- **Overture Places** - open map data from the Overture Maps Foundation with 64M+ places (CDLA Permissive 2.0)\n- **Our index of places** we picked up from crawling the web","default":["reprompt"]},"max_matches":{"anyOf":[{"type":"integer","maximum":5.0,"minimum":1.0},{"type":"null"}],"title":"Max Matches","description":"Maximum matches per source","default":1},"radius":{"anyOf":[{"type":"number","maximum":5000.0,"minimum":50.0},{"type":"null"}],"title":"Radius","description":"Search radius in meters","default":1000}},"additionalProperties":false,"type":"object","required":["place"],"title":"PlacematchRequest","description":"Request model for placematch endpoint."},"PlacematchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/PlacematchItem"},"type":"array","title":"Results","description":"Array of matched places"},"metadata":{"$ref":"#/components/schemas/PlacematchMetadata","description":"Operation metadata"}},"type":"object","required":["results","metadata"],"title":"PlacematchResponse","description":"Response model for placematch endpoint."},"PlacematchSource":{"type":"string","enum":["reprompt","overture","foursquare"],"title":"PlacematchSource","description":"Supported data sources for place matching and search.\n\nThese sources are available across both the placematch API (for entity resolution)\nand the find-places API (for geographic search)."},"V2AttributeDetails":{"properties":{"key":{"type":"string","title":"Key"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"function_signatures":{"items":{"$ref":"#/components/schemas/V2AttributeFunctionSignature"},"type":"array","title":"Function Signatures"},"enrichment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Enrichment Type"},"generic_api_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Generic Api Config"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Favicon"}},"type":"object","required":["key","name","description","function_signatures"],"title":"V2AttributeDetails","description":"Detailed information about a single attribute"},"V2AttributeFunctionSignature":{"properties":{"required_inputs":{"items":{"$ref":"#/components/schemas/V2InputField"},"type":"array","title":"Required Inputs"},"optional_inputs":{"anyOf":[{"items":{"$ref":"#/components/schemas/V2InputField"},"type":"array"},{"type":"null"}],"title":"Optional Inputs"},"output_schema":{"additionalProperties":true,"type":"object","title":"Output Schema"},"example_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Example Output"},"credit_cost":{"type":"integer","title":"Credit Cost"}},"type":"object","required":["required_inputs","output_schema","credit_cost"],"title":"V2AttributeFunctionSignature"},"V2AttributesResponse":{"properties":{"attributes":{"items":{"$ref":"#/components/schemas/V2AttributeDetails"},"type":"array","title":"Attributes"},"total_count":{"type":"integer","title":"Total Count"}},"type":"object","required":["attributes","total_count"],"title":"V2AttributesResponse","description":"Response for the /attributes endpoint"},"V2EnrichRequest":{"properties":{"inputs":{"additionalProperties":true,"type":"object","title":"Inputs"},"attribute_key":{"type":"string","title":"Attribute Key"}},"type":"object","required":["inputs","attribute_key"],"title":"V2EnrichRequest","description":"Main enrichment request"},"V2InputField":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"description":{"type":"string","title":"Description"},"example":{"anyOf":[{},{"type":"null"}],"title":"Example"}},"type":"object","required":["name","type","description"],"title":"V2InputField","description":"Represents a single input field for an attribute"},"V2PlaceValidationRequest":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Business or place name"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"Full address of the place"}},"type":"object","title":"V2PlaceValidationRequest","description":"Request model for place existence endpoint"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WorkbookDestination":{"properties":{"maximum":{"anyOf":[{"type":"integer","exclusiveMinimum":0.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."},"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.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.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'."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token in the format: Bearer YOUR_API_KEY"}}},"tags":[{"name":"Enrichments","description":"Use AI to enrich place data with various attributes"},{"name":"Places","description":"Find, match, and check existence of places"}]}