openapi: 3.0.3
info:
  title: Carbon Intensity Factors 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: Factors
  description: Carbon intensity factors by fuel type
paths:
  /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'
components:
  schemas:
    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
    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'
    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/
  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/