openapi: 3.0.3
info:
  title: Carbon Intensity Factors Generation Mix 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
servers:
- url: https://api.carbonintensity.org.uk
  description: Production API server
tags:
- name: Generation Mix
  description: Electricity generation mix data (beta)
paths:
  /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'
components:
  schemas:
    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'
    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'
    ErrorResponse:
      type: object
      description: Error response wrapper
      properties:
        error:
          $ref: '#/components/schemas/Error'
    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/
  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
  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
externalDocs:
  description: Carbon Intensity API Documentation
  url: https://carbon-intensity.github.io/api-definitions/