{ "components": { "responses": { "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request is malformed: no body, a bad parameter, or an unknown field." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such calculator or document." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is over 64 KiB." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is not JSON." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "One or more fields are invalid. error.fields lists every one, each with a message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests from this address. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "schemas": { "CalculatorDetail": { "properties": { "calculator": { "properties": { "category": { "type": "string" }, "description": { "type": "string" }, "example": true, "id": { "type": "string" }, "inputSchema": { "description": "A JSON Schema (draft 2020-12).", "type": [ "null", "object" ] }, "outputSchema": { "description": "A JSON Schema (draft 2020-12).", "type": [ "null", "object" ] }, "reference": { "additionalProperties": true, "type": "object" }, "standard": { "type": "string" }, "summary": { "description": "One sentence on what it works out.", "type": "string" }, "tier": { "type": "string" }, "title": { "type": "string" }, "webPath": { "type": "string" } }, "required": [ "id", "title", "summary", "tier", "description", "standard", "category", "webPath", "example" ], "type": "object" }, "contentType": { "type": "string" }, "method": { "type": "string" }, "notice": { "type": "string" }, "url": { "type": "string" }, "version": { "type": "string" }, "webUrl": { "type": "string" } }, "required": [ "version", "calculator", "url", "webUrl", "method", "contentType", "notice" ], "type": "object" }, "CalculatorList": { "properties": { "calculators": { "items": { "properties": { "category": { "type": "string" }, "description": { "type": "string" }, "example": true, "id": { "type": "string" }, "inputSchema": { "description": "A JSON Schema (draft 2020-12).", "type": [ "null", "object" ] }, "outputSchema": { "description": "A JSON Schema (draft 2020-12).", "type": [ "null", "object" ] }, "reference": { "additionalProperties": true, "type": "object" }, "standard": { "type": "string" }, "summary": { "description": "One sentence on what it works out.", "type": "string" }, "tier": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "webPath": { "type": "string" }, "webUrl": { "type": "string" } }, "required": [ "id", "title", "summary", "tier", "description", "standard", "category", "webPath", "example", "url", "webUrl" ], "type": "object" }, "type": [ "null", "array" ] }, "count": { "type": "integer" }, "version": { "type": "string" } }, "required": [ "version", "count", "calculators" ], "type": "object" }, "CategoryList": { "properties": { "categories": { "items": { "properties": { "blurb": { "type": "string" }, "count": { "type": "integer" }, "documents": { "items": { "properties": { "apiUrl": { "description": "The same document as JSON.", "type": "string" }, "calculators": { "description": "Ids of calculators on this site that do the arithmetic described here.", "items": { "type": "string" }, "type": [ "null", "array" ] }, "category": { "description": "The subject key: 'basics', 'heat-pumps', 'solar-pv', 'batteries', 'standards' or 'paperwork'.", "type": "string" }, "categoryLabel": { "type": "string" }, "featured": { "type": "boolean" }, "kind": { "description": "'guide', 'article' or 'faq'.", "type": "string" }, "level": { "description": "Articles only: beginner, intermediate or advanced.", "type": "string" }, "levelLabel": { "type": "string" }, "perspective": { "description": "Guides only: who the guide is written for.", "type": "string" }, "perspectiveLabel": { "type": "string" }, "readingMinutes": { "type": "integer" }, "slug": { "type": "string" }, "sources": { "description": "The MCS documents this draws on. Cite these, not this site, when the point is a requirement of a standard.", "items": { "properties": { "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "title": { "type": "string" }, "updated": { "description": "The date of the last change, as YYYY-MM-DD.", "type": "string" }, "url": { "description": "The page, which is the address to cite.", "type": "string" } }, "required": [ "slug", "kind", "title", "summary", "category", "categoryLabel", "updated", "readingMinutes", "url", "apiUrl" ], "type": "object" }, "type": [ "null", "array" ] }, "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label", "blurb", "count", "documents" ], "type": "object" }, "type": [ "null", "array" ] }, "note": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "note", "categories" ], "type": "object" }, "Discovery": { "properties": { "alias": { "description": "The short address, which answers exactly as this version does and never moves to a later one.", "type": "string" }, "calculators": { "properties": { "count": { "type": "integer" }, "describe": { "type": "string" }, "detail": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "index": { "type": "string" } }, "required": [ "index", "count", "detail", "ids", "describe" ], "type": "object" }, "description": { "type": "string" }, "documents": { "properties": { "categories": { "type": "string" }, "detail": { "type": "string" }, "documents": { "type": "integer" }, "index": { "type": "string" }, "kinds": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "perspectives": { "type": "string" }, "questions": { "type": "integer" }, "search": { "type": "string" } }, "required": [ "index", "search", "categories", "perspectives", "detail", "kinds", "documents", "questions" ], "type": "object" }, "mcp": { "properties": { "calculators": { "type": "string" }, "documents": { "type": "string" }, "transport": { "type": "string" } }, "required": [ "calculators", "documents", "transport" ], "type": "object" }, "name": { "type": "string" }, "notice": { "type": "string" }, "openapi": { "description": "The OpenAPI 3.1 description of this API.", "type": "string" }, "standards": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version", "description", "openapi", "alias", "calculators", "documents", "mcp", "standards", "notice" ], "type": "object" }, "DocumentDetail": { "properties": { "document": { "properties": { "apiUrl": { "description": "The same document as JSON.", "type": "string" }, "calculators": { "description": "Ids of calculators on this site that do the arithmetic described here.", "items": { "type": "string" }, "type": [ "null", "array" ] }, "category": { "description": "The subject key: 'basics', 'heat-pumps', 'solar-pv', 'batteries', 'standards' or 'paperwork'.", "type": "string" }, "categoryLabel": { "type": "string" }, "featured": { "type": "boolean" }, "headings": { "description": "The in-page sections.", "items": { "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "type": [ "null", "array" ] }, "kind": { "description": "'guide', 'article' or 'faq'.", "type": "string" }, "level": { "description": "Articles only: beginner, intermediate or advanced.", "type": "string" }, "levelLabel": { "type": "string" }, "perspective": { "description": "Guides only: who the guide is written for.", "type": "string" }, "perspectiveLabel": { "type": "string" }, "questions": { "description": "For a set of questions, each question with its answer as Markdown.", "items": { "properties": { "answer": { "description": "The answer as plain text.", "type": "string" }, "id": { "type": "string" }, "question": { "type": "string" } }, "required": [ "id", "question", "answer" ], "type": "object" }, "type": [ "null", "array" ] }, "readingMinutes": { "type": "integer" }, "related": { "description": "Documents worth reading next.", "items": { "properties": { "apiUrl": { "description": "The same document as JSON.", "type": "string" }, "calculators": { "description": "Ids of calculators on this site that do the arithmetic described here.", "items": { "type": "string" }, "type": [ "null", "array" ] }, "category": { "description": "The subject key: 'basics', 'heat-pumps', 'solar-pv', 'batteries', 'standards' or 'paperwork'.", "type": "string" }, "categoryLabel": { "type": "string" }, "featured": { "type": "boolean" }, "kind": { "description": "'guide', 'article' or 'faq'.", "type": "string" }, "level": { "description": "Articles only: beginner, intermediate or advanced.", "type": "string" }, "levelLabel": { "type": "string" }, "perspective": { "description": "Guides only: who the guide is written for.", "type": "string" }, "perspectiveLabel": { "type": "string" }, "readingMinutes": { "type": "integer" }, "slug": { "type": "string" }, "sources": { "description": "The MCS documents this draws on. Cite these, not this site, when the point is a requirement of a standard.", "items": { "properties": { "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "title": { "type": "string" }, "updated": { "description": "The date of the last change, as YYYY-MM-DD.", "type": "string" }, "url": { "description": "The page, which is the address to cite.", "type": "string" } }, "required": [ "slug", "kind", "title", "summary", "category", "categoryLabel", "updated", "readingMinutes", "url", "apiUrl" ], "type": "object" }, "type": [ "null", "array" ] }, "slug": { "type": "string" }, "sources": { "description": "The MCS documents this draws on. Cite these, not this site, when the point is a requirement of a standard.", "items": { "properties": { "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "text": { "description": "The document as Markdown: prose, with headings and tables. For a set of questions this is every question and answer run together; they also come back separately in questions.", "type": "string" }, "title": { "type": "string" }, "updated": { "description": "The date of the last change, as YYYY-MM-DD.", "type": "string" }, "url": { "description": "The page, which is the address to cite.", "type": "string" } }, "required": [ "slug", "kind", "title", "summary", "category", "categoryLabel", "updated", "readingMinutes", "url", "apiUrl" ], "type": "object" }, "notice": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "document", "notice" ], "type": "object" }, "DocumentList": { "properties": { "count": { "type": "integer" }, "documents": { "description": "Summaries, or with full=true the full documents. A full document is a summary with its text added.", "items": { "properties": { "apiUrl": { "description": "The same document as JSON.", "type": "string" }, "calculators": { "description": "Ids of calculators on this site that do the arithmetic described here.", "items": { "type": "string" }, "type": [ "null", "array" ] }, "category": { "description": "The subject key: 'basics', 'heat-pumps', 'solar-pv', 'batteries', 'standards' or 'paperwork'.", "type": "string" }, "categoryLabel": { "type": "string" }, "featured": { "type": "boolean" }, "headings": { "description": "The in-page sections.", "items": { "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "type": [ "null", "array" ] }, "kind": { "description": "'guide', 'article' or 'faq'.", "type": "string" }, "level": { "description": "Articles only: beginner, intermediate or advanced.", "type": "string" }, "levelLabel": { "type": "string" }, "perspective": { "description": "Guides only: who the guide is written for.", "type": "string" }, "perspectiveLabel": { "type": "string" }, "questions": { "description": "For a set of questions, each question with its answer as Markdown.", "items": { "properties": { "answer": { "description": "The answer as plain text.", "type": "string" }, "id": { "type": "string" }, "question": { "type": "string" } }, "required": [ "id", "question", "answer" ], "type": "object" }, "type": [ "null", "array" ] }, "readingMinutes": { "type": "integer" }, "related": { "description": "Documents worth reading next.", "items": { "properties": { "apiUrl": { "description": "The same document as JSON.", "type": "string" }, "calculators": { "description": "Ids of calculators on this site that do the arithmetic described here.", "items": { "type": "string" }, "type": [ "null", "array" ] }, "category": { "description": "The subject key: 'basics', 'heat-pumps', 'solar-pv', 'batteries', 'standards' or 'paperwork'.", "type": "string" }, "categoryLabel": { "type": "string" }, "featured": { "type": "boolean" }, "kind": { "description": "'guide', 'article' or 'faq'.", "type": "string" }, "level": { "description": "Articles only: beginner, intermediate or advanced.", "type": "string" }, "levelLabel": { "type": "string" }, "perspective": { "description": "Guides only: who the guide is written for.", "type": "string" }, "perspectiveLabel": { "type": "string" }, "readingMinutes": { "type": "integer" }, "slug": { "type": "string" }, "sources": { "description": "The MCS documents this draws on. Cite these, not this site, when the point is a requirement of a standard.", "items": { "properties": { "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "title": { "type": "string" }, "updated": { "description": "The date of the last change, as YYYY-MM-DD.", "type": "string" }, "url": { "description": "The page, which is the address to cite.", "type": "string" } }, "required": [ "slug", "kind", "title", "summary", "category", "categoryLabel", "updated", "readingMinutes", "url", "apiUrl" ], "type": "object" }, "type": [ "null", "array" ] }, "slug": { "type": "string" }, "sources": { "description": "The MCS documents this draws on. Cite these, not this site, when the point is a requirement of a standard.", "items": { "properties": { "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "text": { "description": "The document as Markdown: prose, with headings and tables. For a set of questions this is every question and answer run together; they also come back separately in questions.", "type": "string" }, "title": { "type": "string" }, "updated": { "description": "The date of the last change, as YYYY-MM-DD.", "type": "string" }, "url": { "description": "The page, which is the address to cite.", "type": "string" } }, "required": [ "slug", "kind", "title", "summary", "category", "categoryLabel", "updated", "readingMinutes", "url", "apiUrl" ], "type": "object" }, "type": "array" }, "version": { "type": "string" } }, "required": [ "version", "count", "documents" ], "type": "object" }, "Error": { "properties": { "error": { "properties": { "code": { "type": "string" }, "fields": { "items": { "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ], "type": "object" }, "type": [ "null", "array" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "PerspectiveList": { "properties": { "note": { "type": "string" }, "perspectives": { "items": { "properties": { "blurb": { "type": "string" }, "count": { "type": "integer" }, "guides": { "items": { "properties": { "apiUrl": { "description": "The same document as JSON.", "type": "string" }, "calculators": { "description": "Ids of calculators on this site that do the arithmetic described here.", "items": { "type": "string" }, "type": [ "null", "array" ] }, "category": { "description": "The subject key: 'basics', 'heat-pumps', 'solar-pv', 'batteries', 'standards' or 'paperwork'.", "type": "string" }, "categoryLabel": { "type": "string" }, "featured": { "type": "boolean" }, "kind": { "description": "'guide', 'article' or 'faq'.", "type": "string" }, "level": { "description": "Articles only: beginner, intermediate or advanced.", "type": "string" }, "levelLabel": { "type": "string" }, "perspective": { "description": "Guides only: who the guide is written for.", "type": "string" }, "perspectiveLabel": { "type": "string" }, "readingMinutes": { "type": "integer" }, "slug": { "type": "string" }, "sources": { "description": "The MCS documents this draws on. Cite these, not this site, when the point is a requirement of a standard.", "items": { "properties": { "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "title": { "type": "string" }, "updated": { "description": "The date of the last change, as YYYY-MM-DD.", "type": "string" }, "url": { "description": "The page, which is the address to cite.", "type": "string" } }, "required": [ "slug", "kind", "title", "summary", "category", "categoryLabel", "updated", "readingMinutes", "url", "apiUrl" ], "type": "object" }, "type": [ "null", "array" ] }, "key": { "type": "string" }, "label": { "description": "The phrase a reader would use about themselves.", "type": "string" }, "technical": { "type": "boolean" }, "trade": { "type": "boolean" }, "who": { "description": "Who this is for, in a few words.", "type": "string" } }, "required": [ "key", "label", "who", "blurb", "technical", "trade", "count", "guides" ], "type": "object" }, "type": [ "null", "array" ] }, "version": { "type": "string" } }, "required": [ "version", "note", "perspectives" ], "type": "object" }, "SearchResults": { "properties": { "count": { "type": "integer" }, "query": { "type": "string" }, "results": { "items": { "properties": { "apiUrl": { "description": "The same document as JSON.", "type": "string" }, "calculators": { "description": "Ids of calculators on this site that do the arithmetic described here.", "items": { "type": "string" }, "type": [ "null", "array" ] }, "category": { "description": "The subject key: 'basics', 'heat-pumps', 'solar-pv', 'batteries', 'standards' or 'paperwork'.", "type": "string" }, "categoryLabel": { "type": "string" }, "featured": { "type": "boolean" }, "kind": { "description": "'guide', 'article' or 'faq'.", "type": "string" }, "level": { "description": "Articles only: beginner, intermediate or advanced.", "type": "string" }, "levelLabel": { "type": "string" }, "matchedQuestion": { "description": "Where the query matched one question inside a set, that question and its answer, which is often the whole answer to the query.", "properties": { "answer": { "description": "The answer as plain text.", "type": "string" }, "id": { "type": "string" }, "question": { "type": "string" } }, "required": [ "id", "question", "answer" ], "type": [ "null", "object" ] }, "perspective": { "description": "Guides only: who the guide is written for.", "type": "string" }, "perspectiveLabel": { "type": "string" }, "readingMinutes": { "type": "integer" }, "score": { "type": "integer" }, "slug": { "type": "string" }, "sources": { "description": "The MCS documents this draws on. Cite these, not this site, when the point is a requirement of a standard.", "items": { "properties": { "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "title": { "type": "string" }, "updated": { "description": "The date of the last change, as YYYY-MM-DD.", "type": "string" }, "url": { "description": "The page, which is the address to cite.", "type": "string" } }, "required": [ "slug", "kind", "title", "summary", "category", "categoryLabel", "updated", "readingMinutes", "url", "apiUrl", "score" ], "type": "object" }, "type": [ "null", "array" ] }, "version": { "type": "string" } }, "required": [ "version", "query", "count", "results" ], "type": "object" } } }, "externalDocs": { "description": "The developer page, with the MCP servers as well", "url": "https://ampworth.com/developers" }, "info": { "description": "Open and unauthenticated: no key, no sign-up, and CORS open to any origin. Requests are rate limited per address. Every path here also answers under /api in place of /api/v1, identically and permanently; a later version will get a prefix of its own and leave both alone. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.", "summary": "UK home energy calculators and reference material, following the published MCS standards.", "title": "Ampworth", "version": "1.0" }, "openapi": "3.1.0", "paths": { "/api/v1": { "get": { "description": "The calculator ids, the document endpoints and the two MCP URLs: everything needed to find the rest.", "operationId": "discovery", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" } } }, "description": "OK" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Discovery", "tags": [ "discovery" ] } }, "/api/v1/calculators": { "get": { "description": "Every calculator, the MCS standard it follows, a working example request and the URL that runs it. The schemas and the reference data are left out here and come with the detail endpoint.", "operationId": "listCalculators", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculatorList" } } }, "description": "OK" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "List the calculators", "tags": [ "calculators" ] } }, "/api/v1/calculators/heat-pump-noise": { "post": { "description": "Calculate the sound pressure level an air source heat pump produces at an assessment\nposition, and whether it meets the 37 dB(A) permitted development noise limit, using the method in\nMCS 020.\n\nThe formula is Lp = Lw + 10 log(Q / 4.pi.r^2) - Ab.\n\nLw is the A-weighted sound POWER level of the unit from its product fiche, energy label or the MCS\nproduct database. This is not the sound pressure level, which is a smaller number that already has a\ndistance built into it; confusing the two produces an answer that is wrong by about twenty decibels.\nThe figure for low noise mode must not be used.\n\nQ is the directivity factor, from the count of reflecting surfaces within one metre of the unit that\nextend at least a metre past it in two or more directions. The ground counts; vegetation does not.\nOne surface gives Q=2, two gives Q=4, three gives Q=8. More than three cannot meet MCS 020 at all.\n\nr is the straight-line distance in metres to the assessment position, which is a window or door of a\nhabitable room in a NEIGHBOURING property, at any floor. Every affected position must be checked\nseparately, and the nearest is not always the worst.\n\nAb is the barrier attenuation. Fences with gaps, and vegetation of any kind, count as no barrier.\n\nWhere several units serve one position, list them all and they are combined logarithmically.\n\nMethod from MCS 020.", "operationId": "runHeatPumpNoise", "requestBody": { "content": { "application/json": { "example": { "units": [ { "soundPowerLevel": 58, "distance": 8, "reflectingSurfaces": 2, "barrierType": "type_1", "lineOfSight": "partial" } ] }, "schema": { "type": "object", "properties": { "units": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "soundPowerLevel": { "type": "number", "description": "A-weighted sound POWER level of the unit in dB(A), from the product fiche, the energy label or the MCS product database. Not the sound pressure level, which is a different and smaller number. The figure for low noise mode must not be used. Required." }, "distance": { "type": "number", "description": "Straight-line distance in metres from the centre of the unit to the assessment position, measured to the nearest 0.1 m. Required." }, "reflectingSurfaces": { "type": "integer", "description": "How many surfaces sit within one metre of the unit and extend at least a metre past it in two or more directions. The ground counts; vegetation does not. 1, 2 or 3. More than 3 fails MCS 020 outright. Required." }, "barrierType": { "type": "string", "description": "'type_1' for solid masonry or a solid fence at least 18 mm thick, 'type_2' for a solid fence thinner than 18 mm, or 'none'. Fences with gaps, and vegetation, are 'none'. Defaults to 'none'." }, "lineOfSight": { "type": "string", "description": "Whether the assessment position can be seen from the top edge of the unit: 'none', 'partial' (visible if you move up to 0.25 m in any direction) or 'full'. Defaults to 'full'." }, "label": { "type": "string", "description": "A name for this unit, for a result covering more than one." } }, "required": [ "soundPowerLevel", "distance", "reflectingSurfaces" ], "additionalProperties": false }, "description": "The heat pump or heat pumps being assessed, each with its own distance and barrier to this assessment position. At least one is required." } }, "required": [ "units" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "compliant": { "description": "True when the level is at or below the limit.", "type": "boolean" }, "headroom": { "description": "Decibels below the limit. Negative when the limit is exceeded.", "type": "number" }, "limit": { "description": "The permitted development noise limit, 37.0 dB(A).", "type": "number" }, "method": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "remedies": { "description": "What would bring a failing position within the limit.", "items": { "type": "string" }, "type": [ "null", "array" ] }, "soundPressureLevel": { "description": "Combined A-weighted sound pressure level at the assessment position, in dB(A), rounded to one decimal place as MCS 020 requires.", "type": "number" }, "units": { "items": { "properties": { "barrierAttenuation": { "description": "Decibels the barrier takes off, from the MCS 020 matrix.", "type": "number" }, "directivity": { "description": "Q: 2 for one reflecting surface, 4 for two, 8 for three.", "type": "integer" }, "distance": { "type": "number" }, "distanceLoss": { "description": "Decibels lost to spreading out over the distance.", "type": "number" }, "label": { "type": "string" }, "soundPowerLevel": { "type": "number" }, "soundPressureLevel": { "type": "number" } }, "required": [ "soundPowerLevel", "distance", "directivity", "barrierAttenuation", "soundPressureLevel", "distanceLoss" ], "type": "object" }, "type": [ "null", "array" ] }, "verdict": { "type": "string" } }, "required": [ "units", "soundPressureLevel", "limit", "compliant", "headroom", "verdict", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Heat pump noise assessment", "tags": [ "calculators" ] } }, "/api/v1/calculators/heat-pump-running-cost": { "post": { "description": "Compare what a household spends heating on its current fuel with what the same heat\nwould cost from a heat pump.\n\nThe heat demand is worked out from the household's own metered fuel use, not from a model,\nbecause a year of bills describes a particular house far better than any estimate of it. Supply the\nannual fuel use in the fuel's own unit (kWh for gas and electricity, litres for oil and LPG, kilograms\nfor coal), its price per unit in pounds, and the seasonal efficiency of the existing appliance, which\ndefaults to a realistic figure for that fuel instead of the one on the badge.\n\nThe comparison turns on one ratio. A heat pump costs less to run whenever its seasonal coefficient of\nperformance beats the ratio between the price of a unit of electricity and the price of a unit of heat\nfrom the current fuel. The result reports that break-even figure explicitly.\n\nSCOP must be the figure at the flow temperature the system is actually designed for. The same machine\ncan return 4.2 at 35 degrees and 3.1 at 55, and quoting the first for a system designed at the second\nis the commonest way of overstating a saving.\n\nThis is a running cost comparison. It says nothing about the capital cost or any grant.\n\nMethod from MCS 007.", "operationId": "runHeatPumpRunningCost", "requestBody": { "content": { "application/json": { "example": { "fuel": "mains_gas", "annualFuelUse": 12000, "fuelPricePerUnit": 0.06, "fuelStandingChargePerDay": 0.31, "scop": 3.8, "electricityPricePerKwh": 0.25 }, "schema": { "type": "object", "properties": { "fuel": { "type": "string", "description": "The fuel being replaced: 'mains_gas', 'oil', 'lpg', 'electricity' or 'coal'. Defaults to 'mains_gas'." }, "annualFuelUse": { "type": "number", "description": "How much of that fuel the house uses in a year, in the fuel's own unit: kWh for gas and electricity, litres for oil and LPG, kilograms for coal. Take it from a year of bills. Required." }, "fuelPricePerUnit": { "type": "number", "description": "Price of one unit of that fuel, in pounds. Required." }, "fuelStandingChargePerDay": { "type": "number", "description": "Daily standing charge for that fuel in pounds, if it has one. A house that removes its gas boiler can usually stop paying this." }, "applianceEfficiency": { "type": "number", "description": "Seasonal efficiency of the existing appliance, as a decimal. Defaults to the typical figure for the fuel." }, "nonHeatingFraction": { "type": "number", "description": "Share of that fuel used for something other than heating and hot water, such as a gas hob, as a decimal. A hob is usually 0.03 to 0.05. Defaults to 0." }, "scop": { "type": "number", "description": "Seasonal coefficient of performance of the proposed heat pump: the units of heat it delivers per unit of electricity, averaged over a year at the design flow temperature. Required." }, "electricityPricePerKwh": { "type": "number", "description": "Price of a unit of electricity, in pounds. Required." }, "electricityStandingChargePerDay": { "type": "number", "description": "Daily electricity standing charge in pounds. It is paid either way, so it only changes the answer if the tariff changes with the heat pump." } }, "required": [ "annualFuelUse", "fuelPricePerUnit", "scop", "electricityPricePerKwh" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "annualDifference": { "description": "Positive when the heat pump costs less.", "type": "number" }, "annualHeatDemandKwh": { "description": "Useful heat the house actually needs in a year, after the existing appliance's losses are taken off its fuel input.", "type": "number" }, "applianceEfficiency": { "type": "number" }, "breakEvenPriceRatio": { "description": "How many times dearer a unit of electricity is than a unit of the current fuel. Compare it with the SCOP: a heat pump saves money whenever the SCOP beats this ratio.", "type": "number" }, "breakEvenScop": { "description": "The seasonal efficiency at which the heat pump costs exactly what the current system costs. Below this it costs more.", "type": "number" }, "costPerKwhHeatHeatPump": { "description": "What a unit of delivered heat would cost from the heat pump.", "type": "number" }, "costPerKwhHeatNow": { "description": "What a unit of delivered heat costs today, in pounds.", "type": "number" }, "currentAnnualCost": { "type": "number" }, "fuel": { "properties": { "key": { "type": "string" }, "kwhPerUnit": { "description": "Energy in a single unit of that fuel.", "type": "number" }, "name": { "type": "string" }, "typicalEfficiency": { "description": "Seasonal efficiency of a reasonable appliance burning it, as a decimal.", "type": "number" }, "unit": { "description": "The unit the fuel is normally metered or bought in.", "type": "string" } }, "required": [ "key", "name", "unit", "kwhPerUnit", "typicalEfficiency" ], "type": "object" }, "heatPumpAnnualCost": { "type": "number" }, "heatPumpElectricityKwh": { "description": "Units of electricity the heat pump would use in a year.", "type": "number" }, "method": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "percentDifference": { "type": "number" }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "scop": { "type": "number" }, "verdict": { "type": "string" } }, "required": [ "fuel", "applianceEfficiency", "scop", "annualHeatDemandKwh", "currentAnnualCost", "heatPumpAnnualCost", "annualDifference", "percentDifference", "heatPumpElectricityKwh", "costPerKwhHeatNow", "costPerKwhHeatHeatPump", "breakEvenScop", "breakEvenPriceRatio", "verdict", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Heat pump running cost", "tags": [ "calculators" ] } }, "/api/v1/calculators/heat-pump-size": { "post": { "description": "Estimate the heat pump a UK house needs, and what it would cost to run against the\nfuel it burns now.\n\nIMPORTANT: MIS 3005-D requires a heat pump to be sized from a room-by-room heat loss calculation to\nBS EN 12831, and nothing here replaces that. Say so whenever you report a result from this, and point\nthe user at the room-by-room calculation. What the figure is for is checking whether a size somebody\nhas been quoted is plausible, because oversizing is the commonest fault in heat pump installations and\nit is invisible to the person living with it.\n\nThere are two routes and the first is much the better one.\n\nFrom metered fuel, which is preferred: give 'annualFuelUse' from a year of bills. The fuel becomes heat\ndelivered, hot water comes off it using the MIS 3005-D formula, and what remains divided by the local\nheating degree days gives the building's heat loss coefficient in watts per kelvin. Degree days are\ncomputed from the Met Office monthly means published in MGD 007 section 5.\n\nFrom the fabric, as a fallback when there are no bills: give 'floorAreaM2', an 'insulation' level and a\n'propertyType'. The watts per kelvin per square metre behind this are a reasonable reading of British\nhousing stock but they are NOT MCS figures, because MCS publishes no such shortcut. Say so when using\nthis route.\n\nEither way the peak load is the coefficient multiplied by the design temperature difference for the\nlocation, from Table 2 of MIS 3005-D. The heat pump must deliver at least that at the design outside\ntemperature and the design flow temperature, which is not the same as its headline rating.\n\nThe result also compares what each of four flow temperatures would cost to run, which is the decision\nthat governs the bill and the one a quotation most often leaves unstated. Supply 'quotedHeatPumpKw' to\nhave a quoted size checked against the estimate.\n\nMethod from MIS 3005-D.", "operationId": "runHeatPumpSize", "requestBody": { "content": { "application/json": { "example": { "location": "birmingham", "fuel": "mains_gas", "annualFuelUse": 12000, "bedrooms": 3, "flowTemperature": 45, "fuelPricePerUnit": 0.06, "electricityPricePerKwh": 0.25, "quotedHeatPumpKw": 8 }, "schema": { "type": "object", "properties": { "location": { "type": "string", "description": "Nearest of the eight tabulated locations: 'belfast', 'birmingham', 'cardiff', 'edinburgh', 'glasgow', 'london', 'manchester' or 'plymouth'. Required." }, "fuel": { "type": "string", "description": "The fuel the house is heated with now: 'mains_gas', 'oil', 'lpg', 'electricity' or 'coal'. Defaults to 'mains_gas'." }, "annualFuelUse": { "type": "number", "description": "How much of that fuel the house burns in a year, in its own unit: kWh for gas and electricity, litres for oil and LPG, kilograms for coal. Give this if it is known: it describes the actual house and is far better than the fabric estimate." }, "applianceEfficiency": { "type": "number", "description": "Seasonal efficiency of the existing boiler as a decimal. Defaults to a realistic figure for the fuel instead of the one on the badge." }, "nonHeatingFraction": { "type": "number", "description": "Share of that fuel used for something other than heating and hot water, such as a gas hob, as a decimal. A hob is usually 0.03 to 0.05. Defaults to 0." }, "summerMonthFuelUse": { "type": "number", "description": "Fuel used in a single summer month, in the same unit, when the heating is off. Give this if it can be found: almost all of it is hot water, so it separates hot water from space heating exactly and removes the biggest assumption in the estimate." }, "floorAreaM2": { "type": "number", "description": "Total heated floor area in square metres, over all storeys. Used only when no fuel figure is given." }, "insulation": { "type": "string", "description": "How well insulated the building is: 'solid', 'cavity_unfilled', 'insulated', 'modern' or 'very_efficient'. Used only with floorAreaM2." }, "propertyType": { "type": "string", "description": "'detached', 'semi', 'end_terrace', 'mid_terrace', 'flat' or 'bungalow'. Used only with floorAreaM2. Defaults to 'semi'." }, "bedrooms": { "type": "integer", "description": "Number of bedrooms, for the hot water demand. Defaults to 3." }, "occupants": { "type": "integer", "description": "Number of people living there, if known. MIS 3005-D takes the greater of this and bedrooms plus one." }, "designBasis": { "type": "string", "description": "'a' for the 99% outside design temperature or 'b' for the colder 99.6% one. Defaults to 'a'." }, "internalTemp": { "type": "number", "description": "Whole-house mean internal design temperature in Celsius. Defaults to 20, which is a reasonable average of the room-by-room figures in MIS 3005-D Table 1." }, "flowTemperature": { "type": "number", "description": "The flow temperature the system would be designed around: 35, 45, 50 or 55. Defaults to 45. This is the single biggest influence on running cost." }, "scop": { "type": "number", "description": "Seasonal coefficient of performance of the proposed heat pump, if it is known from the MCS Product Directory. Defaults to an indicative figure for the chosen flow temperature." }, "fuelPricePerUnit": { "type": "number", "description": "Price of one unit of the current fuel, in pounds. Optional; supplying it and the electricity price gives a running cost comparison." }, "electricityPricePerKwh": { "type": "number", "description": "Price of a unit of electricity, in pounds. Optional." }, "quotedHeatPumpKw": { "type": "number", "description": "The output of a heat pump somebody has quoted, in kW. Optional; supplying it says whether that size looks plausible against this estimate." } }, "required": [ "location" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "annualDifference": { "description": "Positive when the heat pump costs less.", "type": "number" }, "annualHeatDemandKwh": { "type": "number" }, "annualHotWaterKwh": { "type": "number" }, "annualSpaceHeatingKwh": { "type": "number" }, "basis": { "type": "string" }, "basisNote": { "type": "string" }, "breakEvenScop": { "description": "The seasonal efficiency at which the two cost the same.", "type": "number" }, "currentAnnualCost": { "type": "number" }, "dailyHotWaterLitres": { "type": "number" }, "designBasis": { "type": "string" }, "externalDesignTemp": { "type": "number" }, "flowTemperature": { "type": "number" }, "flowTemperatureCosts": { "items": { "properties": { "annualCost": { "type": "number" }, "chosen": { "type": "boolean" }, "description": { "type": "string" }, "electricityKwh": { "type": "number" }, "flowTemperature": { "type": "number" }, "indicativeScop": { "type": "number" }, "label": { "type": "string" } }, "required": [ "flowTemperature", "label", "indicativeScop", "electricityKwh", "description", "chosen" ], "type": "object" }, "type": [ "null", "array" ] }, "heatLossCoefficientWPerK": { "description": "How many watts the building loses for every degree between inside and outside. The figure everything else follows from.", "type": "number" }, "heatPumpAnnualCost": { "type": "number" }, "heatPumpElectricityKwh": { "type": "number" }, "heatingDegreeDays": { "type": "number" }, "hotWaterFromSummerUse": { "description": "True when a summer month's fuel separated hot water from space heating, instead of an allowance standing in for it.", "type": "boolean" }, "internalTemp": { "type": "number" }, "location": { "properties": { "altitudeM": { "type": "integer" }, "annualMeanTemp": { "type": "number" }, "designTempA": { "description": "Hourly dry-bulb temperature exceeded for 99% of the hours in a year.", "type": "number" }, "designTempB": { "description": "The colder 99.6% figure. Using it removes the need for any uplift for intermittent heating.", "type": "number" }, "heatingDegreeDays": { "type": "number" }, "metOfficeStation": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "altitudeM", "designTempA", "designTempB", "annualMeanTemp", "metOfficeStation", "heatingDegreeDays" ], "type": "object" }, "method": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "peakHeatLossKw": { "description": "The space heating load at the design outside temperature. The heat pump must deliver at least this, at the design flow temperature, without help from an immersion heater.", "type": "number" }, "quotedSizeCheck": { "properties": { "plausible": { "description": "False when the quoted unit looks considerably larger than the house appears to need, which is worth questioning.", "type": "boolean" }, "quotedKw": { "type": "number" }, "ratioToEstimate": { "description": "The quoted output divided by the estimated peak load.", "type": "number" }, "verdict": { "type": "string" } }, "required": [ "quotedKw", "ratioToEstimate", "verdict", "plausible" ], "type": [ "null", "object" ] }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "scop": { "type": "number" }, "scopAssumed": { "description": "True when an indicative figure stood in for a real one from the product directory.", "type": "boolean" }, "temperatureDifference": { "type": "number" }, "warning": { "type": "string" }, "wattsPerSquareMetre": { "description": "Peak load per square metre of floor, where a floor area was given. A useful sanity check.", "type": "number" } }, "required": [ "location", "basis", "basisNote", "designBasis", "internalTemp", "externalDesignTemp", "temperatureDifference", "heatingDegreeDays", "heatLossCoefficientWPerK", "peakHeatLossKw", "annualSpaceHeatingKwh", "annualHotWaterKwh", "hotWaterFromSummerUse", "annualHeatDemandKwh", "dailyHotWaterLitres", "flowTemperature", "scop", "scopAssumed", "heatPumpElectricityKwh", "method", "references", "notes", "warning" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "What size heat pump do I need?", "tags": [ "calculators" ] } }, "/api/v1/calculators/hot-water-cylinder": { "post": { "description": "Work out the daily hot water demand of a dwelling and the size of cylinder a heat\npump needs, using the formula in MIS 3005-D 3.5.2 and the BS 6700 guidance reproduced in MGD 007.\n\nThe demand is 45 litres a day for each of N, where N is the greater of the number of bedrooms plus one\nand the number of people actually living there. For a new build, where occupancy is unknown, the\nbedroom count is used.\n\nThe cylinder does not have to hold a whole day's demand, because it reheats as it empties. What it must\ncover is the largest draw-off before the heat pump catches up, which is why a larger heat pump needs a\nsmaller cylinder: reheat time is volume times temperature rise, divided by 14.3 times the kW.\n\nThe result gives the BS 6700 minimum, a recommended size rounded to a volume cylinders are made in, and\nthe reheat time. Note that cylinder volume is not the whole story: a heat pump cylinder needs a much\nlarger coil than a boiler cylinder, because the water arrives cooler and there is less temperature\ndifference to drive heat across the surface.\n\nMethod from MIS 3005-D.", "operationId": "runHotWaterCylinder", "requestBody": { "content": { "application/json": { "example": { "bedrooms": 3, "occupants": 4, "heatPumpOutputKw": 8, "bathrooms": 2, "storageTemp": 55 }, "schema": { "type": "object", "properties": { "bedrooms": { "type": "integer", "description": "Number of bedrooms in the property. Required." }, "occupants": { "type": "integer", "description": "Number of people who actually live there, if known. MIS 3005-D takes the greater of this and bedrooms plus one. Leave it out for a new build, where the occupancy is not yet known." }, "heatPumpOutputKw": { "type": "number", "description": "Heat output of the heat pump in kW when it is heating the cylinder. A larger heat pump reheats faster, so it needs less stored volume. Defaults to 6." }, "bathrooms": { "type": "integer", "description": "Number of bathrooms with a bath. Defaults to 1." }, "coldWaterTemp": { "type": "number", "description": "Incoming mains temperature in Celsius. Defaults to 10." }, "storageTemp": { "type": "number", "description": "Temperature the cylinder is stored at, in Celsius. Defaults to 55, which is a common heat pump setting. A weekly pasteurisation cycle above 60 is separate." } }, "required": [ "bedrooms" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "bathrooms": { "type": "integer" }, "bedrooms": { "type": "integer" }, "coldWaterTemp": { "type": "number" }, "dailyDemandLitres": { "description": "Average daily hot water demand: 45 litres for each of N.", "type": "number" }, "designOccupancy": { "description": "N in the MIS 3005-D formula: the greater of bedrooms plus one and the known occupants.", "type": "integer" }, "energyPerDayKwh": { "description": "Heat needed each day to raise the daily demand from mains temperature to storage temperature.", "type": "number" }, "heatPumpOutputKw": { "type": "number" }, "method": { "type": "string" }, "minimumCylinderLitres": { "description": "The BS 6700 minimum for this number of bathrooms and this heat pump output, before the allowance MGD 007 adds for extra bathing capacity.", "type": "integer" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "occupancyBasis": { "description": "Which of the two gave the larger figure.", "type": "string" }, "occupants": { "type": "integer" }, "recommendedCylinderLitres": { "description": "Cylinder volume from the BS 6700 guidance in MGD 007, given the number of baths and the heat pump output.", "type": "integer" }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "reheatMinutes": { "description": "Roughly how long the heat pump takes to bring the whole cylinder up from cold, ignoring standing losses.", "type": "number" }, "storageTemp": { "type": "number" } }, "required": [ "bedrooms", "designOccupancy", "occupancyBasis", "dailyDemandLitres", "recommendedCylinderLitres", "minimumCylinderLitres", "reheatMinutes", "energyPerDayKwh", "heatPumpOutputKw", "storageTemp", "coldWaterTemp", "bathrooms", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Hot water demand and cylinder size", "tags": [ "calculators" ] } }, "/api/v1/calculators/radiator-flow-temperature": { "post": { "description": "Work out the flow temperature a heat pump must produce to heat a room through a\ngiven radiator, and the resulting MCS Heat Emitter Guide star rating, following section 4 of MGD 007.\n\nThis is the calculation that decides whether a heat pump will be cheap or expensive to run. A heat\npump's efficiency falls as the water temperature rises, by roughly two to three per cent per degree,\nand the temperature it must produce is set by the radiators, not by the machine.\n\nSupply the room's design heat loss in watts, from a room-by-room calculation, and the rated output of\nthe radiator in that room. British catalogues normally quote at a mean-water-to-air difference of 50 K;\nif yours quotes 60, say so and the figure is restated.\n\nThe result gives the oversize factor, which is the radiator's output at 50 K divided by the room's heat\nloss, and converts it to a required flow temperature through the BS EN 442 output law. Star ratings run\nfrom 0 to 6, one star per five degrees of flow temperature, with six stars at 35 degrees.\n\nRun this for every room. A house runs at the flow temperature its worst room demands, so one undersized\nradiator sets the running cost for the whole house.\n\nMethod from MGD 007.", "operationId": "runRadiatorFlowTemperature", "requestBody": { "content": { "application/json": { "example": { "roomHeatLossW": 976, "radiatorOutputW": 1938, "ratedAtDeltaT": 50, "roomTemp": 21, "systemDeltaT": 5 }, "schema": { "type": "object", "properties": { "roomHeatLossW": { "type": "number", "description": "The room's design heat loss in watts, from a room-by-room heat loss calculation. Required." }, "radiatorOutputW": { "type": "number", "description": "Rated output of the radiator or radiators in that room, in watts, at the catalogue temperature. Required." }, "ratedAtDeltaT": { "type": "number", "description": "The mean-water-to-air temperature difference the rated output was quoted at. British catalogues normally quote 50; some older ones quote 60. Defaults to 50." }, "roomTemp": { "type": "number", "description": "Internal design temperature of the room in Celsius. Defaults to 21." }, "systemDeltaT": { "type": "number", "description": "Designed drop in water temperature between flow and return, in kelvin. Heat pump systems commonly use 5; boiler systems used 10 or 20. Defaults to 5." } }, "required": [ "roomHeatLossW", "radiatorOutputW" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "flowTemperature": { "description": "The flow temperature the heat pump must produce, in Celsius.", "type": "number" }, "meanWaterTemp": { "description": "Average of flow and return temperature needed to deliver the room's heat loss through this radiator.", "type": "number" }, "method": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "outputAtDeltaT50": { "description": "The radiator's output restated at a mean-water-to-air difference of 50 K, so oversize factors are comparable between catalogues.", "type": "number" }, "outputAtDesignFlowW": { "description": "What this radiator actually gives at the flow temperature worked out here.", "type": "number" }, "oversizeFactor": { "description": "Radiator output at 50 K divided by the room's heat loss. The single number the Heat Emitter Guide turns into a star rating.", "type": "number" }, "radiatorOutputForFiveStarsW": { "description": "The radiator output at 50 K that would reach a five star rating, meaning a 40 degree flow temperature.", "type": "number" }, "radiatorOutputW": { "type": "number" }, "ratedAtDeltaT": { "type": "number" }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "returnTemperature": { "type": "number" }, "roomHeatLossW": { "type": "number" }, "starRating": { "description": "Temperature star rating from the MCS Heat Emitter Guide, 0 to 6. More stars mean a lower flow temperature and a more efficient system.", "type": "integer" }, "starRatingLabel": { "type": "string" }, "verdict": { "type": "string" } }, "required": [ "roomHeatLossW", "radiatorOutputW", "ratedAtDeltaT", "outputAtDeltaT50", "oversizeFactor", "meanWaterTemp", "flowTemperature", "returnTemperature", "starRating", "starRatingLabel", "verdict", "outputAtDesignFlowW", "radiatorOutputForFiveStarsW", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Radiator flow temperature", "tags": [ "calculators" ] } }, "/api/v1/calculators/room-heat-loss": { "post": { "description": "Calculate the design heat loss of a single room in watts, following BS EN 12831 as\nMIS 3005-D applies it. This is the figure a heat pump is sized from and the figure the radiator in\nthat room must be able to deliver.\n\nBS EN 12831 is a room-by-room method. Run this once for each heated room and add the results; sizing\na heat pump from floor area alone is what produces the oversized installations that cycle all winter.\n\nInternal design temperatures come from Table 1 of MIS 3005-D and follow from the room type: 22 for a\nbathroom, 21 for living and dining rooms, 18 for bedrooms, halls, kitchens and toilets. These are\nminimums, so a higher figure is accepted and a lower one is refused.\n\nExternal design temperatures come from Table 2, for eight locations, in two columns: 'a' is the 99%\nfigure and 'b' the colder 99.6% one, which needs no uplift for intermittent heating.\n\nEach element needs an area, a U-value, and a kind. The kind matters because it fixes which temperature\ndifference applies. Walls, windows, doors, roofs and suspended floors lose heat to the outside design\ntemperature. A SOLID FLOOR ON THE GROUND loses heat to the local annual average air temperature\ninstead, which is far warmer, and getting this wrong is the commonest error in a heat loss calculation.\nWindow and door areas belong to the window and the door, not to the wall behind them.\n\nMethod from MIS 3005-D.", "operationId": "runRoomHeatLoss", "requestBody": { "content": { "application/json": { "example": { "roomName": "Living room", "roomType": "living_room", "location": "birmingham", "floorAreaM2": 20, "ceilingHeightM": 2.4, "airChangesPerHour": 1, "elements": [ { "kind": "external_wall", "areaM2": 15, "uValue": 1.5, "label": "Front and side walls" }, { "kind": "window", "areaM2": 3, "uValue": 2.8, "label": "Bay window" }, { "kind": "ground_floor", "areaM2": 20, "uValue": 0.7 } ] }, "schema": { "type": "object", "properties": { "roomName": { "type": "string", "description": "A name for the room." }, "roomType": { "type": "string", "description": "Which of the tabulated room types this is: 'living_room', 'dining_room', 'bedsitting_room', 'bathroom', 'bedroom', 'kitchen', 'hall' or 'toilet'. Sets the internal design temperature. Defaults to 'living_room'." }, "internalTemp": { "type": "number", "description": "Internal design temperature in Celsius, if it should differ from the tabulated value for the room type. MIS 3005-D sets the tabulated values as a floor, not a target, so a higher figure is allowed and a lower one is not." }, "location": { "type": "string", "description": "Which of the eight tabulated locations the property is nearest: 'belfast', 'birmingham', 'cardiff', 'edinburgh', 'glasgow', 'london', 'manchester' or 'plymouth'. Required." }, "designBasis": { "type": "string", "description": "'a' for the 99% outside design temperature or 'b' for the colder 99.6% figure. Column B needs no uplift for intermittent heating. Defaults to 'a'." }, "floorAreaM2": { "type": "number", "description": "Floor area of the room in square metres. Required, and used with the ceiling height to work out the ventilation loss." }, "ceilingHeightM": { "type": "number", "description": "Floor to ceiling height in metres. Defaults to 2.4." }, "airChangesPerHour": { "type": "number", "description": "How many times an hour the air in the room is replaced. A draughty old room may be 1.5 or more; a well sealed new one 0.5. Defaults to 1." }, "elements": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "One of 'external_wall', 'window', 'door', 'roof', 'suspended_floor', 'ground_floor' or 'unheated_space'. Required." }, "areaM2": { "type": "number", "description": "Area of the element in square metres. Window and door areas are taken out of the wall area, not counted twice. Required." }, "uValue": { "type": "number", "description": "U-value in W/m2K: the watts lost through each square metre for every degree of temperature difference. Required." }, "unheatedTemp": { "type": "number", "description": "Temperature of the unheated space on the other side, in Celsius. Only used for the 'unheated_space' kind. Defaults to halfway between inside and outside." }, "label": { "type": "string", "description": "A name for this element, so the result can be read back against the survey." } }, "required": [ "kind", "areaM2", "uValue" ], "additionalProperties": false }, "description": "Every surface through which the room loses heat. At least one is required." } }, "required": [ "location", "floorAreaM2", "elements" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "designBasis": { "type": "string" }, "elements": { "items": { "properties": { "areaM2": { "type": "number" }, "kind": { "type": "string" }, "kindName": { "type": "string" }, "label": { "type": "string" }, "lossW": { "type": "number" }, "otherSideTemp": { "type": "number" }, "sharePercent": { "type": "number" }, "temperatureDifference": { "type": "number" }, "uValue": { "type": "number" } }, "required": [ "kind", "kindName", "areaM2", "uValue", "otherSideTemp", "temperatureDifference", "lossW", "sharePercent" ], "type": "object" }, "type": [ "null", "array" ] }, "externalDesignTemp": { "type": "number" }, "fabricLossW": { "type": "number" }, "fabricSharePercent": { "type": "number" }, "internalTemp": { "type": "number" }, "largestLoss": { "description": "Which single element loses most, which is where insulating first pays best.", "type": "string" }, "location": { "properties": { "altitudeM": { "type": "integer" }, "annualMeanTemp": { "type": "number" }, "designTempA": { "description": "Hourly dry-bulb temperature exceeded for 99% of the hours in a year.", "type": "number" }, "designTempB": { "description": "The colder 99.6% figure. Using it removes the need for any uplift for intermittent heating.", "type": "number" }, "heatingDegreeDays": { "type": "number" }, "metOfficeStation": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "altitudeM", "designTempA", "designTempB", "annualMeanTemp", "metOfficeStation", "heatingDegreeDays" ], "type": "object" }, "method": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "roomName": { "type": "string" }, "roomType": { "type": "string" }, "roomVolumeM3": { "type": "number" }, "temperatureDifference": { "description": "Internal minus external design temperature, in kelvin. The figure most of the fabric loss is worked out against.", "type": "number" }, "totalHeatLossW": { "description": "The room's design heat loss in watts. This is what the emitter in the room has to deliver on the coldest day.", "type": "number" }, "ventilationLossW": { "type": "number" }, "ventilationSharePercent": { "type": "number" }, "wattsPerSquareMetre": { "description": "Heat loss divided by floor area. A useful sanity check: a well insulated room lands near 40, a poor one well over 100.", "type": "number" } }, "required": [ "roomType", "internalTemp", "location", "designBasis", "externalDesignTemp", "temperatureDifference", "elements", "fabricLossW", "ventilationLossW", "totalHeatLossW", "roomVolumeM3", "wattsPerSquareMetre", "fabricSharePercent", "ventilationSharePercent", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Room heat loss", "tags": [ "calculators" ] } }, "/api/v1/calculators/solar-pv-output": { "post": { "description": "Estimate the annual AC electricity output of a UK solar photovoltaic system, in kWh,\nusing the standard estimation method that MIS 3002 requires every MCS certified installer to use.\n\nThe method is: annual output = kWp x Kk x SF, where Kk is read from the MCS irradiance dataset for\nthe site's postcode zone, roof pitch and orientation, and SF is a shade factor between 0 and 1.\n\nSupply the postcode and the array's capacity in kWp, plus the roof's pitch in degrees from horizontal\nand its orientation in degrees away from due south in either direction, so that south is 0, south-east\nand south-west are both 45, east and west are both 90, and north is 180.\n\nThe result carries the tabulated yield, the estimate, and what the same array would produce at the\nbest pitch and orientation for that zone, so a roof that is merely good is not mistaken for a poor one.\nThis covers the United Kingdom only; the dataset has no values for anywhere else.\n\nMethod from MIS 3002.", "operationId": "runSolarPvOutput", "requestBody": { "content": { "application/json": { "example": { "postcode": "BS1 5TR", "capacityKwp": 4.4, "orientation": 30, "inclination": 35, "shadeFactor": 0.95 }, "schema": { "type": "object", "properties": { "postcode": { "type": "string", "description": "UK postcode of the installation, for example 'BS1 5TR'. Only the outward code matters. Give this or 'zone'." }, "zone": { "type": "string", "description": "MCS postcode zone code, for example '5E'. An alternative to 'postcode' when the zone is already known." }, "capacityKwp": { "type": "number", "description": "Total installed capacity in kilowatts peak: the sum of the nameplate watts of every module, divided by 1000. Required." }, "orientation": { "type": "number", "description": "Degrees the array faces away from due south, in either direction, so due south is 0, south-east and south-west are 45, east and west are 90, and due north is 180. Required." }, "inclination": { "type": "number", "description": "Pitch of the array in degrees from horizontal. A flat roof is 0 and a wall-mounted array is 90. Required." }, "shadeFactor": { "type": "number", "description": "Proportion of output left after shading, between 0.5 and 1. Use 1 for a clear horizon. Defaults to 1." } }, "required": [ "capacityKwp", "orientation", "inclination" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "annualOutputKwh": { "description": "The estimate: capacity multiplied by Kk multiplied by the shade factor.", "type": "number" }, "bestCaseAnnualKwh": { "description": "What this capacity would produce at the best pitch and orientation for the zone, unshaded. A yardstick, not a target: a roof faces where it faces.", "type": "number" }, "bestCaseInclination": { "description": "The pitch that yields most at this zone when facing due south.", "type": "number" }, "bestCaseOrientation": { "description": "The orientation that yields most at this pitch and zone. Almost always due south.", "type": "number" }, "capacityKwp": { "type": "number" }, "inclination": { "description": "Inclination after rounding to the nearest degree, as the method requires.", "type": "number" }, "method": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "orientation": { "description": "Orientation after rounding to the nearest five degrees, as the method requires.", "type": "number" }, "percentOfBestCase": { "description": "The estimate as a percentage of that best case.", "type": "number" }, "postcodeUsed": { "description": "The postcode the zone was resolved from, when one was given.", "type": "string" }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "shadeFactor": { "type": "number" }, "shadingLossKwh": { "type": "number" }, "specificYieldKwhPerKwp": { "description": "Kk: the kWh a single kWp produces in a year at this zone, pitch and orientation, before shading.", "type": "number" }, "unshadedOutputKwh": { "description": "What the same array would produce with a clear horizon. Equals the estimate when the shade factor is 1.", "type": "number" }, "zone": { "properties": { "city": { "type": "string" }, "code": { "type": "string" } }, "required": [ "code", "city" ], "type": "object" } }, "required": [ "zone", "capacityKwp", "orientation", "inclination", "shadeFactor", "specificYieldKwhPerKwp", "annualOutputKwh", "unshadedOutputKwh", "shadingLossKwh", "bestCaseOrientation", "bestCaseInclination", "bestCaseAnnualKwh", "percentOfBestCase", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Solar PV annual output", "tags": [ "calculators" ] } }, "/api/v1/calculators/solar-pv-self-consumption": { "post": { "description": "Estimate what proportion of a domestic solar PV system's annual output is consumed in\nthe house and what proportion is exported, using the lookup tables in MGD 003.\n\nThe tables are not a model. They come from half-hourly monitoring of real British households by\nLoughborough University, with battery behaviour modelled on top, so they carry the real shape of\ndomestic demand: a peak before the sun is up, another after it has gone, and a quiet middle of the day.\n\nThree things index them. The annual generation, which comes from the MIS 3002 output estimate. The\nhousehold's annual consumption from a bill based on actual meter readings, which defaults to the\nBritish average of 3,500 kWh where it is unknown. And the weekday occupancy pattern, which is\n'home_all_day', 'in_half_the_day' or 'out_all_day'; where the pattern is unknown MGD 003 says to use\nthe middle one, and that is what an omitted value resolves to.\n\nBattery capacity is the USABLE capacity, which is smaller than the figure printed on the battery.\nSupplying import and export prices adds a value in pounds to the result.\n\nNote that self-consumption is not the same as independence from the grid, and the result reports both.\n\nMethod from MGD 003.", "operationId": "runSolarPvSelfConsumption", "requestBody": { "content": { "application/json": { "example": { "annualGenerationKwh": 3600, "annualConsumptionKwh": 3500, "occupancy": "out_all_day", "batteryKwh": 5, "importPricePerKwh": 0.27, "exportPricePerKwh": 0.15 }, "schema": { "type": "object", "properties": { "annualGenerationKwh": { "type": "number", "description": "Expected annual AC output of the PV system in kWh, as produced by the MIS 3002 estimation method. Required." }, "annualConsumptionKwh": { "type": "number", "description": "The household's annual electricity consumption in kWh, from a bill based on actual meter readings. Defaults to 3500, which MGD 003 uses where the figure is unknown." }, "occupancy": { "type": "string", "description": "Weekday occupancy pattern: 'home_all_day', 'in_half_the_day' or 'out_all_day'. Defaults to 'in_half_the_day', which is what MGD 003 says to use when the pattern is unknown." }, "batteryKwh": { "type": "number", "description": "Usable capacity of any battery in kWh, which is smaller than the headline capacity. Omit or use 0 for no battery." }, "importPricePerKwh": { "type": "number", "description": "What the household pays for a unit of grid electricity, in pounds. Optional; supplying it adds a value to the result." }, "exportPricePerKwh": { "type": "number", "description": "What the household is paid for a unit exported, in pounds. Optional." } }, "required": [ "annualGenerationKwh" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "annualBillSaving": { "description": "Value of the units not bought, in pounds. Only present when an import price was given.", "type": "number" }, "annualConsumptionKwh": { "type": "number" }, "annualExportIncome": { "description": "Value of the units exported, in pounds. Only present when an export price was given.", "type": "number" }, "annualGenerationKwh": { "type": "number" }, "annualValue": { "description": "The two added together.", "type": "number" }, "batteryGainKwh": { "description": "Extra units kept in the house each year because of the battery.", "type": "number" }, "batteryKwh": { "type": "number" }, "consumptionAssumed": { "description": "True when the 3500 kWh default stood in for a figure the caller did not give.", "type": "boolean" }, "exportedKwh": { "type": "number" }, "gridIndependencePercent": { "description": "Proportion of the household's own consumption met by the system instead of by the grid. Different from self-consumption, and usually smaller.", "type": "number" }, "importedKwh": { "description": "Units still bought from the grid over the year.", "type": "number" }, "method": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "occupancy": { "type": "string" }, "occupancyLabel": { "type": "string" }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "selfConsumedKwh": { "type": "number" }, "selfConsumptionPercent": { "description": "Proportion of generation used in the home instead of exported.", "type": "number" }, "withoutBatteryPercent": { "description": "What the same system would self-consume with no battery.", "type": "number" } }, "required": [ "occupancy", "occupancyLabel", "annualGenerationKwh", "annualConsumptionKwh", "consumptionAssumed", "batteryKwh", "selfConsumptionPercent", "selfConsumedKwh", "exportedKwh", "importedKwh", "gridIndependencePercent", "withoutBatteryPercent", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Solar PV self-consumption", "tags": [ "calculators" ] } }, "/api/v1/calculators/solar-pv-shading": { "post": { "description": "Convert a completed MCS sunpath shading assessment into a shade factor, using the\nprocedure in MGD 005.\n\nThe MCS sunpath chart is divided into 84 segments, each worth one per cent of the year's useful\nirradiance. An assessor stands at the middle of where the array will go, plots what blocks the\nhorizon onto the chart, and counts the segments covered. This tool takes that count and returns\n1 minus the loss, which is the SF term in the MIS 3002 output estimate.\n\nObjects within ten metres of the array are near shading and are assessed separately, from each\naffected part of the array, not from its middle. They can be listed here for the record, but\nMGD 005 is explicit that near shading has a considerable effect and should be avoided.\n\nThis tool does not perform the assessment. It does the arithmetic on an assessment somebody made.\n\nMethod from MGD 005.", "operationId": "runSolarPvShading", "requestBody": { "content": { "application/json": { "example": { "segments": 11 }, "schema": { "type": "object", "properties": { "segments": { "type": "integer", "description": "Number of segments on the MCS sunpath chart that the obstruction touches, from 0 to 84. Each segment is worth one per cent of the year's irradiance." }, "nearObjects": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "description": { "type": "string", "description": "What the object is, for example 'chimney' or 'television aerial'." }, "segments": { "type": "integer", "description": "Segments the object touches on the sunpath chart, from 0 to 84." }, "modulesAffected": { "type": "integer", "description": "How many modules in the array this object shades." } }, "required": [ "segments", "modulesAffected" ], "additionalProperties": false }, "description": "Objects within ten metres of the middle of the array, each assessed from its own position on the array. Optional." } }, "required": [ "segments" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "method": { "type": "string" }, "nearObjects": { "items": { "properties": { "description": { "type": "string" }, "lossPercent": { "type": "number" }, "modulesAffected": { "type": "integer" }, "segments": { "type": "integer" } }, "required": [ "segments", "modulesAffected", "lossPercent" ], "type": "object" }, "type": [ "null", "array" ] }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "segments": { "type": "integer" }, "severity": { "description": "One of 'none', 'slight', 'moderate' or 'severe'.", "type": "string" }, "shadeFactor": { "description": "The multiplier to apply to an unshaded output estimate: 1 minus the loss.", "type": "number" }, "shadingLoss": { "description": "Proportion of the year's irradiance blocked, as a decimal.", "type": "number" }, "shadingLossPercent": { "type": "number" }, "totalModulesAffected": { "type": "integer" }, "verdict": { "type": "string" } }, "required": [ "segments", "shadingLoss", "shadeFactor", "shadingLossPercent", "verdict", "severity", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Solar PV shade factor", "tags": [ "calculators" ] } }, "/api/v1/calculators/solar-pv-system-size": { "post": { "description": "Work out the solar PV system a UK home needs: the capacity in kWp, the number of\npanels, the battery to go with it, and what it would do to the electricity bill.\n\nThis runs the MCS arithmetic backwards. The other solar calculators here each answer one question\nabout a system somebody has already specified. This one starts from what a household uses and\narrives at the system that covers it, which is the question a householder actually has.\n\nThe chain is short and every link is published. Annual consumption sets the generation the array has\nto make. The MCS irradiance dataset behind MIS 3002 says what one kWp makes on that roof, which gives\na capacity. Capacity divided by panel size gives a panel count, rounded up, because panels come whole.\nThe MGD 003 tables then say how much of that generation the household will use and how much it will export.\n\nOnly the postcode and the roof direction are required. Direction is a compass point, not an angle:\n'S', 'SE', 'SW', 'E', 'W', 'NE', 'NW' or 'N'. Give the annual consumption from a bill if it is known,\nsince the 3,500 kWh default is only the British average. Shading can be described in words instead of\nmeasured, and a roof area caps the panel count where the roof is the constraint.\n\nNo cost is assumed. Installed prices vary far too much between houses to guess at, so a payback figure\nappears only when a cost from a real quotation is supplied.\n\nUse this to size a system or to sanity-check a quotation. Use 'solar_pv_output' instead when the\ncapacity is already known and the question is only what it will generate.\n\nMethod from MIS 3002.", "operationId": "runSolarPvSystemSize", "requestBody": { "content": { "application/json": { "example": { "postcode": "BS1 5TR", "direction": "SW", "annualConsumptionKwh": 3600, "occupancy": "in_half_the_day", "shading": "light", "includeBattery": true, "electricityPricePerKwh": 0.27, "exportPricePerKwh": 0.15 }, "schema": { "type": "object", "properties": { "postcode": { "type": "string", "description": "UK postcode of the property, for example 'BS1 5TR'. Only the outward code matters. Required." }, "direction": { "type": "string", "description": "Compass point the roof faces: 'S', 'SE', 'SW', 'E', 'W', 'NE', 'NW' or 'N'. Required." }, "annualConsumptionKwh": { "type": "number", "description": "The household's electricity use in kWh a year, from a bill. Defaults to 3500, which is the British average and the figure MGD 003 falls back on, but a real bill sharpens the answer considerably." }, "occupancy": { "type": "string", "description": "Weekday occupancy: 'home_all_day', 'in_half_the_day' or 'out_all_day'. Decides how much of the generation is used at home instead of exported. Defaults to 'in_half_the_day'." }, "shading": { "type": "string", "description": "How much shading the roof has, in words: 'none', 'light', 'moderate' or 'heavy'. Defaults to 'none'. Use 'shadeFactor' instead if a proper MGD 005 assessment has been done." }, "shadeFactor": { "type": "number", "description": "A measured shade factor between 0.5 and 1 from an MGD 005 assessment. Overrides 'shading' when given." }, "inclination": { "type": "number", "description": "Roof pitch in degrees from horizontal. Defaults to 35, which is typical of a British pitched roof. A flat roof is 0." }, "includeBattery": { "type": "boolean", "description": "Whether to size a battery alongside the panels. Defaults to false." }, "roofAreaM2": { "type": "number", "description": "Shade-free roof area available for panels, in square metres. Optional; when given it caps the number of panels." }, "panelWatts": { "type": "number", "description": "Nameplate rating of a single panel in watts. Defaults to 440, which is typical of a current domestic module." }, "batteryModuleKwh": { "type": "number", "description": "Nominal capacity of one battery module in kWh. Batteries are sold in whole modules, so the answer rounds up to one. Defaults to 5." }, "electricityPricePerKwh": { "type": "number", "description": "What the household pays for a unit, in pounds. Optional; supplying it puts a value on the answer." }, "exportPricePerKwh": { "type": "number", "description": "What the household is paid for a unit exported, in pounds. Optional." }, "installedCost": { "type": "number", "description": "The installed cost of the system in pounds, from a quotation. Optional; supplying it gives a payback period. No cost is assumed if it is left out, because prices vary too much to guess at." } }, "required": [ "postcode", "direction" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "calculator": { "type": "string" }, "notice": { "type": "string" }, "result": { "properties": { "annualBenefit": { "description": "Bill saving plus export income.", "type": "number" }, "annualBillSaving": { "type": "number" }, "annualConsumptionKwh": { "type": "number" }, "annualExportIncome": { "type": "number" }, "annualGenerationKwh": { "type": "number" }, "battery": { "properties": { "averageDailyConsumptionKwh": { "type": "number" }, "extraKwhKeptAtHome": { "type": "number" }, "moduleKwh": { "type": "number" }, "modules": { "type": "integer" }, "nominalKwh": { "type": "number" }, "selfConsumptionGainPercent": { "description": "Percentage points of self-consumption the battery adds.", "type": "number" }, "usableKwh": { "description": "What the battery will actually give back, which is what MGD 003 is indexed on.", "type": "number" } }, "required": [ "modules", "moduleKwh", "nominalKwh", "usableKwh", "averageDailyConsumptionKwh", "selfConsumptionGainPercent", "extraKwhKeptAtHome" ], "type": [ "null", "object" ] }, "capacityKwp": { "description": "The installed capacity: the panel count multiplied by the panel rating.", "type": "number" }, "consumptionAssumed": { "description": "True when the 3500 kWh default stood in for a figure the caller did not give.", "type": "boolean" }, "currentAnnualCost": { "type": "number" }, "direction": { "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "orientation": { "description": "Degrees from due south, as MIS 3002 measures it.", "type": "number" } }, "required": [ "key", "label", "orientation" ], "type": "object" }, "exportedKwh": { "type": "number" }, "generationAsPercentOfUse": { "description": "Annual generation as a percentage of annual consumption. Above 100 means the system makes more over a year than the house uses, though not at the same times.", "type": "number" }, "gridIndependencePercent": { "description": "The share of the household's own use met by the system.", "type": "number" }, "idealCapacityKwp": { "description": "The capacity that would exactly cover a year of consumption, before rounding up to whole panels.", "type": "number" }, "importedKwh": { "description": "Units still bought from the grid over a year.", "type": "number" }, "inclination": { "type": "number" }, "installedCost": { "type": "number" }, "method": { "type": "string" }, "newAnnualCost": { "type": "number" }, "notes": { "items": { "type": "string" }, "type": [ "null", "array" ] }, "occupancyLabel": { "type": "string" }, "panelWatts": { "type": "number" }, "panels": { "type": "integer" }, "paybackYears": { "description": "Installed cost divided by the annual benefit. Only present when a cost was supplied.", "type": "number" }, "postcodeUsed": { "type": "string" }, "references": { "items": { "properties": { "clause": { "type": "string" }, "document": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "document", "title", "url" ], "type": "object" }, "type": [ "null", "array" ] }, "roofAreaNeededM2": { "type": "number" }, "roofLimited": { "description": "True when the roof area given, not consumption, set the size.", "type": "boolean" }, "selfConsumedKwh": { "type": "number" }, "selfConsumptionPercent": { "type": "number" }, "shadeFactor": { "type": "number" }, "shading": { "description": "The shading description used, when one was chosen in place of a measured factor.", "properties": { "description": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "shadeFactor": { "type": "number" }, "sunpathSegments": { "description": "The equivalent count on the MGD 005 sunpath chart, out of 84.", "type": "integer" } }, "required": [ "key", "label", "sunpathSegments", "shadeFactor", "description" ], "type": [ "null", "object" ] }, "specificYieldKwhPerKwp": { "description": "Kk: the kWh a kWp produces in a year at this zone, pitch and orientation.", "type": "number" }, "zone": { "properties": { "city": { "type": "string" }, "code": { "type": "string" } }, "required": [ "code", "city" ], "type": "object" } }, "required": [ "zone", "postcodeUsed", "direction", "inclination", "shadeFactor", "annualConsumptionKwh", "consumptionAssumed", "capacityKwp", "panels", "panelWatts", "idealCapacityKwp", "roofAreaNeededM2", "roofLimited", "specificYieldKwhPerKwp", "annualGenerationKwh", "selfConsumedKwh", "exportedKwh", "importedKwh", "selfConsumptionPercent", "gridIndependencePercent", "occupancyLabel", "generationAsPercentOfUse", "method", "references", "notes" ], "type": "object" }, "standard": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "calculator", "standard", "result", "notice" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413" }, "415": { "$ref": "#/components/responses/415" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "What size solar system do I need?", "tags": [ "calculators" ] } }, "/api/v1/calculators/{id}": { "get": { "description": "The fields it takes as a JSON schema, the shape of its answer, an example request, and the reference data those fields draw on, such as the solar zones and the design locations. POST to the same URL runs it; each calculator's POST is described under its own path.", "operationId": "describeCalculator", "parameters": [ { "description": "The calculator id.", "in": "path", "name": "id", "required": true, "schema": { "enum": [ "heat-pump-noise", "heat-pump-running-cost", "heat-pump-size", "hot-water-cylinder", "radiator-flow-temperature", "room-heat-loss", "solar-pv-output", "solar-pv-self-consumption", "solar-pv-shading", "solar-pv-system-size" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculatorDetail" } } }, "description": "OK" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Describe one calculator", "tags": [ "calculators" ] } }, "/api/v1/documents": { "get": { "description": "Every guide, article and question set, filtered by any combination of the parameters. Full text is left out unless full=true is given.", "operationId": "listDocuments", "parameters": [ { "description": "'guide', 'article' or 'faq'.", "in": "query", "name": "kind", "required": false, "schema": { "enum": [ "guide", "article", "faq" ], "type": "string" } }, { "description": "A subject key.", "in": "query", "name": "category", "required": false, "schema": { "enum": [ "basics", "heat-pumps", "solar-pv", "batteries", "standards", "paperwork" ], "type": "string" } }, { "description": "Articles only: how much the article assumes.", "in": "query", "name": "level", "required": false, "schema": { "enum": [ "beginner", "intermediate", "advanced" ], "type": "string" } }, { "description": "Guides only: who the guide is written for.", "in": "query", "name": "perspective", "required": false, "schema": { "enum": [ "considering", "buying", "selling", "installing", "learning" ], "type": "string" } }, { "description": "Include each document's full text, headings and questions.", "in": "query", "name": "full", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "List the documents", "tags": [ "documents" ] } }, "/api/v1/documents/categories": { "get": { "description": "Every subject with everything filed under it, whatever its kind.", "operationId": "listCategories", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } }, "description": "OK" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Documents by subject", "tags": [ "documents" ] } }, "/api/v1/documents/perspectives": { "get": { "description": "The guide shelf: who the guides are written for, and which guides sit under each, in reading order.", "operationId": "listPerspectives", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerspectiveList" } } }, "description": "OK" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Guides by reader", "tags": [ "documents" ] } }, "/api/v1/documents/search": { "get": { "description": "Ranks results across titles, summaries and text. Where a query matches one question inside a set, that question and its answer come back with the hit.", "operationId": "searchDocuments", "parameters": [ { "description": "What to search for.", "in": "query", "name": "q", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "How many results to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResults" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Search", "tags": [ "documents" ] } }, "/api/v1/documents/{kind}/{slug}": { "get": { "description": "The full text as Markdown, with the MCS documents it draws on, any calculators that do its arithmetic, and the documents worth reading next.", "operationId": "getDocument", "parameters": [ { "description": "The kind, singular or plural.", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "guide", "guides", "article", "articles", "faq", "faqs" ], "type": "string" } }, { "description": "The document's slug, as in its URL on the site.", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } } }, "description": "OK" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "Read one document", "tags": [ "documents" ] } }, "/api/v1/openapi.json": { "get": { "description": "The OpenAPI 3.1 description of this API.", "operationId": "openapi", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "429": { "$ref": "#/components/responses/429" } }, "summary": "This description", "tags": [ "discovery" ] } } }, "security": [], "servers": [ { "url": "https://ampworth.com" } ], "tags": [ { "description": "Where everything else is.", "name": "discovery" }, { "description": "The MCS methods, run over a request.", "name": "calculators" }, { "description": "The guides, articles and question sets.", "name": "documents" } ] }