Rebase Energy Describe API

openapi: 3.2.0
info:
  title: Rebase Grid Describe API
  version: '1'
  description: 'REST API for European power system data: production, consumption, prices, exchanges, capacities

    and balancing, collected from TSOs, exchanges and transparency platforms. Every value is stored

    as the provider published it, with the time it became known and every later version.


    The guides at grid.rebase.energy/docs/v1/ explain entities, timeseries names, providers and

    reading values; this document is the endpoint contract. Before scripting calls, read

    grid.rebase.energy/docs/v1/guides/efficient-calls/: one timeseries per values call, 240

    requests per minute per key, at most 100,000 points per values request, and the paging rules.


    No API key is needed: every endpoint but `/me` answers a request without one, at 10 requests

    per minute per IP address (grid.rebase.energy/docs/v1/guides/open-access/). A free key raises

    the limit to 240 per minute.'
servers:
- url: https://grid.rebase.energy/api/v1
security:
- apiKey: []
- {}
tags:
- name: Describe
  description: What a timeseries measures, and the metadata of each provider that publishes it.
paths:
  /entities/{entity}/timeseries/{name}:
    get:
      tags:
      - Describe
      summary: Timeseries metadata
      parameters:
      - $ref: '#/components/parameters/entity'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeseriesMetadata'
              example:
                entity:
                  id: IT-NO
                  kind: price_zone
                  parent: Italy
                  country: Italy
                  sync_area: sync:CESA
                name: consumption.realised_load.total_load
                definition:
                  path: consumption.realised_load.total_load
                  measures: net generation − exports + imports − absorbed (stored) energy
                  document: A65
                  baseline: true
                  ref: https://eepublicdownloads.entsoe.eu/clean-documents/Transparency/MoP_Ref2_DDD_v3r4.pdf
                component: null
                unit: MW
                providers:
                - provider: entsoe
                  resolution: PT15M
                  extent:
                    first: '2026-09-03T14:00:00Z'
                    last: '2026-10-12T10:45:00Z'
                  publication_time: measured
                  latency_minutes:
                    p05: 48
                    p50: 63
                    p95: 108
                  coverage: 1
                  annotations_seen:
                    a03_forward_fill: 2
                  values: /entities/IT-NO/timeseries/consumption.realised_load.total_load/values?provider=entsoe
                - provider: terna
                  resolution: PT15M
                  extent:
                    first: '2026-09-30T22:00:00Z'
                    last: '2026-10-11T21:45:00Z'
                  publication_time: measured
                  latency_minutes:
                    p05: 1760
                    p50: 6170
                    p95: 10715
                  coverage: 0.99
                  annotations_seen: {}
                  values: /entities/IT-NO/timeseries/consumption.realised_load.total_load/values?provider=terna
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
      operationId: getEntitiesByEntityTimeseriesByName
      x-operation-id-source: derived
