{
 "openapi": "3.1.0",
 "info": {
  "title": "CouncilData API",
  "version": "1.0.0",
  "description": "Verified UK local government data. Every row carries provenance: source_url, verified_date, status. Free static tier served from councildata.co.uk/api/v1 (attribution required, CC BY 4.0). Keyed commercial tiers (history, change feed, alerts) launch at api.councildata.co.uk with identical paths.",
  "contact": {
   "email": "hello@councildata.co.uk"
  },
  "license": {
   "name": "CC BY 4.0",
   "url": "https://creativecommons.org/licenses/by/4.0/"
  }
 },
 "servers": [
  {
   "url": "https://councildata.co.uk/api/v1"
  }
 ],
 "paths": {
  "/meta.json": {
   "get": {
    "summary": "Dataset versions, counts, licence",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/council-tax/2026-27.json": {
   "get": {
    "summary": "All 350 councils, full band tables with provenance",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CouncilTaxList"
        }
       }
      }
     }
    }
   }
  },
  "/council-tax/2026-27/{slug}.json": {
   "get": {
    "summary": "One council's full record",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "birmingham"
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Unknown slug"
     }
    }
   }
  },
  "/contacts.json": {
   "get": {
    "summary": "Verified council service phone numbers (planning priority)",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/premiums.json": {
   "get": {
    "summary": "Second home and empty homes premiums per council (% and effective dates)",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/parking.json": {
   "get": {
    "summary": "CPZ presence and resident permit price ranges per council (collection from late 2026)",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "CouncilTaxRecord": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "council": {
      "type": "string"
     },
     "slug": {
      "type": "string"
     },
     "nation": {
      "type": "string",
      "enum": [
       "england",
       "scotland",
       "wales"
      ]
     },
     "period": {
      "type": "string"
     },
     "band_d_total": {
      "type": [
       "number",
       "null"
      ]
     },
     "bands": {
      "type": [
       "object",
       "null"
      ],
      "additionalProperties": {
       "type": [
        "number",
        "null"
       ]
      }
     },
     "pct_change_yoy": {
      "type": [
       "number",
       "null"
      ]
     },
     "includes": {
      "type": [
       "string",
       "null"
      ]
     },
     "area_note": {
      "type": [
       "string",
       "null"
      ]
     },
     "asc_precept_note": {
      "type": [
       "string",
       "null"
      ]
     },
     "unit": {
      "type": "string"
     },
     "source_url": {
      "type": [
       "string",
       "null"
      ]
     },
     "source_title": {
      "type": [
       "string",
       "null"
      ]
     },
     "verified_date": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "verified",
       "unverified"
      ]
     },
     "notes": {
      "type": [
       "string",
       "null"
      ]
     },
     "page": {
      "type": "string"
     }
    },
    "required": [
     "id",
     "council",
     "slug",
     "nation",
     "period",
     "unit",
     "status"
    ]
   },
   "CouncilTaxList": {
    "type": "object",
    "properties": {
     "meta": {
      "type": "object"
     },
     "count": {
      "type": "integer"
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CouncilTaxRecord"
      }
     }
    }
   }
  }
 }
}