openapi: 3.0.3
info:
  title: Carbon Intensity API
  description: >-
    The Carbon Intensity API is the official carbon intensity forecasting service
    for Great Britain, developed by the National Energy System Operator (NESO) in
    partnership with EDF, the University of Oxford, and WWF. It provides real-time,
    forecast, and historical carbon intensity data alongside generation mix
    information for GB electricity, with 96+ hour forecasts and 30-minute temporal
    resolution across 14 regional DNO boundaries. The API is publicly accessible
    with no authentication required and is licensed under CC BY 4.0.
  version: '2.0'
  contact:
    name: Carbon Intensity API Support
    url: https://carbonintensity.org.uk/
    email: lyndon.ruff@nationalgrideso.com
  license:
    name: Creative Commons Attribution 4.0 International (CC BY 4.0)
    url: https://creativecommons.org/licenses/by/4.0/
  termsOfService: https://github.com/carbon-intensity/terms
externalDocs:
  description: Carbon Intensity API Documentation
  url: https://carbon-intensity.github.io/api-definitions/
servers:
  - url: https://api.carbonintensity.org.uk
    description: Production API server
tags:
  - name: National Intensity
    description: National carbon intensity data for Great Britain
  - name: Statistics
    description: Carbon intensity statistics and aggregations
  - name: Factors
    description: Carbon intensity factors by fuel type
  - name: Generation Mix
    description: Electricity generation mix data (beta)
  - name: Regional
    description: Regional carbon intensity and generation mix data (beta)