components:
  schemas:
    Licence:
      type: object
      description: The terms the publisher releases the data under (src/gridapi/licences.yaml). The data stays under these terms; follow them and show `attribution` when you republish it.
      required:
      - name
      - url
      - attribution
      properties:
        name:
          type: string
          description: The licence, e.g. `CC BY 4.0`; `unreviewed` when its terms are still being read.
        url:
          type:
          - string
          - 'null'
          description: The publisher's terms page.
        attribution:
          type:
          - string
          - 'null'
          description: The credit line the publisher asks for.
    TimeseriesMetadata:
      type: object
      required:
      - entity
      - name
      - definition
      - component
      - unit
      - data_type
      - columns
      - providers
      properties:
        entity:
          type: object
          properties:
            id:
              type: string
            kind:
              $ref: '#/components/schemas/Kind'
            parent:
              type:
              - string
              - 'null'
            country:
              type:
              - string
              - 'null'
            sync_area:
              type:
              - string
              - 'null'
        name:
          type: string
        definition:
          $ref: '#/components/schemas/Definition'
        component:
          oneOf:
          - $ref: '#/components/schemas/Component'
          - type: 'null'
        unit:
          type: string
        data_type:
          $ref: '#/components/schemas/DataType'
        columns:
          type: object
          description: 'Per provider, the columns of the series: `["value"]` for a plain series, `["p50", "p10", "p90"]` for a quantile family, one per fuel for a per-plant generation mix. A series with more than one column answers values as `points[].values` keyed by column.'
          additionalProperties:
            type: array
            items:
              type: string
            minItems: 1
        providers:
          type: array
          items:
            $ref: '#/components/schemas/ProviderMetadata'
          minItems: 1
    Kind:
      type: string
      enum:
      - sync_area
      - country
      - price_zone
      - area
      - aggregate
      - boundary
      - substation
      - plant
      - unit
      - portfolio
      - border
      - interconnector
    Definition:
      type: object
      required:
      - path
      - measures
      properties:
        path:
          type: string
        measures:
          type: string
        vs_baseline:
          type: string
        document:
          type:
          - string
          - 'null'
        baseline:
          type: boolean
        ref:
          type: string
    ProviderMetadata:
      type: object
      required:
      - provider
      - resolution
      - extent
      - publication_time
      - values
      properties:
        provider:
          type: string
        resolution:
          type:
          - string
          - 'null'
          description: ISO 8601 duration, null when the series has no fixed grid.
        resolution_history:
          type: array
          description: The grid changes over time, oldest first; from the platform series tag.
          items:
            type: object
            required:
            - valid_from
            - resolution
            properties:
              valid_from:
                type: string
                format: date-time
              resolution:
                type: string
        resolution_history_truncated:
          type: boolean
          description: True when the platform's 500-character tag cap dropped the oldest spans.
        extent:
          type:
          - object
          - 'null'
          description: Null when the platform reports no extent.
          properties:
            first:
              type: string
              format: date-time
            last:
              type: string
              format: date-time
        publication_time:
          type: string
          enum:
          - declared
          - measured
          description: declared = the provider states its publication time and we store it; measured = knowledge_time is when we observed the value appear.
        licence:
          oneOf:
          - $ref: '#/components/schemas/Licence'
          - type: 'null'
          description: The publisher's licence and the credit line to show when republishing; null when the licence register has no entry.
        latency_minutes:
          type:
          - object
          - 'null'
          properties:
            p05:
              type: integer
            p50:
              type: integer
            p95:
              type: integer
        coverage:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        annotations_seen:
          type: object
          additionalProperties:
            type: integer
        component:
          $ref: '#/components/schemas/Component'
          description: Only when the component's meaning is provider-specific (per_provider in components.yaml).
        inputs:
          type: array
          items:
            type: string
          description: Only for provider rebase (clean series).
        method:
          type: string
          description: Only for provider rebase.
        values:
          type: string
          description: Path of the values call for this provider.
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          enum:
          - not_found
          - bad_request
          - unauthorized
          - rate_limited
          - not_implemented
          - platform_unavailable
          - index_warming
        message:
          type: string
        param:
          type: string
          description: On bad_request, the offending parameter when there is one.
        anonymous:
          type: boolean
          description: On rate_limited, true when the request carried no API key.
        limit_rpm:
          type: integer
          description: On rate_limited without a key, the requests per minute an address may make.
        key_limit_rpm:
          type: integer
          description: On rate_limited without a key, the requests per minute a free key may make.
        retry_after_s:
          type: integer
          description: On rate_limited without a key, seconds to wait before repeating the request.
        sign_up:
          type: string
          description: Without a key, the form that requests a free one.
        docs:
          type: string
          description: Without a key, the documentation.
        info:
          type: string
          description: On rate_limited without a key, the Grid API product page.
        reason:
          type: string
          description: On not_found, `index_stale` when the series index may simply not have caught up with a new series.
        closest:
          type: array
          items:
            type: string
          description: On not_found, the three closest ids or names.
        providers:
          type: array
          items:
            type: string
          description: On bad_request for a missing/unknown provider, the providers available.
    Component:
      type: object
      required:
      - key
      - description
      properties:
        key:
          type: string
        description:
          type:
          - string
          - 'null'
        siblings:
          type: array
          items:
            type: string
          description: Other components of the same definition on this entity.
    DataType:
      type: string
      enum:
      - actual
      - forecast
      - capacity
      - price
      - schedule
      - other
      description: Derived from the category and sub-category of the name.
  responses:
    NotFound:
      description: Unknown entity, name or provider.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: The data platform did not answer (`platform_unavailable`) or the series index is still building (`index_warming`). Retry after the delay.
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: An API key that is not valid (`unauthorized`). A request with no key is served under the open limit; only `/me` answers it with this.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: 'The per-minute request limit is spent (`rate_limited`): 240 for a key, 5 for an address without one. Retry after the delay.'
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    name:
      name: name
      in: path
      required: true
      description: The quantity, `category.sub_category.definition[.component]`, never with the provider suffix.
      schema:
        type: string
        pattern: ^[a-z0-9_]+(\.[a-z0-9_]+){2,}$
    entity:
      name: entity
      in: path
      required: true
      description: 'The entity id, e.g. `SE-SE3`, `Sweden`, `sync:NSA`, `ca:DE-Amprion`, `bnd:GB-B1`, `sub:Blyth`, `border:FI~SE-SE3`, `icx:BritNed`, or a plant, unit or portfolio: `plant:11WD4SAEK2HS---S`, `unit:…`, `portfolio:…` — the key, or the name after the kind prefix (`plant:Säckingen hydroelectric plant`). A name shared by several records is 404 listing their ids. See the Entities guide for every kind.'
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Optional. The Grid API key, also accepted as `?api_key=`; without it a request is answered at 10 per minute per IP address. How to get a key: grid.rebase.energy/docs/v1/guides/authentication/. The key is in the API tab of the grid map.'