openapi: 3.1.0
info:
  title: Electricity Maps CarbonIntensity Zones API
  description: The Electricity Maps API delivers real-time, historical, and forecasted electricity grid signals worldwide, including carbon intensity, power breakdown by source, renewable and carbon-free percentages, electricity flows, total and net load, and day-ahead pricing. Each signal is available in three temporality variants (latest, past, forecast) and can be queried by zone identifier, geographic coordinates, or data center provider/region.
  version: '3.0'
  contact:
    name: Electricity Maps Support
    url: https://www.electricitymaps.com/contact
  license:
    name: Commercial
    url: https://www.electricitymaps.com/api-pricing
servers:
- url: https://api.electricitymap.org
  description: Production
security:
- authToken: []
- basicAuth: []
tags:
- name: Zones
  description: Discover available zones and locate them by coordinates or data center.
paths:
  /v3/zones:
    get:
      operationId: listZones
      summary: List available zones
      description: Returns the list of zones supported by the API. This endpoint does not require authentication.
      tags:
      - Zones
      security: []
      responses:
        '200':
          description: Map of zone identifiers to zone metadata
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Zone'
  /v3/zone:
    get:
      operationId: locateZone
      summary: Locate a zone by coordinates
      tags:
      - Zones
      parameters:
      - name: lon
        in: query
        required: true
        schema:
          type: number
      - name: lat
        in: query
        required: true
        schema:
          type: number
      responses:
        '200':
          description: Zone matched at the supplied coordinates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '404':
          description: No zone covers the supplied coordinates
  /v3/data-centers:
    get:
      operationId: listDataCenters
      summary: List available data centers
      tags:
      - Zones
      responses:
        '200':
          description: Data center list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataCenter'
components:
  schemas:
    DataCenter:
      type: object
      properties:
        provider:
          type: string
        region:
          type: string
        zone:
          type: string
    Zone:
      type: object
      properties:
        zoneName:
          type: string
        countryName:
          type: string
        access:
          type: array
          items:
            type: string
  securitySchemes:
    authToken:
      type: apiKey
      in: header
      name: auth-token
      description: API token issued from the Electricity Maps portal.
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  description: Electricity Maps API Documentation
  url: https://app.electricitymaps.com/docs/getting-started