{"openapi":"3.1.0","info":{"title":"BeachFinder Agent Search API","version":"1.0.0","description":"Read-only discovery for 184,900 swimming spots, conditions, guides and activity providers. Every recommendation links back to BeachFinder."},"servers":[{"url":"https://getbeachfinder.com"}],"paths":{"/api/v1/agent/beaches/search":{"get":{"operationId":"searchBeaches","summary":"Find beaches for a destination and intent","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":90}},{"name":"city","in":"query","schema":{"type":"string","maxLength":90}},{"name":"country","in":"query","schema":{"type":"string","maxLength":60}},{"name":"radiusKm","in":"query","schema":{"type":"number","minimum":1,"maximum":150,"default":50}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"}},{"name":"intent","in":"query","schema":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}],"responses":{"200":{"description":"A privacy-safe BeachFinder recommendation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or ambiguous request"},"429":{"description":"Rate limited"}}},"post":{"operationId":"searchBeachesPrivateLocation","summary":"Find beaches for a destination and intent; POST is recommended for consented coordinates","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":90},"city":{"type":"string","maxLength":90},"country":{"type":"string","maxLength":60},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","minimum":1,"maximum":150,"default":50},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5},"lang":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"},"intent":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}}}}},"responses":{"200":{"description":"A privacy-safe BeachFinder recommendation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or ambiguous request"},"429":{"description":"Rate limited"}}}},"/api/v1/agent/spots/search":{"get":{"operationId":"searchSwimSpots","summary":"Find beaches, lakes and swimming spots","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":90}},{"name":"city","in":"query","schema":{"type":"string","maxLength":90}},{"name":"country","in":"query","schema":{"type":"string","maxLength":60}},{"name":"radiusKm","in":"query","schema":{"type":"number","minimum":1,"maximum":150,"default":50}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"}},{"name":"intent","in":"query","schema":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}],"responses":{"200":{"description":"A privacy-safe BeachFinder recommendation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or ambiguous request"},"429":{"description":"Rate limited"}}},"post":{"operationId":"searchSwimSpotsPrivateLocation","summary":"Find beaches, lakes and swimming spots; POST is recommended for consented coordinates","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":90},"city":{"type":"string","maxLength":90},"country":{"type":"string","maxLength":60},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","minimum":1,"maximum":150,"default":50},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5},"lang":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"},"intent":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}}}}},"responses":{"200":{"description":"A privacy-safe BeachFinder recommendation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or ambiguous request"},"429":{"description":"Rate limited"}}}},"/api/v1/agent/providers/search":{"get":{"operationId":"searchActivityProviders","summary":"Find source-backed water activity providers","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":90}},{"name":"city","in":"query","schema":{"type":"string","maxLength":90}},{"name":"country","in":"query","schema":{"type":"string","maxLength":60}},{"name":"radiusKm","in":"query","schema":{"type":"number","minimum":1,"maximum":150,"default":50}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"}},{"name":"intent","in":"query","schema":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}],"responses":{"200":{"description":"A privacy-safe BeachFinder recommendation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or ambiguous request"},"429":{"description":"Rate limited"}}},"post":{"operationId":"searchActivityProvidersPrivateLocation","summary":"Find source-backed water activity providers; POST is recommended for consented coordinates","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":90},"city":{"type":"string","maxLength":90},"country":{"type":"string","maxLength":60},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","minimum":1,"maximum":150,"default":50},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5},"lang":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"},"intent":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}}}}},"responses":{"200":{"description":"A privacy-safe BeachFinder recommendation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or ambiguous request"},"429":{"description":"Rate limited"}}}},"/api/v1/agent/guides/search":{"get":{"operationId":"searchGuides","summary":"Find relevant BeachFinder guides","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":90}},{"name":"city","in":"query","schema":{"type":"string","maxLength":90}},{"name":"country","in":"query","schema":{"type":"string","maxLength":60}},{"name":"radiusKm","in":"query","schema":{"type":"number","minimum":1,"maximum":150,"default":50}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"}},{"name":"intent","in":"query","schema":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}],"responses":{"200":{"description":"A privacy-safe BeachFinder recommendation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or ambiguous request"},"429":{"description":"Rate limited"}}},"post":{"operationId":"searchGuidesPrivateLocation","summary":"Find relevant BeachFinder guides; POST is recommended for consented coordinates","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":90},"city":{"type":"string","maxLength":90},"country":{"type":"string","maxLength":60},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","minimum":1,"maximum":150,"default":50},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5},"lang":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"},"intent":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}}}}},"responses":{"200":{"description":"A privacy-safe BeachFinder recommendation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or ambiguous request"},"429":{"description":"Rate limited"}}}},"/api/v1/agent/specialized/{kind}":{"get":{"operationId":"searchSpecializedSpots","summary":"Find surf, dive, river or vanlife spots","parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["surf","dive","river","van"]}},{"name":"query","in":"query","schema":{"type":"string","maxLength":90}},{"name":"city","in":"query","schema":{"type":"string","maxLength":90}},{"name":"country","in":"query","schema":{"type":"string","maxLength":60}},{"name":"lat","in":"query","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lng","in":"query","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"radiusKm","in":"query","schema":{"type":"number","minimum":1,"maximum":150,"default":50}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"}},{"name":"intent","in":"query","schema":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}],"responses":{"200":{"description":"Specialized BeachFinder results"},"400":{"description":"Invalid request"}}},"post":{"operationId":"searchSpecializedSpotsPrivateLocation","summary":"Find specialized spots; POST is recommended for consented coordinates","parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["surf","dive","river","van"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":90},"city":{"type":"string","maxLength":90},"country":{"type":"string","maxLength":60},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","minimum":1,"maximum":150,"default":50},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5},"lang":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"],"default":"en"},"intent":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"],"default":"general"}}}}}},"responses":{"200":{"description":"Specialized BeachFinder results"},"400":{"description":"Invalid request"}}}},"/api/v1/agent/spots/{id}":{"get":{"operationId":"getSpotDetails","summary":"Get public details for one BeachFinder spot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"]}}],"responses":{"200":{"description":"Spot details"},"404":{"description":"Not found"}}}},"/api/v1/agent/spots/{id}/conditions":{"get":{"operationId":"getSpotConditions","summary":"Get current planning signals for one spot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"]}}],"responses":{"200":{"description":"Current conditions"}}}},"/api/v1/agent/spots/compare":{"post":{"operationId":"compareSpots","summary":"Compare two to five BeachFinder spots","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["spotIds"],"properties":{"spotIds":{"type":"array","minItems":2,"maxItems":5,"items":{"type":"string","format":"uuid"}},"lang":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"]},"intent":{"type":"string","enum":["general","swimming","family","low-wind","warm-water","surf","accessible","amenities"]}}}}}},"responses":{"200":{"description":"Spot comparison"}}}},"/api/v1/agent/community/{id}":{"get":{"operationId":"getCommunityConditions","summary":"Get an anonymous aggregate of active community observations","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","es","de","it","pt","nl","ja","ko","zh","ar","tr","ru","id"]}}],"responses":{"200":{"description":"Anonymous aggregate only"}}}}},"components":{"schemas":{"AgentResponse":{"type":"object","required":["ok","operation","answer","results","safetyNotice"],"properties":{"ok":{"const":true},"operation":{"type":"string"},"answer":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"confidence":{"enum":["high","medium","low"]},"results":{"type":"array","maxItems":10,"items":{"type":"object"}},"safetyNotice":{"type":"string"},"attribution":{"type":"string"}}}}}}