{ "openapi": "3.0.3", "info": { "title": "HospitalWaits Public API", "version": "1.0.0", "description": "Free public read-only JSON API for NHS England waiting-time data. Provides per-trust RTT and DM01 waits, the national specialty directory, and a ranked national league table per specialty. CORS-open, no auth, ISR-cached. Licensed under the UK Open Government Licence v3.0.", "termsOfService": "https://hospitalwaits.co.uk/terms", "contact": { "name": "HospitalWaits (Doctor Data Ltd)", "url": "https://hospitalwaits.co.uk", "email": "mustafa@doctor-data.co.uk" }, "license": { "name": "Open Government Licence v3.0", "url": "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" } }, "servers": [ { "url": "https://hospitalwaits.co.uk/api/v1", "description": "Production" } ], "externalDocs": { "description": "Human-readable docs", "url": "https://hospitalwaits.co.uk/api/docs" }, "tags": [ { "name": "RTT", "description": "Referral to Treatment waiting times." }, { "name": "DM01", "description": "Monthly Diagnostic Waiting Times." }, { "name": "A&E", "description": "Monthly A&E performance statistics (NOT live queue times)." } ], "paths": { "/specialties": { "get": { "tags": [ "RTT" ], "summary": "List supported specialties.", "operationId": "listSpecialties", "responses": { "200": { "description": "List of 18 NHS specialties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecialtyListResponse" } } } } } } }, "/trusts": { "get": { "tags": [ "RTT" ], "summary": "Paginated directory of NHS trusts.", "operationId": "listTrusts", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Up to 100 trusts per page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustListResponse" } } } } } } }, "/wait": { "get": { "tags": [ "RTT" ], "summary": "Single trust × specialty RTT wait.", "operationId": "getWait", "parameters": [ { "name": "trust", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Trust slug — see /trusts." }, { "name": "specialty", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Specialty slug — see /specialties." } ], "responses": { "200": { "description": "Resolved wait (or no_data soft-fail).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/national/{specialty}": { "get": { "tags": [ "RTT" ], "summary": "Ranked list of trusts for a specialty.", "operationId": "getNationalRanking", "parameters": [ { "name": "specialty", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Specialty slug — see /specialties." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "wait", "list_size", "pct_within_18_weeks" ], "default": "wait" } } ], "responses": { "200": { "description": "Ranked trusts. Excludes median = 0 or list size < 10.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NationalRankingResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/diagnostic": { "get": { "tags": [ "DM01" ], "summary": "DM01 single-trust diagnostic wait.", "operationId": "getDiagnostic", "parameters": [ { "name": "trust", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "procedure", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^DM01_(0[1-9]|1[0-5])$", "example": "DM01_01" }, "description": "DM01 procedure code (DM01_01..DM01_15)." } ], "responses": { "200": { "description": "Resolved DM01 wait (or no_data soft-fail).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/ae": { "get": { "tags": [ "A&E" ], "summary": "Latest month's A&E performance for every trust with a major (Type 1) ED. Monthly statistics — NOT live queue times.", "operationId": "listAePerformance", "responses": { "200": { "description": "One row per ED trust: Type-1 4-hour %, 12-hour decision-to-admit waits, attendances.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "A&E data temporarily unavailable." } } } }, "/ae/{trustSlug}": { "get": { "tags": [ "A&E" ], "summary": "One trust's A&E record: latest month, monthly history, national rank. Monthly statistics — NOT live queue times.", "operationId": "getAePerformance", "parameters": [ { "name": "trustSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust slug — see /trusts or /ae." } ], "responses": { "200": { "description": "A&E record for the trust.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown slug, or the trust has no major (Type 1) emergency department." } } } }, "/csv/rtt-latest.csv": { "get": { "tags": [ "RTT" ], "summary": "Latest month's full RTT extract (every trust × specialty) as a CSV snapshot with #-comment attribution rows.", "operationId": "getRttCsvSnapshot", "responses": { "200": { "description": "CSV file. Lines starting with # are attribution comments.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "503": { "description": "RTT data temporarily unavailable." } } } }, "/csv/ae-latest.csv": { "get": { "tags": [ "A&E" ], "summary": "Latest month's A&E performance as a CSV snapshot with #-comment attribution rows.", "operationId": "getAeCsvSnapshot", "responses": { "200": { "description": "CSV file. Lines starting with # are attribution comments.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "503": { "description": "A&E data temporarily unavailable." } } } } }, "components": { "schemas": { "AttributionFields": { "type": "object", "properties": { "source": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "lastUpdated": { "type": "string", "format": "date", "nullable": true }, "license": { "type": "string", "example": "Open Government Licence v3.0" }, "licenseUrl": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "publisherUrl": { "type": "string", "format": "uri" }, "apiVersion": { "type": "string", "example": "v1" }, "terms": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" } }, "required": [ "source", "sourceUrl", "license", "licenseUrl", "publisher", "publisherUrl", "apiVersion", "terms", "docs" ] }, "Meta": { "type": "object", "properties": { "resultCount": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "sort": { "type": "string" }, "nextUrl": { "type": "string", "nullable": true }, "methodologyNote": { "type": "string" } } }, "Specialty": { "type": "object", "properties": { "code": { "type": "string", "example": "C_110" }, "slug": { "type": "string", "example": "trauma-orthopaedics" }, "name": { "type": "string", "example": "Trauma & Orthopaedics" }, "url": { "type": "string", "format": "uri" }, "apiUrl": { "type": "string", "format": "uri" } } }, "Trust": { "type": "object", "properties": { "odsCode": { "type": "string", "example": "RAS" }, "slug": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "cqcRating": { "type": "string", "nullable": true, "enum": [ "Outstanding", "Good", "Requires improvement", "Inadequate", null ] }, "isIndependent": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "apiUrl": { "type": "string", "format": "uri" } } }, "WaitMetrics": { "type": "object", "properties": { "medianWeeks": { "type": "number", "example": 14.2 }, "totalWaiting": { "type": "integer", "example": 4231 }, "pctWithin18Weeks": { "type": "number", "example": 67.3 }, "pathwayType": { "type": "string", "example": "incomplete" }, "period": { "type": "string", "example": "RTT-January-2026" }, "periodDate": { "type": "string", "format": "date" } } }, "RankedTrust": { "type": "object", "properties": { "rank": { "type": "integer" }, "odsCode": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "cqcRating": { "type": "string", "nullable": true }, "isIndependent": { "type": "boolean" }, "trustType": { "type": "string", "enum": [ "acute", "community", "mental_health", "specialist", "independent" ] }, "medianWeeks": { "type": "number" }, "totalWaiting": { "type": "integer" }, "pctWithin18Weeks": { "type": "number" }, "url": { "type": "string", "format": "uri" }, "apiUrl": { "type": "string", "format": "uri" } } }, "DiagnosticProcedure": { "type": "object", "properties": { "code": { "type": "string", "example": "DM01_01" }, "name": { "type": "string", "nullable": true, "example": "Magnetic Resonance Imaging" } } }, "DiagnosticWaitMetrics": { "type": "object", "properties": { "medianWeeks": { "type": "number", "nullable": true }, "totalWaiting": { "type": "integer", "nullable": true }, "within6Weeks": { "type": "integer", "nullable": true }, "over6Weeks": { "type": "integer", "nullable": true }, "over13Weeks": { "type": "integer", "nullable": true }, "pctWithin6Weeks": { "type": "number", "nullable": true }, "period": { "type": "string", "example": "DM01-March-2026" }, "periodDate": { "type": "string", "format": "date" } } }, "SpecialtyListResponse": { "allOf": [ { "$ref": "#/components/schemas/AttributionFields" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Specialty" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } ] }, "TrustListResponse": { "allOf": [ { "$ref": "#/components/schemas/AttributionFields" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trust" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } ] }, "WaitResponse": { "allOf": [ { "$ref": "#/components/schemas/AttributionFields" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "trust": { "$ref": "#/components/schemas/Trust" }, "specialty": { "$ref": "#/components/schemas/Specialty" }, "wait": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WaitMetrics" } ] }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } } } } } ] }, "NationalRankingResponse": { "allOf": [ { "$ref": "#/components/schemas/AttributionFields" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "specialty": { "$ref": "#/components/schemas/Specialty" }, "stats": { "type": "object", "nullable": true, "properties": { "trustCount": { "type": "integer" }, "totalWaiting": { "type": "integer" }, "medianWaitWeeks": { "type": "number" }, "pctWithin18Weeks": { "type": "number" } } }, "ranking": { "type": "array", "items": { "$ref": "#/components/schemas/RankedTrust" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } ] }, "DiagnosticResponse": { "allOf": [ { "$ref": "#/components/schemas/AttributionFields" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "trust": { "$ref": "#/components/schemas/Trust" }, "procedure": { "$ref": "#/components/schemas/DiagnosticProcedure" }, "wait": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DiagnosticWaitMetrics" } ] }, "standard": { "type": "object", "properties": { "name": { "type": "string" }, "headlineMetric": { "type": "string" }, "target": { "type": "string" } } }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } } } } } ] }, "ErrorResponse": { "allOf": [ { "$ref": "#/components/schemas/AttributionFields" }, { "type": "object", "properties": { "data": { "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ] } } } ] } }, "responses": { "Error": { "description": "Validation or resolution error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }