Engrate Core API

openapi: 3.2.0
info:
  title: Engrate Core API
  version: 1.0.0
servers:
- url: https://api.engrate.io
security:
- apiKeyAuth: []
tags:
- name: Core
paths:
  /core/v1/bidding-zones:
    get:
      description: 'List & filter bidding zones.


        If you specify multiple values for some filter parameter they are OR-ed. If you specify multiple separate filters they are "AND"-ed.'
      operationId: list_bidding_zones_core_v1_bidding_zones_get
      parameters:
      - description: Filter by EIC code(s)
        in: query
        name: id
        required: false
        schema:
          default: []
          description: Filter by EIC code(s)
          items:
            type: string
          title: Id
          type: array
      - description: Filter by name or short name using substring matching
        in: query
        name: name
        required: false
        schema:
          default: []
          description: Filter by name or short name using substring matching
          items:
            type: string
          title: Name
          type: array
      - description: Filter by ISO 3166-1 alpha-2 country codes
        in: query
        name: country
        required: false
        schema:
          default: []
          description: Filter by ISO 3166-1 alpha-2 country codes
          examples:
          - SE
          items:
            type: string
          title: Country
          type: array
      responses:
        '200':
          content:
            application/json:
              example:
                bidding_zones:
                - countries:
                  - SE
                  id: 10Y1001A1001A46L
                  name: Swedish Elspot Area 3
                  short_name: SE3
              schema:
                $ref: '#/components/schemas/GetBiddingZonesResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Bidding Zones
      tags:
      - Core
  /core/v1/control-areas:
    get:
      description: 'List & filter control areas.


        If you specify multiple values for some filter parameter they are OR-ed. If you specify multiple separate filters they are "AND"-ed.'
      operationId: list_control_areas_core_v1_control_areas_get
      parameters:
      - description: Filter by EIC code(s)
        in: query
        name: id
        required: false
        schema:
          default: []
          description: Filter by EIC code(s)
          items:
            type: string
          title: Id
          type: array
      - description: Filter by name or short name using substring matching
        in: query
        name: name
        required: false
        schema:
          default: []
          description: Filter by name or short name using substring matching
          items:
            type: string
          title: Name
          type: array
      - description: Filter by ISO 3166-1 alpha-2 country codes
        in: query
        name: country
        required: false
        schema:
          default: []
          description: Filter by ISO 3166-1 alpha-2 country codes
          examples:
          - DE
          items:
            type: string
          title: Country
          type: array
      responses:
        '200':
          content:
            application/json:
              example:
                control_areas:
                - countries:
                  - DE
                  id: 10YDE-VE-------2
                  name: Germany 50Hertz
                  short_name: DE-50HERTZ
              schema:
                $ref: '#/components/schemas/GetControlAreasResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Control Areas
      tags:
      - Core
  /core/v1/metering-grid-areas:
    get:
      description: 'List & filter Metering Grid Areas.


        If you specify multiple values for some filter parameter they are OR-ed. If you specify multiple separate filters they are "AND"-ed.


        For instance if you specify country=SE&country=DK, you''ll get MGAs in Denmark and Sweden. If you specify country=DK&city=Stockholm you''ll get no results as no MGAs cover both Stockholm and Denmark.


        See Metering Grid Area for details on MeteringGridArea.'
      operationId: list_metering_grid_areas_core_v1_metering_grid_areas_get
      parameters:
      - description: Filter by Engrate metering grid area id(s)
        in: query
        name: id
        required: false
        schema:
          default: []
          description: Filter by Engrate metering grid area id(s)
          items:
            format: uuid
            type: string
          title: Id
          type: array
      - description: Substring filter by name(s) of the metering grid area
        in: query
        name: name
        required: false
        schema:
          default: []
          description: Substring filter by name(s) of the metering grid area
          items:
            type: string
          title: Name
          type: array
      - description: Filter by [Extra Identifier](/api-reference/core/models/extra-identifier)(s)
        in: query
        name: extra_id
        required: false
        schema:
          default: []
          description: Filter by [Extra Identifier](/api-reference/core/models/extra-identifier)(s)
          items:
            type: string
          title: Extra Id
          type: array
      - description: Filter MGAs operated by the specified [Party](/api-reference/core/models/party)(s)
        in: query
        name: system_operator_id
        required: false
        schema:
          default: []
          description: Filter MGAs operated by the specified [Party](/api-reference/core/models/party)(s)
          items:
            format: uuid
            type: string
          title: System Operator Id
          type: array
      - description: Filter MGAs operated by the specified [Party](/api-reference/core/models/party)(s), convenience filter to search by extra ids
        in: query
        name: system_operator_extra_id
        required: false
        schema:
          default: []
          description: Filter MGAs operated by the specified [Party](/api-reference/core/models/party)(s), convenience filter to search by extra ids
          items:
            type: string
          title: System Operator Extra Id
          type: array
      - description: Filter by country(s)
        in: query
        name: country
        required: false
        schema:
          default: []
          description: Filter by country(s)
          items:
            type: string
          title: Country
          type: array
      - description: Filter by latitude, requires you to also specify lon; finds MGAs that cover the given location
        in: query
        name: lat
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Filter by latitude, requires you to also specify lon; finds MGAs that cover the given location
          title: Lat
      - description: Filter by longitude, requires you to also specify lat; finds MGAs that cover the given location
        in: query
        name: lon
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Filter by longitude, requires you to also specify lat; finds MGAs that cover the given location
          title: Lon
      - description: Filter by street address, requires that you also specify country and city
        in: query
        name: street
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by street address, requires that you also specify country and city
          title: Street
      - description: Filter by city, requires you also specify street and country
        in: query
        name: city
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by city, requires you also specify street and country
          title: City
      - description: Filter by zip/postal code, requires you also specify country
        in: query
        name: zipcode
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by zip/postal code, requires you also specify country
          title: Zipcode
      responses:
        '200':
          content:
            application/json:
              example:
                mgas:
                - extra_ids:
                  - kind: eic
                    value: 46Y000000000016G
                  - kind: se.mga_code
                    value: STO
                  id: 0199c317-25ec-7c00-b1a0-a1b2c3d4e5f6
                  name: Stockholm
                  scheduling_area_eic: 10Y1001A1001A47J
                  system_operator:
                    extra_ids:
                    - kind: eic
                      value: 46X000000000245K
                    id: 0199c317-25ec-7cf7-94cc-32a39f068433
              schema:
                $ref: '#/components/schemas/GetMeteringGridAreasResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Metering Grid Areas
      tags:
      - Core
  /core/v1/parties:
    get:
      description: 'List & filter market parties.


        If you specify multiple values for some filter parameter they are OR-ed. If you specify multiple separate filters they are "AND"-ed.


        See Party for details on Parties.'
      operationId: list_parties_core_v1_parties_get
      parameters:
      - description: Filter by Engrate party id(s)
        in: query
        name: id
        required: false
        schema:
          default: []
          description: Filter by Engrate party id(s)
          items:
            format: uuid
            type: string
          title: Id
          type: array
      - description: Filter by [Extra Identifiers](/api-reference/core/models/extra-identifier) - EIC, Ediel, VAT, and similar market-specific identifiers
        in: query
        name: extra_id
        required: false
        schema:
          default: []
          description: Filter by [Extra Identifiers](/api-reference/core/models/extra-identifier) - EIC, Ediel, VAT, and similar market-specific identifiers
          items:
            type: string
          title: Extra Id
          type: array
      - description: Filter by ISO 3166-1 alpha-2 country codes
        in: query
        name: country
        required: false
        schema:
          default: []
          description: Filter by ISO 3166-1 alpha-2 country codes
          examples:
          - SE
          items:
            type: string
          title: Country
          type: array
      - description: Filter by legal name using substring matching
        in: query
        name: name
        required: false
        schema:
          default: []
          description: Filter by legal name using substring matching
          items:
            type: string
          title: Name
          type: array
      - description: Filter by party role(s)
        in: query
        name: role
        required: false
        schema:
          default: []
          description: Filter by party role(s)
          examples:
          - system-operator
          items:
            type: string
          title: Role
          type: array
      responses:
        '200':
          content:
            application/json:
              example:
                parties:
                - countries:
                  - SE
                  extra_ids:
                  - kind: eic
                    value: 46X000000000245K
                  - kind: se.ediel
                    value: '24200'
                  id: 0199c317-25ec-7cf7-94cc-32a39f068433
                  name: Ellevio AB
              schema:
                $ref: '#/components/schemas/GetPartiesResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Parties
      tags:
      - Core
  /core/v1/scheduling-areas:
    get:
      description: 'List & filter scheduling areas.


        If you specify multiple values for some filter parameter they are OR-ed. If you specify multiple separate filters they are "AND"-ed.'
      operationId: list_scheduling_areas_core_v1_scheduling_areas_get
      parameters:
      - description: Filter by EIC code(s)
        in: query
        name: id
        required: false
        schema:
          default: []
          description: Filter by EIC code(s)
          items:
            type: string
          title: Id
          type: array
      - description: Filter by name or short name using substring matching
        in: query
        name: name
        required: false
        schema:
          default: []
          description: Filter by name or short name using substring matching
          items:
            type: string
          title: Name
          type: array
      - description: Filter by ISO 3166-1 alpha-2 country codes
        in: query
        name: country
        required: false
        schema:
          default: []
          description: Filter by ISO 3166-1 alpha-2 country codes
          examples:
          - SE
          items:
            type: string
          title: Country
          type: array
      responses:
        '200':
          content:
            application/json:
              example:
                scheduling_areas:
                - countries:
                  - SE
                  id: 10Y1001A1001A47J
                  name: Swedish Elspot Area 4
                  short_name: SE4
              schema:
                $ref: '#/components/schemas/GetSchedulingAreasResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Scheduling Areas
      tags:
      - Core