paths:
  /intensity:
    get:
      summary: Get current national carbon intensity
      description: >-
        Returns current national carbon intensity for Great Britain.
        Returns data for the half-hour period that includes the current time.
      operationId: getCurrentIntensity
      tags:
        - National Intensity
      responses:
        '200':
          description: Successful response with current carbon intensity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
              example:
                data:
                  - from: '2018-01-20T12:00Z'
                    to: '2018-01-20T12:30Z'
                    intensity:
                      forecast: 266
                      actual: 263
                      index: moderate
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/date:
    get:
      summary: Get national carbon intensity for today
      description: >-
        Returns national carbon intensity data for all half-hour periods in the current date (today).
      operationId: getIntensityForToday
      tags:
        - National Intensity
      responses:
        '200':
          description: Successful response with today's carbon intensity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/date/{date}:
    get:
      summary: Get national carbon intensity for a specific date
      description: >-
        Returns national carbon intensity data for all half-hour periods on the specified date.
      operationId: getIntensityByDate
      tags:
        - National Intensity
      parameters:
        - name: date
          in: path
          required: true
          description: Date in YYYY-MM-DD format
          schema:
            type: string
            format: date
            example: '2018-01-20'
      responses:
        '200':
          description: Successful response with carbon intensity data for the specified date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/date/{date}/{period}:
    get:
      summary: Get national carbon intensity for a specific date and period
      description: >-
        Returns national carbon intensity data for a specific half-hour period on the specified date.
        Periods are numbered 1-48 representing 30-minute intervals from midnight.
      operationId: getIntensityByDateAndPeriod
      tags:
        - National Intensity
      parameters:
        - name: date
          in: path
          required: true
          description: Date in YYYY-MM-DD format
          schema:
            type: string
            format: date
            example: '2018-01-20'
        - name: period
          in: path
          required: true
          description: Half-hour period number (1-48)
          schema:
            type: integer
            minimum: 1
            maximum: 48
            example: 24
      responses:
        '200':
          description: Successful response with carbon intensity data for the specified date and period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/factors:
    get:
      summary: Get carbon intensity factors by fuel type
      description: >-
        Returns the carbon intensity factors (gCO2/kWh) for each fuel type used in generation mix calculations.
      operationId: getIntensityFactors
      tags:
        - Factors
      responses:
        '200':
          description: Successful response with carbon intensity factors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactorsResponse'
              example:
                data:
                  - Biomass: 120
                    Coal: 937
                    'Dutch Imports': 474
                    'French Imports': 53
                    'Gas (Combined Cycle)': 394
                    'Gas (Open Cycle)': 651
                    Hydro: 0
                    'Irish Imports': 458
                    Nuclear: 0
                    Oil: 935
                    Other: 300
                    'Pumped Storage': 0
                    Solar: 0
                    Wind: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/{from}:
    get:
      summary: Get national carbon intensity from a specific datetime
      description: >-
        Returns national carbon intensity data for the half-hour period that includes the specified datetime.
      operationId: getIntensityFrom
      tags:
        - National Intensity
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
      responses:
        '200':
          description: Successful response with carbon intensity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/{from}/fw24h:
    get:
      summary: Get 24-hour forward forecast from a specific datetime
      description: >-
        Returns national carbon intensity forecast data for the 24 hours following the specified datetime,
        with 30-minute resolution.
      operationId: getIntensityForward24h
      tags:
        - National Intensity
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
      responses:
        '200':
          description: Successful response with 24-hour forward forecast data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/{from}/fw48h:
    get:
      summary: Get 48-hour forward forecast from a specific datetime
      description: >-
        Returns national carbon intensity forecast data for the 48 hours following the specified datetime,
        with 30-minute resolution.
      operationId: getIntensityForward48h
      tags:
        - National Intensity
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
      responses:
        '200':
          description: Successful response with 48-hour forward forecast data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/{from}/pt24h:
    get:
      summary: Get 24-hour historical data ending at a specific datetime
      description: >-
        Returns national carbon intensity data for the 24 hours preceding the specified datetime,
        with 30-minute resolution.
      operationId: getIntensityPast24h
      tags:
        - National Intensity
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
      responses:
        '200':
          description: Successful response with 24-hour historical data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/{from}/{to}:
    get:
      summary: Get national carbon intensity for a date/time range
      description: >-
        Returns national carbon intensity data for all half-hour periods between the specified
        from and to datetimes. Maximum range is 14 days.
      operationId: getIntensityRange
      tags:
        - National Intensity
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - $ref: '#/components/parameters/ToDatetime'
      responses:
        '200':
          description: Successful response with carbon intensity data for the specified range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/stats/{from}/{to}:
    get:
      summary: Get carbon intensity statistics for a date/time range
      description: >-
        Returns aggregated carbon intensity statistics (min, max, average) for the specified
        date/time range.
      operationId: getIntensityStats
      tags:
        - Statistics
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - $ref: '#/components/parameters/ToDatetime'
      responses:
        '200':
          description: Successful response with carbon intensity statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityStatsResponse'
              example:
                data:
                  - from: '2018-01-20T12:00Z'
                    to: '2018-01-20T12:30Z'
                    intensity:
                      max: 320
                      average: 266
                      min: 180
                      index: moderate
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intensity/stats/{from}/{to}/{block}:
    get:
      summary: Get blocked carbon intensity statistics for a date/time range
      description: >-
        Returns aggregated carbon intensity statistics (min, max, average) for the specified
        date/time range, grouped into blocks of the specified number of hours.
      operationId: getIntensityStatsBlocked
      tags:
        - Statistics
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - $ref: '#/components/parameters/ToDatetime'
        - name: block
          in: path
          required: true
          description: Block size in hours (1-24)
          schema:
            type: integer
            minimum: 1
            maximum: 24
            example: 2
      responses:
        '200':
          description: Successful response with blocked carbon intensity statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntensityStatsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /generation:
    get:
      summary: Get current national generation mix
      description: >-
        Returns the current national electricity generation mix showing the percentage contribution
        of each fuel type. This is a beta endpoint.
      operationId: getCurrentGeneration
      tags:
        - Generation Mix
      responses:
        '200':
          description: Successful response with current generation mix
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationResponse'
              example:
                data:
                  - from: '2018-01-20T12:00Z'
                    to: '2018-01-20T12:30Z'
                    generationmix:
                      - fuel: gas
                        perc: 43.6
                      - fuel: coal
                        perc: 0.7
                      - fuel: biomass
                        perc: 4.2
                      - fuel: nuclear
                        perc: 17.6
                      - fuel: hydro
                        perc: 1.1
                      - fuel: imports
                        perc: 6.5
                      - fuel: other
                        perc: 0.3
                      - fuel: wind
                        perc: 6.8
                      - fuel: solar
                        perc: 18.1
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /generation/{from}/{to}:
    get:
      summary: Get national generation mix for a date/time range
      description: >-
        Returns national electricity generation mix data for all half-hour periods between
        the specified from and to datetimes. This is a beta endpoint.
      operationId: getGenerationRange
      tags:
        - Generation Mix
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - $ref: '#/components/parameters/ToDatetime'
      responses:
        '200':
          description: Successful response with generation mix data for the specified range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional:
    get:
      summary: Get current carbon intensity for all regions
      description: >-
        Returns current carbon intensity and generation mix for all 14 regional DNO boundaries
        in Great Britain. This is a beta endpoint.
      operationId: getAllRegionsIntensity
      tags:
        - Regional
      responses:
        '200':
          description: Successful response with regional carbon intensity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionalResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/england:
    get:
      summary: Get current carbon intensity for England
      description: >-
        Returns current carbon intensity and generation mix for England.
        This is a beta endpoint.
      operationId: getEnglandIntensity
      tags:
        - Regional
      responses:
        '200':
          description: Successful response with England carbon intensity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionalResponse'
              example:
                data:
                  - from: '2018-01-20T12:00Z'
                    to: '2018-01-20T12:30Z'
                    regions:
                      - regionid: 15
                        dnoregion: England
                        shortname: England
                        intensity:
                          forecast: 266
                          index: moderate
                        generationmix:
                          - fuel: gas
                            perc: 43.6
                          - fuel: coal
                            perc: 0.7
                          - fuel: wind
                            perc: 6.8
                          - fuel: solar
                            perc: 18.1
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/scotland:
    get:
      summary: Get current carbon intensity for Scotland
      description: >-
        Returns current carbon intensity and generation mix for Scotland.
        This is a beta endpoint.
      operationId: getScotlandIntensity
      tags:
        - Regional
      responses:
        '200':
          description: Successful response with Scotland carbon intensity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionalResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/wales:
    get:
      summary: Get current carbon intensity for Wales
      description: >-
        Returns current carbon intensity and generation mix for Wales.
        This is a beta endpoint.
      operationId: getWalesIntensity
      tags:
        - Regional
      responses:
        '200':
          description: Successful response with Wales carbon intensity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionalResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/postcode/{postcode}:
    get:
      summary: Get carbon intensity for a specific postcode
      description: >-
        Returns current carbon intensity and generation mix for the DNO region containing
        the specified postcode. This is a beta endpoint.
      operationId: getIntensityByPostcode
      tags:
        - Regional
      parameters:
        - name: postcode
          in: path
          required: true
          description: GB postcode (outward code only, e.g. RG10)
          schema:
            type: string
            example: RG10
      responses:
        '200':
          description: Successful response with regional carbon intensity data for the postcode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostcodeResponse'
              example:
                data:
                  - regionid: 3
                    dnoregion: Electricity North West
                    shortname: North West England
                    postcode: RG10
                    data:
                      - from: '2018-01-20T12:00Z'
                        to: '2018-01-20T12:30Z'
                        intensity:
                          forecast: 266
                          index: moderate
                        generationmix:
                          - fuel: gas
                            perc: 43.6
                          - fuel: wind
                            perc: 6.8
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/regionid/{regionid}:
    get:
      summary: Get carbon intensity for a specific region ID
      description: >-
        Returns current carbon intensity and generation mix for the specified DNO region.
        Region IDs range from 1-17, covering 14 DNO areas plus England (15), Scotland (16), and Wales (17).
        This is a beta endpoint.
      operationId: getIntensityByRegionId
      tags:
        - Regional
      parameters:
        - name: regionid
          in: path
          required: true
          description: DNO region ID (1-17)
          schema:
            type: integer
            minimum: 1
            maximum: 17
            example: 3
      responses:
        '200':
          description: Successful response with regional carbon intensity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionIdResponse'
              example:
                data:
                  - regionid: 3
                    dnoregion: Electricity North West
                    shortname: North West England
                    data:
                      - from: '2018-01-20T12:00Z'
                        to: '2018-01-20T12:30Z'
                        intensity:
                          forecast: 266
                          index: moderate
                        generationmix:
                          - fuel: gas
                            perc: 43.6
                          - fuel: wind
                            perc: 6.8
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/{from}/{to}:
    get:
      summary: Get regional carbon intensity for a date/time range
      description: >-
        Returns carbon intensity and generation mix for all regions across the specified
        date/time range. This is a beta endpoint.
      operationId: getRegionalIntensityRange
      tags:
        - Regional
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - $ref: '#/components/parameters/ToDatetime'
      responses:
        '200':
          description: Successful response with regional carbon intensity data for the range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionalResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/intensity/{from}/fw24h/postcode/{postcode}:
    get:
      summary: Get 24-hour forward regional intensity forecast by postcode
      description: >-
        Returns 24-hour forward carbon intensity forecast for the region containing the specified postcode.
        This is a beta endpoint.
      operationId: getRegionalForward24hByPostcode
      tags:
        - Regional
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - name: postcode
          in: path
          required: true
          description: GB postcode (outward code only)
          schema:
            type: string
            example: RG10
      responses:
        '200':
          description: Successful response with 24-hour regional forecast data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostcodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/intensity/{from}/fw24h/regionid/{regionid}:
    get:
      summary: Get 24-hour forward regional intensity forecast by region ID
      description: >-
        Returns 24-hour forward carbon intensity forecast for the specified region.
        This is a beta endpoint.
      operationId: getRegionalForward24hByRegionId
      tags:
        - Regional
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - name: regionid
          in: path
          required: true
          description: DNO region ID (1-17)
          schema:
            type: integer
            minimum: 1
            maximum: 17
            example: 3
      responses:
        '200':
          description: Successful response with 24-hour regional forecast data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionIdResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/intensity/{from}/fw48h/postcode/{postcode}:
    get:
      summary: Get 48-hour forward regional intensity forecast by postcode
      description: >-
        Returns 48-hour forward carbon intensity forecast for the region containing the specified postcode.
        This is a beta endpoint.
      operationId: getRegionalForward48hByPostcode
      tags:
        - Regional
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - name: postcode
          in: path
          required: true
          description: GB postcode (outward code only)
          schema:
            type: string
            example: RG10
      responses:
        '200':
          description: Successful response with 48-hour regional forecast data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostcodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/intensity/{from}/fw48h/regionid/{regionid}:
    get:
      summary: Get 48-hour forward regional intensity forecast by region ID
      description: >-
        Returns 48-hour forward carbon intensity forecast for the specified region.
        This is a beta endpoint.
      operationId: getRegionalForward48hByRegionId
      tags:
        - Regional
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - name: regionid
          in: path
          required: true
          description: DNO region ID (1-17)
          schema:
            type: integer
            minimum: 1
            maximum: 17
            example: 3
      responses:
        '200':
          description: Successful response with 48-hour regional forecast data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionIdResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/intensity/{from}/pt24h/postcode/{postcode}:
    get:
      summary: Get 24-hour historical regional intensity by postcode
      description: >-
        Returns 24-hour historical carbon intensity data for the region containing the specified postcode.
        This is a beta endpoint.
      operationId: getRegionalPast24hByPostcode
      tags:
        - Regional
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - name: postcode
          in: path
          required: true
          description: GB postcode (outward code only)
          schema:
            type: string
            example: RG10
      responses:
        '200':
          description: Successful response with 24-hour historical regional data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostcodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /regional/intensity/{from}/pt24h/regionid/{regionid}:
    get:
      summary: Get 24-hour historical regional intensity by region ID
      description: >-
        Returns 24-hour historical carbon intensity data for the specified region.
        This is a beta endpoint.
      operationId: getRegionalPast24hByRegionId
      tags:
        - Regional
      parameters:
        - $ref: '#/components/parameters/FromDatetime'
        - name: regionid
          in: path
          required: true
          description: DNO region ID (1-17)
          schema:
            type: integer
            minimum: 1
            maximum: 17
            example: 3
      responses:
        '200':
          description: Successful response with 24-hour historical regional data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionIdResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    FromDatetime:
      name: from
      in: path
      required: true
      description: >-
        Start datetime in ISO 8601 format (YYYY-MM-DDThh:mmZ).
        Example: 2018-01-20T12:00Z
      schema:
        type: string
        format: date-time
        example: '2018-01-20T12:00Z'
    ToDatetime:
      name: to
      in: path
      required: true
      description: >-
        End datetime in ISO 8601 format (YYYY-MM-DDThh:mmZ).
        Example: 2018-01-20T12:30Z
      schema:
        type: string
        format: date-time
        example: '2018-01-20T12:30Z'
  schemas:
    IntensityPeriod:
      type: object
      description: Carbon intensity data for a single half-hour period
      properties:
        from:
          type: string
          format: date-time
          description: Start of the half-hour period (ISO 8601)
          example: '2018-01-20T12:00Z'
        to:
          type: string
          format: date-time
          description: End of the half-hour period (ISO 8601)
          example: '2018-01-20T12:30Z'
        intensity:
          $ref: '#/components/schemas/Intensity'
    Intensity:
      type: object
      description: Carbon intensity measurements and forecast
      properties:
        forecast:
          type: integer
          description: Forecasted carbon intensity in gCO2/kWh
          example: 266
        actual:
          type: integer
          nullable: true
          description: Actual carbon intensity in gCO2/kWh (null for future periods)
          example: 263
        index:
          type: string
          description: Qualitative carbon intensity index
          enum:
            - very low
            - low
            - moderate
            - high
            - very high
          example: moderate
    IntensityStats:
      type: object
      description: Aggregated carbon intensity statistics
      properties:
        max:
          type: integer
          description: Maximum carbon intensity in gCO2/kWh
          example: 320
        average:
          type: integer
          description: Average carbon intensity in gCO2/kWh
          example: 266
        min:
          type: integer
          description: Minimum carbon intensity in gCO2/kWh
          example: 180
        index:
          type: string
          description: Qualitative carbon intensity index for the average
          enum:
            - very low
            - low
            - moderate
            - high
            - very high
          example: moderate
    IntensityStatsPeriod:
      type: object
      description: Carbon intensity statistics for a time period
      properties:
        from:
          type: string
          format: date-time
          description: Start of the period (ISO 8601)
          example: '2018-01-20T12:00Z'
        to:
          type: string
          format: date-time
          description: End of the period (ISO 8601)
          example: '2018-01-20T12:30Z'
        intensity:
          $ref: '#/components/schemas/IntensityStats'
    GenerationMixItem:
      type: object
      description: Generation percentage for a single fuel type
      properties:
        fuel:
          type: string
          description: Fuel type name
          enum:
            - biomass
            - coal
            - imports
            - gas
            - nuclear
            - other
            - hydro
            - solar
            - wind
          example: gas
        perc:
          type: number
          format: float
          description: Percentage of total generation from this fuel type
          minimum: 0
          maximum: 100
          example: 43.6
    GenerationPeriod:
      type: object
      description: Generation mix data for a single half-hour period
      properties:
        from:
          type: string
          format: date-time
          description: Start of the half-hour period (ISO 8601)
          example: '2018-01-20T12:00Z'
        to:
          type: string
          format: date-time
          description: End of the half-hour period (ISO 8601)
          example: '2018-01-20T12:30Z'
        generationmix:
          type: array
          description: List of fuel type generation percentages
          items:
            $ref: '#/components/schemas/GenerationMixItem'
    RegionalIntensity:
      type: object
      description: Regional carbon intensity data
      properties:
        forecast:
          type: integer
          description: Forecasted carbon intensity in gCO2/kWh for the region
          example: 266
        index:
          type: string
          description: Qualitative carbon intensity index
          enum:
            - very low
            - low
            - moderate
            - high
            - very high
          example: moderate
    Region:
      type: object
      description: Data for a single DNO region
      properties:
        regionid:
          type: integer
          description: DNO region identifier (1-17)
          example: 3
        dnoregion:
          type: string
          description: Full DNO region name
          example: Electricity North West
        shortname:
          type: string
          description: Short region name
          example: North West England
        intensity:
          $ref: '#/components/schemas/RegionalIntensity'
        generationmix:
          type: array
          description: Generation mix for this region
          items:
            $ref: '#/components/schemas/GenerationMixItem'
    RegionalPeriod:
      type: object
      description: Regional carbon intensity data for a time period
      properties:
        from:
          type: string
          format: date-time
          description: Start of the half-hour period (ISO 8601)
          example: '2018-01-20T12:00Z'
        to:
          type: string
          format: date-time
          description: End of the half-hour period (ISO 8601)
          example: '2018-01-20T12:30Z'
        regions:
          type: array
          description: List of regional intensity data
          items:
            $ref: '#/components/schemas/Region'
    RegionDataPeriod:
      type: object
      description: Carbon intensity and generation mix for a single time period within a region
      properties:
        from:
          type: string
          format: date-time
          description: Start of the half-hour period (ISO 8601)
          example: '2018-01-20T12:00Z'
        to:
          type: string
          format: date-time
          description: End of the half-hour period (ISO 8601)
          example: '2018-01-20T12:30Z'
        intensity:
          $ref: '#/components/schemas/RegionalIntensity'
        generationmix:
          type: array
          description: Generation mix for this period
          items:
            $ref: '#/components/schemas/GenerationMixItem'
    RegionById:
      type: object
      description: Data for a specific DNO region with time-series data
      properties:
        regionid:
          type: integer
          description: DNO region identifier (1-17)
          example: 3
        dnoregion:
          type: string
          description: Full DNO region name
          example: Electricity North West
        shortname:
          type: string
          description: Short region name
          example: North West England
        data:
          type: array
          description: Time-series intensity and generation mix data
          items:
            $ref: '#/components/schemas/RegionDataPeriod'
    RegionByPostcode:
      type: object
      description: Data for the DNO region containing the specified postcode
      properties:
        regionid:
          type: integer
          description: DNO region identifier (1-17)
          example: 3
        dnoregion:
          type: string
          description: Full DNO region name
          example: Electricity North West
        shortname:
          type: string
          description: Short region name
          example: North West England
        postcode:
          type: string
          description: Postcode queried
          example: RG10
        data:
          type: array
          description: Time-series intensity and generation mix data
          items:
            $ref: '#/components/schemas/RegionDataPeriod'
    CarbonIntensityFactors:
      type: object
      description: Carbon intensity factors by fuel type (gCO2/kWh)
      properties:
        Biomass:
          type: integer
          description: Carbon intensity factor for biomass generation (gCO2/kWh)
          example: 120
        Coal:
          type: integer
          description: Carbon intensity factor for coal generation (gCO2/kWh)
          example: 937
        'Dutch Imports':
          type: integer
          description: Carbon intensity factor for Dutch imports (gCO2/kWh)
          example: 474
        'French Imports':
          type: integer
          description: Carbon intensity factor for French imports (gCO2/kWh)
          example: 53
        'Gas (Combined Cycle)':
          type: integer
          description: Carbon intensity factor for gas (combined cycle) generation (gCO2/kWh)
          example: 394
        'Gas (Open Cycle)':
          type: integer
          description: Carbon intensity factor for gas (open cycle) generation (gCO2/kWh)
          example: 651
        Hydro:
          type: integer
          description: Carbon intensity factor for hydro generation (gCO2/kWh)
          example: 0
        'Irish Imports':
          type: integer
          description: Carbon intensity factor for Irish imports (gCO2/kWh)
          example: 458
        Nuclear:
          type: integer
          description: Carbon intensity factor for nuclear generation (gCO2/kWh)
          example: 0
        Oil:
          type: integer
          description: Carbon intensity factor for oil generation (gCO2/kWh)
          example: 935
        Other:
          type: integer
          description: Carbon intensity factor for other generation types (gCO2/kWh)
          example: 300
        'Pumped Storage':
          type: integer
          description: Carbon intensity factor for pumped storage (gCO2/kWh)
          example: 0
        Solar:
          type: integer
          description: Carbon intensity factor for solar generation (gCO2/kWh)
          example: 0
        Wind:
          type: integer
          description: Carbon intensity factor for wind generation (gCO2/kWh)
          example: 0
    Error:
      type: object
      description: Error response
      properties:
        code:
          type: string
          description: HTTP status code and description
          example: '400 Bad Request'
        message:
          type: string
          description: Human-readable error message
          example: 'Please enter a valid path e.g. /intensity/'
    IntensityResponse:
      type: object
      description: Response containing national carbon intensity data
      properties:
        data:
          type: array
          description: Array of carbon intensity periods
          items:
            $ref: '#/components/schemas/IntensityPeriod'
    IntensityStatsResponse:
      type: object
      description: Response containing aggregated carbon intensity statistics
      properties:
        data:
          type: array
          description: Array of carbon intensity statistics periods
          items:
            $ref: '#/components/schemas/IntensityStatsPeriod'
    GenerationResponse:
      type: object
      description: Response containing national generation mix data
      properties:
        data:
          type: array
          description: Array of generation mix periods
          items:
            $ref: '#/components/schemas/GenerationPeriod'
    FactorsResponse:
      type: object
      description: Response containing carbon intensity factors by fuel type
      properties:
        data:
          type: array
          description: Array containing the factors object
          items:
            $ref: '#/components/schemas/CarbonIntensityFactors'
    RegionalResponse:
      type: object
      description: Response containing regional carbon intensity data
      properties:
        data:
          type: array
          description: Array of regional carbon intensity periods
          items:
            $ref: '#/components/schemas/RegionalPeriod'
    RegionIdResponse:
      type: object
      description: Response containing data for a specific region
      properties:
        data:
          type: array
          description: Array containing the region data
          items:
            $ref: '#/components/schemas/RegionById'
    PostcodeResponse:
      type: object
      description: Response containing data for the region matching a postcode
      properties:
        data:
          type: array
          description: Array containing the postcode region data
          items:
            $ref: '#/components/schemas/RegionByPostcode'
    ErrorResponse:
      type: object
      description: Error response wrapper
      properties:
        error:
          $ref: '#/components/schemas/Error'
  responses:
    BadRequest:
      description: Bad request - invalid parameters or path
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: '400 Bad Request'
              message: 'Please enter a valid path e.g. /intensity/'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: '500 Internal Server Error'
              message: 'Internal Server Error'