{"openapi":"3.1.0","info":{"title":"TidalWaiv API","description":"Public read-only access to England's bathing water history. No API key required. Start with GET /api/v1/sites?q=Brean, then follow summary, history and chart links. Cache responses and fetch on demand; avoid bulk polling. Historical data and annual classifications are not live safety readings. Full integration guide: /api/guide. Existing /api/sites endpoints remain available.","version":"1.0.0"},"paths":{"/api/sites":{"get":{"tags":["sites"],"summary":"List Sites","description":"Return a list of bathing water sites, optionally filtered by region.","operationId":"list_sites_api_sites_get","parameters":[{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter sites by region label","title":"Region"},"description":"Filter sites by region label"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SiteSummary"},"title":"Response List Sites Api Sites Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/sites/{site_id}":{"get":{"tags":["sites"],"summary":"Get Site Detail","description":"Return detailed metadata for a single site.","operationId":"get_site_detail_api_sites__site_id__get","parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/sites/{site_id}/history":{"get":{"tags":["sites"],"summary":"Get Site History","description":"Return processed historical sampling data for a site.","operationId":"get_site_history_api_sites__site_id__history_get","parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sites":{"get":{"tags":["Bot API v1"],"summary":"Search or list bathing waters","operationId":"list_sites_api_v1_sites_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}],"description":"Match a site name, district or exact site ID; ambiguous names return all matches.","title":"Q"},"description":"Match a site name, district or exact site ID; ambiguous names return all matches."},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Region"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotSiteList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sites/{site_id}/summary":{"get":{"tags":["Bot API v1"],"summary":"Get a shareable historical summary","operationId":"site_summary_api_v1_sites__site_id__summary_get","parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotSummary"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sites/{site_id}":{"get":{"tags":["Bot API v1"],"summary":"Get a site's data and media links","operationId":"site_summary_api_v1_sites__site_id__get","parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotSummary"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sites/{site_id}/history":{"get":{"tags":["Bot API v1"],"summary":"Get all processed samples and annual classifications","operationId":"site_history_api_v1_sites__site_id__history_get","parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sites/{site_id}/samples.csv":{"get":{"tags":["Bot API v1"],"summary":"Download the processed sample history as CSV","operationId":"samples_csv_api_v1_sites__site_id__samples_csv_get","parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"text/csv":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sites/{site_id}/charts/{chart}.png":{"get":{"tags":["Bot API v1"],"summary":"Download a branded sample or classification graph","operationId":"chart_image_api_v1_sites__site_id__charts__chart__png_get","parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","title":"Site Id"}},{"name":"chart","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Chart"}}],"responses":{"200":{"description":"Successful Response","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/favicon.ico":{"get":{"summary":"Serve Favicon","operationId":"serve_favicon_favicon_ico_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/apple-touch-icon.png":{"get":{"summary":"Serve Apple Icon","operationId":"serve_apple_icon_apple_touch_icon_png_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/android-chrome-192x192.png":{"get":{"summary":"Serve Android 192","operationId":"serve_android_192_android_chrome_192x192_png_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/android-chrome-512x512.png":{"get":{"summary":"Serve Android 512","operationId":"serve_android_512_android_chrome_512x512_png_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/social-preview-v1.png":{"get":{"summary":"Serve Og Image","operationId":"serve_og_image_social_preview_v1_png_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"head":{"summary":"Serve Og Image","operationId":"serve_og_image_social_preview_v1_png_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/og-image.png":{"get":{"summary":"Serve Og Image","operationId":"serve_og_image_og_image_png_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"head":{"summary":"Serve Og Image","operationId":"serve_og_image_og_image_png_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/top10-improved-sites.csv":{"get":{"summary":"Serve Top10 Csv","operationId":"serve_top10_csv_top10_improved_sites_csv_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"BotLinks":{"properties":{"page":{"type":"string","title":"Page"},"summary":{"type":"string","title":"Summary"},"history":{"type":"string","title":"History"},"samples_csv":{"type":"string","title":"Samples Csv"},"social_image":{"type":"string","title":"Social Image"},"charts":{"additionalProperties":{"type":"string"},"type":"object","title":"Charts"},"methodology":{"type":"string","title":"Methodology"},"source":{"type":"string","title":"Source"}},"type":"object","required":["page","summary","history","samples_csv","social_image","charts","methodology","source"],"title":"BotLinks"},"BotSite":{"properties":{"site_id":{"type":"string","title":"Site Id"},"name":{"type":"string","title":"Name"},"latitude":{"type":"number","title":"Latitude"},"longitude":{"type":"number","title":"Longitude"},"classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classification"},"district":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"District"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"page_url":{"type":"string","title":"Page Url"},"summary_url":{"type":"string","title":"Summary Url"},"history_url":{"type":"string","title":"History Url"}},"type":"object","required":["site_id","name","latitude","longitude","page_url","summary_url","history_url"],"title":"BotSite"},"BotSiteList":{"properties":{"total":{"type":"integer","title":"Total"},"offset":{"type":"integer","title":"Offset"},"limit":{"type":"integer","title":"Limit"},"items":{"items":{"$ref":"#/components/schemas/BotSite"},"type":"array","title":"Items"}},"type":"object","required":["total","offset","limit","items"],"title":"BotSiteList"},"BotSummary":{"properties":{"api_version":{"type":"string","const":"1","title":"Api Version","default":"1"},"site":{"$ref":"#/components/schemas/SiteDetail"},"coverage":{"$ref":"#/components/schemas/SiteHistorySummary"},"latest_official_classification":{"anyOf":[{"$ref":"#/components/schemas/SiteAnnualClassification"},{"type":"null"}]},"trend":{"$ref":"#/components/schemas/BotTrend"},"summary":{"type":"string","title":"Summary"},"share_text":{"type":"string","title":"Share Text"},"links":{"$ref":"#/components/schemas/BotLinks"},"retrieved_at":{"type":"string","format":"date-time","title":"Retrieved At","description":"When this cached source snapshot was retrieved, not the sample date."},"units":{"type":"string","title":"Units","default":"CFU per 100 ml"},"source":{"type":"string","title":"Source","default":"Environment Agency bathing water data for England; historical processing by TidalWaiv."},"interpretation":{"type":"string","title":"Interpretation","default":"Historical bacterial indicators and annual assessments; not a live water-safety or sewage-discharge reading. Legacy FC/FS proxies and estimated classifications are labelled in the history. See methodology."}},"type":"object","required":["site","coverage","latest_official_classification","trend","summary","share_text","links","retrieved_at"],"title":"BotSummary"},"BotTrend":{"properties":{"percent_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Percent Change","description":"Negative means lower bacterial counts, positive means higher. Null means insufficient history."},"baseline_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Baseline Date"},"latest_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Date"},"metric":{"type":"string","title":"Metric","default":"Arithmetic mean of the available EC and IE four-year geometric means, matching the website trend."}},"type":"object","required":["percent_change","baseline_date","latest_date"],"title":"BotTrend"},"Chart":{"type":"string","enum":["samples","ec","ie","classifications"],"title":"Chart"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SiteAnnualClassification":{"properties":{"year":{"type":"integer","title":"Year"},"classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classification"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"ec_95_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ec 95 Percentile"},"ie_95_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ie 95 Percentile"},"ec_90_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ec 90 Percentile"},"ie_90_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ie 90 Percentile"},"sample_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sample Count"},"ec_sample_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ec Sample Count"},"ie_sample_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ie Sample Count"},"data_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Source"}},"type":"object","required":["year"],"title":"SiteAnnualClassification","description":"Annual bathing water classification with supporting metrics."},"SiteDetail":{"properties":{"site_id":{"type":"string","title":"Site Id"},"name":{"type":"string","title":"Name"},"canonical_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Path"},"latitude":{"type":"number","title":"Latitude"},"longitude":{"type":"number","title":"Longitude"},"classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classification"},"district":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"District"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"description_status":{"type":"string","enum":["available","missing","unavailable"],"title":"Description Status","default":"missing"},"last_sample_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Sample Date"},"total_samples":{"type":"integer","title":"Total Samples","default":0}},"type":"object","required":["site_id","name","latitude","longitude"],"title":"SiteDetail","description":"Detailed metadata for a bathing water site."},"SiteHistoryPoint":{"properties":{"date":{"type":"string","format":"date-time","title":"Date"},"ec":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ec"},"ie":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ie"},"fc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fc"},"fs":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fs"},"tc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tc"},"ec_unified":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ec Unified"},"ie_unified":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ie Unified"},"ec_rolling_4yr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ec Rolling 4Yr"},"ie_rolling_4yr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ie Rolling 4Yr"},"classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classification"}},"type":"object","required":["date"],"title":"SiteHistoryPoint","description":"Time series point for bathing water measurements."},"SiteHistoryResponse":{"properties":{"site_id":{"type":"string","title":"Site Id"},"points":{"items":{"$ref":"#/components/schemas/SiteHistoryPoint"},"type":"array","title":"Points"},"summary":{"$ref":"#/components/schemas/SiteHistorySummary"},"classifications":{"items":{"$ref":"#/components/schemas/SiteAnnualClassification"},"type":"array","title":"Classifications"},"trend_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Trend Pct"}},"type":"object","required":["site_id","points","summary"],"title":"SiteHistoryResponse","description":"Response model for site historical data."},"SiteHistorySummary":{"properties":{"total_samples":{"type":"integer","title":"Total Samples","default":0},"start_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date"},"modern_samples":{"additionalProperties":{"type":"integer"},"type":"object","title":"Modern Samples"},"legacy_samples":{"additionalProperties":{"type":"integer"},"type":"object","title":"Legacy Samples"},"unified_samples":{"additionalProperties":{"type":"integer"},"type":"object","title":"Unified Samples"}},"type":"object","title":"SiteHistorySummary","description":"Aggregated information about a site's sampling history."},"SiteSummary":{"properties":{"site_id":{"type":"string","title":"Site Id"},"name":{"type":"string","title":"Name"},"latitude":{"type":"number","title":"Latitude"},"longitude":{"type":"number","title":"Longitude"},"classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classification"},"district":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"District"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["site_id","name","latitude","longitude"],"title":"SiteSummary","description":"Summary information about a bathing water site."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"Bot API v1","description":"Stable public endpoints for bot integrations, data and graph downloads."},{"name":"sites","description":"Existing dashboard data endpoints."}]}