{"openapi":"3.1.0","info":{"title":"UK Bin Collection API","description":"Look up bin collection schedules for UK councils","version":"2.0.0"},"paths":{"/api/v2/councils":{"get":{"summary":"List Councils","operationId":"list_councils_api_v2_councils_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CouncilInfo"},"type":"array","title":"Response List Councils Api V2 Councils Get"}}}}}}},"/api/v2/status":{"get":{"summary":"System Status","operationId":"system_status_api_v2_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemHealth"}}}}}}},"/api/v2/metrics":{"get":{"summary":"Metrics","operationId":"metrics_api_v2_metrics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v2/find":{"get":{"summary":"Find","description":"The postcode's council and its addresses, each with the UPRN to pass to /view.\n\n`council` is the LAD code when we serve the council. Otherwise `addresses`\nis empty and `deeplink` points at the council's own page, or `candidates`\nlists the councils a postcode straddles. Where Turnstile is configured the\naddress list needs an `X-Turnstile-Token` header; without one `addresses`\nis null and the rest still answers.","operationId":"find_api_v2_find_get","parameters":[{"name":"postcode","in":"query","required":true,"schema":{"type":"string","description":"The postcode to look up.","title":"Postcode"},"description":"The postcode to look up."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/{lad}/view/{uprn}":{"get":{"summary":"View","description":"Collection dates, ascending; a deeplink instead when we can't fetch them.\n\nCouncils that need more than the UPRN (postcode, address label,\nproperty_id, usrn...) take it as query params; /councils lists them.","operationId":"view_api_v2__lad__view__uprn__get","parameters":[{"name":"uprn","in":"path","required":true,"schema":{"type":"string","title":"Uprn"}},{"name":"lad","in":"path","required":true,"schema":{"type":"string","description":"The council's ONS LAD code (e.g. E06000001), as /find returns it. Scraper IDs from before the switch to LAD codes still resolve.","title":"Lad"},"description":"The council's ONS LAD code (e.g. E06000001), as /find returns it. Scraper IDs from before the switch to LAD codes still resolve."},{"name":"postcode","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postcode"}},{"name":"address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/{lad}/subscribe/{uprn}":{"get":{"summary":"Subscribe","description":"The ICS feed, for a calendar subscription (webcal).","operationId":"subscribe_api_v2__lad__subscribe__uprn__get","parameters":[{"name":"uprn","in":"path","required":true,"schema":{"type":"string","title":"Uprn"}},{"name":"lad","in":"path","required":true,"schema":{"type":"string","description":"The council's ONS LAD code (e.g. E06000001), as /find returns it. Scraper IDs from before the switch to LAD codes still resolve.","title":"Lad"},"description":"The council's ONS LAD code (e.g. E06000001), as /find returns it. Scraper IDs from before the switch to LAD codes still resolve."},{"name":"postcode","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postcode"}},{"name":"address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"}}],"responses":{"200":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/{lad}/download/{uprn}":{"get":{"summary":"Download","description":"The ICS as a file download.","operationId":"download_api_v2__lad__download__uprn__get","parameters":[{"name":"uprn","in":"path","required":true,"schema":{"type":"string","title":"Uprn"}},{"name":"lad","in":"path","required":true,"schema":{"type":"string","description":"The council's ONS LAD code (e.g. E06000001), as /find returns it. Scraper IDs from before the switch to LAD codes still resolve.","title":"Lad"},"description":"The council's ONS LAD code (e.g. E06000001), as /find returns it. Scraper IDs from before the switch to LAD codes still resolve."},{"name":"postcode","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postcode"}},{"name":"address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"}}],"responses":{"200":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AddressResult":{"properties":{"uprn":{"type":"string","title":"Uprn"},"full_address":{"type":"string","title":"Full Address"},"postcode":{"type":"string","title":"Postcode"},"address_line_1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line 1"},"house_number_or_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"House Number Or Name"},"street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Street"}},"type":"object","required":["uprn","full_address","postcode"],"title":"AddressResult"},"Blocker":{"type":"string","enum":["captcha","login","bot_protection","browser_only","no_lookup","site_down","not_supported"],"title":"Blocker","description":"Why a council answers with a link to its own site instead of bin days.\n\nPublic: deeplinks carry it as `blocker`, with `label` as `blocker_label`."},"CollectionDate":{"properties":{"date":{"type":"string","format":"date","title":"Date"},"holiday":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Holiday"},"type":{"$ref":"#/components/schemas/CollectionType"}},"type":"object","required":["date","type"],"title":"CollectionDate"},"CollectionType":{"properties":{"label":{"type":"string","title":"Label"},"colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colour"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"}},"type":"object","required":["label"],"title":"CollectionType"},"CouncilCandidate":{"properties":{"council":{"type":"string","title":"Council"},"name":{"type":"string","title":"Name"},"homepage_url":{"type":"string","title":"Homepage Url"}},"type":"object","required":["council","name","homepage_url"],"title":"CouncilCandidate"},"CouncilInfo":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","title":"Url"},"params":{"items":{"type":"string"},"type":"array","title":"Params"}},"type":"object","required":["id","name","url","params"],"title":"CouncilInfo"},"DeeplinkInfo":{"properties":{"url":{"type":"string","title":"Url"},"reason":{"type":"string","title":"Reason"},"council_name":{"type":"string","title":"Council Name"},"blocker":{"$ref":"#/components/schemas/Blocker","description":"Why there are no bin days: captcha, login, bot_protection, browser_only, no_lookup, site_down or not_supported."},"blocker_label":{"type":"string","title":"Blocker Label","description":"`blocker` in words, e.g. \"Requires a captcha\"."}},"type":"object","required":["url","reason","council_name","blocker","blocker_label"],"title":"DeeplinkInfo"},"FindResponse":{"properties":{"postcode":{"type":"string","title":"Postcode"},"council":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Council"},"council_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Council Name"},"candidates":{"items":{"$ref":"#/components/schemas/CouncilCandidate"},"type":"array","title":"Candidates","default":[]},"deeplink":{"anyOf":[{"$ref":"#/components/schemas/DeeplinkInfo"},{"type":"null"}]},"addresses":{"anyOf":[{"items":{"$ref":"#/components/schemas/AddressResult"},"type":"array"},{"type":"null"}],"title":"Addresses","default":[]}},"type":"object","required":["postcode"],"title":"FindResponse","description":"A postcode's council and addresses.\n\n`council` is the LAD code when we serve the council; otherwise `deeplink`\n(unwired, or a scraper that needs a browser) or `candidates` (a postcode\nstraddling councils) says what to do instead, and `addresses` is empty.\n`addresses` is None when the request had no Turnstile token."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ScheduleResponse":{"properties":{"uprn":{"type":"string","title":"Uprn"},"council":{"type":"string","title":"Council"},"cached":{"type":"boolean","title":"Cached","default":false},"cached_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Cached At"},"dates":{"items":{"$ref":"#/components/schemas/CollectionDate"},"type":"array","title":"Dates","default":[]},"deeplink":{"anyOf":[{"$ref":"#/components/schemas/DeeplinkInfo"},{"type":"null"}]}},"type":"object","required":["uprn","council"],"title":"ScheduleResponse"},"SystemHealth":{"properties":{"status":{"type":"string","title":"Status"},"scraper_count":{"type":"integer","title":"Scraper Count"},"postcode_lookup":{"type":"boolean","title":"Postcode Lookup"},"lad_lookup":{"type":"boolean","title":"Lad Lookup"}},"type":"object","required":["status","scraper_count","postcode_lookup","lad_lookup"],"title":"SystemHealth"},"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"}}}}