components:
  schemas:
    MeteringGridArea:
      description: 'A Metering Grid Area (MGA) is a core domain concept in the European energy market.


        The [ENTSO-E Harmonized Electricity Market Role Model](https://www.entsoe.eu/data/cim/role-models/) defines an MGA as:


        > A physical area where consumption, production and exchange can be measured. It is delimited by the placement of meters for continuous measurement for input to, and withdrawal from the area.


        In other words, an MGA is a collection of Metering Points operated by some System Operator, usually a DSO.'
      example:
        extra_ids:
        - kind: eic
          value: 46Y000000000016G
        - kind: se.mga_code
          value: STO
        id: 0199c317-25ec-7c00-b1a0-a1b2c3d4e5f6
        name: Stockholm
        scheduling_area_eic: 10Y1001A1001A47J
        system_operator:
          extra_ids:
          - kind: eic
            value: 46X000000000245K
          id: 0199c317-25ec-7cf7-94cc-32a39f068433
      properties:
        extra_ids:
          description: '[Extra Identifiers](/api-reference/core/models/extra-identifier) for this MGA'
          items:
            $ref: '#/components/schemas/ExtraIdentifier'
          title: Extra Ids
          type: array
        id:
          description: Unique identifier for the MGA
          format: uuid
          title: Id
          type: string
        name:
          description: Name of the metering grid area
          title: Name
          type: string
        scheduling_area_eic:
          description: EIC code for the Scheduling Area this Metering Grid Area belongs to
          title: Scheduling Area Eic
          type: string
        system_operator:
          $ref: '#/components/schemas/Identifier'
          description: The [Party](/api-reference/core/models/party) that operates this MGA
      required:
      - extra_ids
      - id
      - name
      - scheduling_area_eic
      - system_operator
      title: MeteringGridArea
      type: object
    ControlArea:
      description: 'A Control Area is a core domain concept in the European energy market.


        The [ENTSO-E Harmonized Electricity Market Role Model](https://www.entsoe.eu/data/cim/role-models/) defines a Control Area as:


        > A coherent part of the interconnected system, operated by a single System Operator and shall include connected physical loads and/or generation units if any.


        In other words, it is the grid a single TSO operates. It is distinct from the Scheduling Area, which is the area sharing one imbalance price. One good example is Germany, where a single Scheduling Area (DE/LU) is divided into four Control Areas — 50Hertz, Amprion, TenneT DE and TransnetBW.'
      example:
        countries:
        - DE
        id: 10YDE-VE-------2
        name: Germany 50Hertz
        short_name: DE-50HERTZ
      properties:
        countries:
          description: ISO 3166-1 alpha-2 country codes this control area covers
          items:
            type: string
          title: Countries
          type: array
        id:
          description: EIC code identifying this control area
          title: Id
          type: string
        name:
          description: Full official name of the control area
          title: Name
          type: string
        short_name:
          description: Short display name for the control area
          title: Short Name
          type: string
      required:
      - countries
      - id
      - name
      - short_name
      title: ControlArea
      type: object
    IdentifierKind:
      enum:
      - eic
      - vat
      - gln
      - se.ediel
      - se.mga_code
      - no.mga_code
      - esett.mga_type
      title: IdentifierKind
      type: string
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    BiddingZone:
      description: 'A Bidding Zone (also called a price area) is a core domain concept in the European energy market.


        The [ENTSO-E Harmonized Electricity Market Role Model](https://www.entsoe.eu/data/cim/role-models/) defines a Bidding Zone as:


        > The largest geographical area within which market participants are able to exchange energy without capacity allocation.


        In other words, it is an area within which electricity clears at a single day-ahead price; in the Nordics these are the Nord Pool price areas such as SE3 and NO1.'
      example:
        countries:
        - SE
        id: 10Y1001A1001A46L
        name: Swedish Elspot Area 3
        short_name: SE3
      properties:
        countries:
          description: ISO 3166-1 alpha-2 country codes this bidding zone covers
          items:
            type: string
          title: Countries
          type: array
        id:
          description: EIC code identifying this bidding zone
          title: Id
          type: string
        name:
          description: Full official name of the bidding zone
          title: Name
          type: string
        short_name:
          description: Short display name for the bidding zone
          title: Short Name
          type: string
      required:
      - countries
      - id
      - name
      - short_name
      title: BiddingZone
      type: object
    GetSchedulingAreasResponse:
      properties:
        scheduling_areas:
          items:
            $ref: '#/components/schemas/SchedulingArea'
          title: Scheduling Areas
          type: array
      required:
      - scheduling_areas
      title: GetSchedulingAreasResponse
      type: object
    SchedulingArea:
      description: 'A Scheduling Area is a core domain concept in the European energy market.


        The [ENTSO-E Harmonized Electricity Market Role Model](https://www.entsoe.eu/data/cim/role-models/) defines a Scheduling Area as:


        > An area within which the TSOs'' obligations regarding scheduling apply due to operational or organisational needs. This area consists of one or more Metering Grid Areas with common market rules for which the settlement responsible party carries out an imbalance settlement and which has the same price for imbalance.


        In other words, it is the area within which schedules are submitted and imbalance is settled at a single price. In the Nordics each Scheduling Area shares its EIC with the corresponding Bidding Zone (e.g. SE3, NO1).'
      example:
        countries:
        - SE
        id: 10Y1001A1001A47J
        name: Swedish Elspot Area 4
        short_name: SE4
      properties:
        countries:
          description: ISO 3166-1 alpha-2 country codes this scheduling area covers
          items:
            type: string
          title: Countries
          type: array
        id:
          description: EIC code identifying this scheduling area
          title: Id
          type: string
        name:
          description: Full official name of the scheduling area
          title: Name
          type: string
        short_name:
          description: Short display name for the scheduling area
          title: Short Name
          type: string
      required:
      - countries
      - id
      - name
      - short_name
      title: SchedulingArea
      type: object
    GetBiddingZonesResponse:
      properties:
        bidding_zones:
          items:
            $ref: '#/components/schemas/BiddingZone'
          title: Bidding Zones
          type: array
      required:
      - bidding_zones
      title: GetBiddingZonesResponse
      type: object
    ExtraIdentifier:
      description: 'Extra identifiers are used to attach things like EIC ids, VAT numbers, jurisdiction-specific identifiers, etc.


        For example, Metering Grid Area''s in parts of Europe are assigned an local jurisdiction EIC code; for those MGAs, the Engrate system will store the EIC as an extra identifier. However some jurisdictions have not yet switched to EIC codes, instead they rely on older local identification schemes. Swedish MGAs, as an example, use a local code assigned by the Swedish TSO.


        Because the local schemes are subject to collisions - two TSOs assigning the same numerical code to different things, as they do not coordinate id assignment - we also track an identifier "kind".'
      example:
        kind: eic
        value: 46X000000000245K
      properties:
        kind:
          $ref: '#/components/schemas/IdentifierKind'
          description: The kind of identifier
        value:
          description: The identifier value
          title: Value
          type: string
      required:
      - kind
      - value
      title: ExtraIdentifier
      type: object
    Identifier:
      example:
        extra_ids:
        - kind: eic
          value: 46X000000000245K
        id: 0199c317-25ec-7cf7-94cc-32a39f068433
      properties:
        extra_ids:
          description: '[Extra Identifiers](/api-reference/core/models/extra-identifier) used to reference this same entity'
          items:
            $ref: '#/components/schemas/ExtraIdentifier'
          title: Extra Ids
          type: array
        id:
          description: Unique identifier assigned by Engrate
          format: uuid
          title: Id
          type: string
      required:
      - extra_ids
      - id
      title: Identifier
      type: object
    GetControlAreasResponse:
      properties:
        control_areas:
          items:
            $ref: '#/components/schemas/ControlArea'
          title: Control Areas
          type: array
      required:
      - control_areas
      title: GetControlAreasResponse
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    Party:
      description: 'Represents a "Market Party" of some kind. Normally this is some legal person - a corporation, government entity, NGO etc - that serves some role in the electrical system.


        Parties may be DSOs, TSOs, Energy Retailers and so on.'
      example:
        countries:
        - SE
        extra_ids:
        - kind: eic
          value: 46X000000000245K
        - kind: se.ediel
          value: '24200'
        id: 0199c317-25ec-7cf7-94cc-32a39f068433
        name: Ellevio AB
      properties:
        countries:
          description: ISO 3166-1 alpha-2 country codes, this indicates countries where this party is active in some way, not only their legal home country
          items:
            type: string
          title: Countries
          type: array
        description:
          anyOf:
          - type: string
          - type: 'null'
          description: Brief description of the party, if available
          title: Description
        extra_ids:
          description: '[Extra Identifiers](/api-reference/core/models/extra-identifier) for this Party, like EIC identifiers where those exist'
          items:
            $ref: '#/components/schemas/ExtraIdentifier'
          title: Extra Ids
          type: array
        id:
          description: Unique identifier for the party
          format: uuid
          title: Id
          type: string
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          description: URL to the logo of the party, if available
          title: Logo Url
        name:
          description: Legal name of the party
          title: Name
          type: string
        website_url:
          anyOf:
          - type: string
          - type: 'null'
          description: URL to the website of the party, if available
          title: Website Url
      required:
      - countries
      - description
      - extra_ids
      - id
      - logo_url
      - name
      - website_url
      title: Party
      type: object
    GetMeteringGridAreasResponse:
      properties:
        mgas:
          items:
            $ref: '#/components/schemas/MeteringGridArea'
          title: Mgas
          type: array
      required:
      - mgas
      title: GetMeteringGridAreasResponse
      type: object
    GetPartiesResponse:
      properties:
        parties:
          items:
            $ref: '#/components/schemas/Party'
          title: Parties
          type: array
      required:
      - parties
      title: GetPartiesResponse
      type: object
  securitySchemes:
    apiKeyAuth:
      in: header
      name: Authorization
      type: apiKey