> ## Documentation Index > Fetch the complete documentation index at: https://docs.auth.energy/llms.txt > Use this file to discover all available pages before exploring further. # Get Capacity Heatmap Dataset > Returns a capacity heatmap dataset for a network operator's licence area. ## OpenAPI ````yaml /neso-dsi/api/capacity-heatmaps-openapi.yaml get /heatmap openapi: 3.1.0 info: title: LTDS Capacity Heatmaps API version: 1.0.0 description: > API specification for the Long Term Development Statement (LTDS) Capacity Heatmaps data model, as defined by Ofgem (April 2024). This describes the structure of capacity heatmap data published by GB Distribution Network Operators (DNOs). The data is structured as a hierarchy: - **HeatmapDataSet** at the root - **Substations** and **Circuits** nested within the dataset - Each Substation contains Demands, Generators, Storage, Transformers, Constraints, and Curtailments Network operators are required to publish data in JSON format at minimum. Alternative formats (e.g. GeoJSON) may also be produced. **Published by:** Ofgem **Standard:** LTDS Capacity Heatmaps Appendix 1: Information Model **Governance:** BSI GB CIM Engagement Hub (https://cim.bsigroup.com) servers: [] security: [] paths: /heatmap: get: summary: Get Capacity Heatmap Dataset description: >- Returns a capacity heatmap dataset for a network operator's licence area. operationId: getHeatmapDataset responses: '200': description: Successful response containing the heatmap dataset content: application/json: schema: $ref: '#/components/schemas/HeatmapDataSet' components: schemas: HeatmapDataSet: type: object description: > A single instance of a published capacity heatmap dataset. Metadata fields follow the Dublin Core standard (http://purl.org/dc/terms/). required: - contributor - coverage - creator - date - description - format - identifier - issued - language - publisher - rights - title - valid properties: contributor: type: string description: >- An entity responsible for making contributions to the resource. (http://purl.org/dc/terms/contributor) example: My Network Operator North, My Network Operator South coverage: type: string description: >- The spatial or temporal topic of the resource, or jurisdiction under which the resource is relevant. (http://purl.org/dc/terms/coverage) example: North of Scotland, South of England creator: type: string description: >- An entity responsible for making the resource. (http://purl.org/dc/terms/creator) example: My Network Operator date: type: string format: date-time description: Date the dataset is valid from. (http://purl.org/dc/terms/date) example: 2024-01-01T00:00:00.000+0000 description: type: string description: An account of the resource. (http://purl.org/dc/terms/description) example: A heatmaps dataset combined for north and south format: type: string description: The file format of the resource. (http://purl.org/dc/terms/format) example: application/json identifier: type: string description: >- An unambiguous reference to the resource within a given context. (http://purl.org/dc/terms/identifier) example: c91a4b42-4b21-476d-9c6f-5201a1324b2b issued: type: string format: date-time description: >- Date of formal issuance of the resource. (http://purl.org/dc/terms/issued) example: 2023-12-22T00:54:52.196+0000 language: type: string description: A language of the resource. (http://purl.org/dc/terms/language) example: en publisher: type: string description: >- An entity responsible for making the resource available. (http://purl.org/dc/terms/publisher) example: My Network Operator rights: type: string format: uri description: >- Information about rights held in and over the resource. (http://purl.org/dc/terms/rights) example: https://www.mynetworkoperators/link/to/license title: type: string description: A name given to the resource. (http://purl.org/dc/terms/title) example: North South Heatmap Data valid: type: array description: > A date range for the validity of the resource. Two ISO 8601 date-times: the first is inclusive (valid from), the second is exclusive (valid to). (http://purl.org/dc/terms/valid) minItems: 2 maxItems: 2 items: type: string format: date-time example: - 2024-01-01T00:00:00.000+0000 - 2024-04-01T00:00:00.000+0000 Substations: type: array description: A list of substations with heatmap data. items: $ref: '#/components/schemas/Substation' Circuits: type: array description: A list of circuits with heatmap data. items: $ref: '#/components/schemas/Circuit' Substation: type: object description: > A substation with connected demand, generation, or storage. Can be a Grid Supply Point (GSP), Bulk Supply Point (BSP), Primary, or Secondary station. required: - name - type - area - voltages - longitude - latitude - demandFirmCapacity - demandAvailableCapacity - demandConstraint - demandConstraintLimitingFactor - generationFirmCapacity - generationAvailableCapacity - generationConstraint - generationConstraintLimitingFactor - reversePowerFlowTotalCapacity - reversePowerFlowAvailableCapacity properties: mRID: type: string description: > Master Resource ID of the substation. Where CIM data is being produced for LTDS this should be present, persistent across releases, and match the mRID/rdf:ID of the CIM Substation. Optional if produced prior to CIM LTDS publication. example: 248ff818f157022515afc2b8e3c65894449ab903 name: type: string description: Human-readable name of the substation, consistent with LTDS naming. example: OSPREY type: $ref: '#/components/schemas/SubstationKind' area: type: string description: >- Name of the licence area (abbreviated, e.g. EPN for Eastern Power Networks). example: Southern England shortCode: type: string pattern: ^[A-Z0-9]+$ description: Short alphanumeric uppercase code for the substation. example: OSPE description: type: string description: Free text for additional descriptive data about the substation. voltages: type: array description: Voltages at the substation in kilovolts (kV). minItems: 1 items: type: number example: - 33 - 11 longitude: type: number description: Longitude of the substation in decimal degrees. example: -1.275823 latitude: type: number description: Latitude of the substation in decimal degrees. example: 51.749565 GSP: type: string description: >- Name or mRID of the GSP this substation is within. Not present for GSP-level substations. BSP: type: string description: >- Name or mRID of the BSP this substation is supplied by. Not present for GSP/BSP substations or Scottish networks (which have no BSPs). Primary: type: string description: >- Name or mRID of the Primary this substation is supplied by. Not present for GSP, BSP, or Primary substations. demandFirmCapacity: type: number description: Firm capacity for demand at the substation in MVA. example: 30 demandContractedCapacity: type: number description: >- Sum of all demand currently contracted but not yet connected (MVA). Must be >= sum of contracted demand/storage child elements. example: 0 demandConnectedCapacity: type: number description: >- Sum of all demand currently connected at the substation (MVA). Must be >= sum of connected demand/storage child elements. demandQuotedCapacity: type: number description: >- Sum of all demand currently quoted, excluding contracted and connected (MVA). example: 0 demandAvailableCapacity: type: number description: >- Available demand capacity at the substation (MVA), based on firm capacity, maximum demand, and constraints. example: 0.6 demandMaximum: type: number description: >- Maximum demand at the substation (MVA), normalised from historic measurements. Required for 33kV and above. example: 23.604368 demandMinimum: type: number description: >- Minimum demand at the substation (MVA), normalised from historic measurements. Required for 33kV and above. example: 5.986012 demand99Percentile: type: number description: 99th percentile of demand (MVA). Required for 33kV and above. demand75Percentile: type: number description: 75th percentile of demand (MVA). Required for 33kV and above. demand50Percentile: type: number description: 50th percentile of demand (MVA). Required for 33kV and above. demand25Percentile: type: number description: 25th percentile of demand (MVA). Required for 33kV and above. demandConstraint: $ref: '#/components/schemas/RAG' demandConstraintLimitingFactor: $ref: '#/components/schemas/LimitingFactorKind' generationFirmCapacity: type: number description: Total firm generation capacity of the substation (MVA). example: 1.504 generationConnectedCapacity: type: number description: Sum of all generation currently connected (MVA). generationContractedCapacity: type: number description: Sum of all generation contracted but not yet connected (MVA). example: 0.504 generationQuotedCapacity: type: number description: >- Sum of all currently quoted generation, excluding contracted and connected (MVA). example: 0 generationAvailableCapacity: type: number description: Available generation capacity at the substation (MVA). example: 0.2 generationConstraint: $ref: '#/components/schemas/RAG' generationConstraintLimitingFactor: $ref: '#/components/schemas/LimitingFactorKind' breakerRatedCurrent: type: number description: Rated normal current of the circuit breaker (kA RMS). breakerBreakingCapacity: type: number description: >- Short-circuit breaking current of the circuit breaker (kA RMS at contact separation). breakerMakingCapacity: type: number description: Peak making current of the circuit breaker on a short circuit (kA). breakerAvailableCapacity: type: number description: Available capacity of the circuit breaker (kA). breakerShortCircuitCurrent: type: number description: >- Short circuit current the breaker can carry in a fully closed condition (kA RMS). breakerShortCircuitDuration: type: number description: >- Duration in seconds that the short circuit current can be carried without damage. reversePowerFlowTotalCapacity: type: number description: >- Reverse power flow capacity from lower to higher voltage levels (MVA). 0 if no reverse flow capability. example: 0 reversePowerFlowAvailableCapacity: type: number description: Available reverse power flow capacity (MVA). example: 0 embeddedCapacityRegister: type: string format: uri description: URL to the embedded capacity register entry for this station. Demands: type: array description: >- Individual or aggregated demands at the station. Optional — may be aggregated into substation-level attributes. items: $ref: '#/components/schemas/Demand' Generators: type: array description: >- Individual or aggregated generators at the station. Optional — may be aggregated into substation-level attributes. items: $ref: '#/components/schemas/Generator' Storage: type: array description: >- Storage devices at the station. Optional — may be aggregated into substation-level attributes. items: $ref: '#/components/schemas/Storage' Transformers: type: array description: Transformers connected at the substation. items: $ref: '#/components/schemas/Transformer' OtherConstraints: type: array description: Additional constraints on the substation. items: $ref: '#/components/schemas/Constraint' Curtailments: type: array description: Curtailments at the substation. items: $ref: '#/components/schemas/Curtailment' Circuit: type: object description: > A circuit representing a connection between substations. Can be an HV circuit between stations or a circuit feeding multiple secondary stations from a primary. required: - mRID - name - voltage - demandConstraint - FromSubstation properties: mRID: type: string description: >- Master Resource ID of the circuit. Should match the mRID/rdf:ID of the CIM elements where CIM data is being produced. example: 109cb050-a158-4df7-bd8e-a1e8b0469346 name: type: string description: Human-readable name of the circuit. example: My Example Circuit description: type: string description: Free text for additional descriptive data about the circuit. voltage: type: number description: Voltage of the circuit in kilovolts (kV). example: 11 demandMaximum: type: number description: Maximum load on the circuit (MVA), from historic measurements. demandMinimum: type: number description: Minimum demand on the circuit (MVA), from historic measurements. demand99Percentile: type: number description: 99th percentile of demand on the circuit (MVA). demand75Percentile: type: number description: 75th percentile of demand on the circuit (MVA). demand50Percentile: type: number description: 50th percentile of demand on the circuit (MVA). demand25Percentile: type: number description: 25th percentile of demand on the circuit (MVA). demandConstraint: $ref: '#/components/schemas/RAG' demandAvailableCapacity: type: number description: Available demand capacity on the circuit (MVA). demandConnectedCapacity: type: number description: Sum of all demand currently connected on the circuit (MVA). demandContractedCapacity: type: number description: Sum of all demand currently contracted but not yet connected (MVA). demandQuotedCapacity: type: number description: >- Sum of all demand currently quoted, excluding contracted and connected (MVA). summerRating: type: number description: Summer rating for the minimum rated section in the circuit (MVA). winterRating: type: number description: Winter rating for the minimum rated section in the circuit (MVA). FromSubstation: type: string description: >- mRID (or name if no CIM mRID yet) of the substation the circuit originates from. example: b3d5cdd9e3033cf61ec1e5c783a4aedeed93ae55 ToSubstation: type: array description: >- mRIDs (or names) of the substations the circuit connects to. Optional for LV circuits with no LV/secondary substations. items: type: string OtherConstraints: type: array description: Additional constraints on the circuit. items: $ref: '#/components/schemas/Constraint' Geometry: $ref: '#/components/schemas/Geometry' SubstationKind: type: string description: The type/level of the substation in the distribution network hierarchy. enum: - GSP - BSP - Primary - Secondary example: Primary RAG: type: string description: > Red-Amber-Green status indicating the level of constraint at a substation or circuit. Network operators must document how this RAG status is calculated in accompanying documentation. enum: - Red - Amber - Green example: Amber LimitingFactorKind: type: string description: The physical factor limiting capacity at a substation or circuit. enum: - Thermal - Voltage - FaultLevel example: FaultLevel Demand: type: object description: > An individual or aggregated demand at a substation. May represent all demand at a voltage level, or a specific connected/contracted/quoted demand. required: - name - aggregate - demandConnectedCapacity - demandContractedCapacity - voltage properties: mRID: type: string description: >- Master Resource ID. Should match the mRID/rdf:ID of the CIM elements where available. name: type: string description: Human-readable name of the demand. example: New Demand Project aggregate: type: boolean description: >- True if this represents an aggregation of multiple demands at a single voltage level. example: false demandConnectedCapacity: type: number description: Currently connected demand capacity (MVA). example: 157.58 demandContractedCapacity: type: number description: Currently contracted demand capacity not yet connected (MVA). example: 0 demandQuotedCapacity: type: number description: >- Currently active quoted demand capacity, excluding contracted and connected (MVA). Optional. voltage: type: number description: Voltage the demand is connected at (kV). example: 132 technologyType: type: string description: Technology type of the connected demand. Generator: type: object description: > An individual or aggregated generator at a substation. May represent all generation at a voltage level, or a specific connected/contracted/quoted generator. required: - name - aggregate - generationConnectedCapacity - generationContractedCapacity - voltage properties: mRID: type: string description: >- Master Resource ID. Should match the mRID/rdf:ID of the CIM elements where available. name: type: string description: Human-readable name of the generator. example: New Generator Project aggregate: type: boolean description: > True if this represents an aggregation of multiple generators at a single voltage level. If technologyType is blank, aggregates all generation types. If technologyType is set, aggregates that specific technology type. example: false generationConnectedCapacity: type: number description: Currently connected generation capacity (MVA). example: 2.8 generationContractedCapacity: type: number description: Currently contracted generation capacity not yet connected (MVA). example: 0 generationQuotedCapacity: type: number description: >- Currently active quoted generation capacity, excluding contracted and connected (MVA). Optional. voltage: type: number description: Voltage the generator is connected at (kV). example: 11 technologyType: type: string description: >- Technology type of the connected generation (e.g. CHP, Wind, PV, Battery). example: Wind Storage: type: object description: | An individual or aggregated storage device at a substation. Storage contributes to both demand and generation capacities. required: - name - aggregate - demandConnectedCapacity - demandContractedCapacity - generationConnectedCapacity - generationContractedCapacity - voltage properties: mRID: type: string description: >- Master Resource ID. Should match the mRID/rdf:ID of the CIM elements where available. name: type: string description: Human-readable name of the storage device. example: New Storage Project aggregate: type: boolean description: > True if this represents an aggregation of multiple storage devices at a single voltage level. If technologyType is blank, aggregates all storage types. example: false demandConnectedCapacity: type: number description: Currently connected demand capacity (MVA). example: 21.3 demandContractedCapacity: type: number description: Currently contracted demand capacity not yet connected (MVA). example: 0 demandQuotedCapacity: type: number description: >- Currently active quoted demand capacity, excluding contracted and connected (MVA). Optional. generationConnectedCapacity: type: number description: Currently connected generation capacity (MVA). example: 1.8 generationContractedCapacity: type: number description: Currently contracted generation capacity not yet connected (MVA). example: 0 generationQuotedCapacity: type: number description: >- Currently active quoted generation capacity, excluding contracted and connected (MVA). Optional. voltage: type: number description: Voltage the storage device is connected at (kV). example: 11 technologyType: type: string description: Technology type (e.g. PumpStorage, Battery). example: Battery Transformer: type: object description: >- A transformer at a substation. Optional but useful for per-transformer ratings and capacity. required: - name - voltages properties: mRID: type: string description: >- Master Resource ID. Should match the mRID/rdf:ID of the CIM PowerTransformer where available. name: type: string description: Human-readable name of the transformer. example: Transformer voltages: type: array description: >- Primary, secondary, and optional tertiary voltages of the transformer (kV). minItems: 2 maxItems: 3 items: type: number example: - 33 - 11 Ratings: type: array description: Ratings of the transformer. items: $ref: '#/components/schemas/Rating' Constraint: type: object description: >- An additional non-numeric constraint on a Substation or Circuit (e.g. physical restrictions on reinforcement). required: - name - description - type properties: name: type: string description: Human-readable name of the constraint. example: Station Constraint description: type: string description: Free text description of the constraint. example: No room for upgrades type: $ref: '#/components/schemas/ConstraintKind' Curtailment: type: object description: >- A curtailment of demand or generation capacity at a substation, with optional temporal and seasonal parameters. required: - name - description - type - curtailedBy properties: name: type: string description: Human-readable name of the curtailment. example: Low load curtailment description: type: string description: Free text description of the curtailment. example: Reduced generation capacity in the afternoon type: $ref: '#/components/schemas/CurtailmentKind' curtailedBy: type: number description: Amount the demand/generation capacity is curtailed by (MVA). example: 50 technologyType: type: string description: >- Technology type the curtailment applies to (e.g. CHP, Wind, PV, Battery for generation). season: $ref: '#/components/schemas/Season' dayType: $ref: '#/components/schemas/DayKind' startTime: type: string format: time description: Start time of the curtailment (inclusive), in HH:MM format. example: '11:00' endTime: type: string format: time description: End time of the curtailment (exclusive), in HH:MM format. example: '16:00' Geometry: type: object description: >- The geometry of a circuit, expressed as one or more ordered line strings. Compatible with GeoJSON geometry format. required: - type - Lines properties: type: type: string description: The geometry type. enum: - LineString - MultiLineString example: LineString Lines: type: array description: One or more line elements. Multiple Lines support radial geometries. minItems: 1 items: $ref: '#/components/schemas/Line' Rating: type: object description: > A rating for a transformer. Multiple ratings can be defined per transformer (e.g. OFAF vs ONAN, or different directional ratings for reverse power flow). required: - name - summerRating - winterRating - fromVoltage - toVoltage properties: name: type: string description: Human-readable name of the rating. example: Operational summerRating: type: number description: Summer rating in MVA. example: 100 winterRating: type: number description: Winter rating in MVA. example: 120 fromVoltage: type: number description: From voltage for this rating (kV). example: 33 toVoltage: type: number description: To voltage for this rating (kV). example: 11 ConstraintKind: type: string description: The type of non-numeric constraint on a substation or circuit. enum: - Voltage - Physical - Other example: Physical CurtailmentKind: type: string description: Whether the curtailment applies to demand or generation. enum: - Demand - Generation example: Generation Season: type: string description: The season during which a curtailment applies. enum: - Spring - Summer - Autumn - Winter example: Summer DayKind: type: string description: The type of day during which a curtailment applies. enum: - Weekday - Weekend example: Weekday Line: type: object description: A series of ordered coordinates forming a line. required: - Coordinates properties: Coordinates: type: array description: Ordered list of coordinates forming the line. minItems: 2 items: $ref: '#/components/schemas/Coordinate' Coordinate: type: object description: A single latitude/longitude coordinate in decimal degrees. required: - latitude - longitude properties: latitude: type: number description: Latitude in decimal degrees. example: 56.397694 longitude: type: number description: Longitude in decimal degrees. example: -3.437605 ````