Skip to main content
Deno 2 is finally here 🎉️
Learn more

entsoe-api-client

Unofficial ENTSO-e REST API Client for Deno and Node. Comprehensive. User-friendly. Minimalistic.

Module type: CJS+ESM NPM Downloads MIT License

Features

  • Supports all requests listed in Entso-e REST API Documentation
  • Supports zip-file endpoints and transparently unzips documents
  • Includes examples that support both Deno and Node
  • Supports both Deno and Node (>=18.0)
  • Written in fully typed TypeScript
  • Offers ESM (for Deno and Node) and CommonJS (for Node) support
  • Adds descriptions to codes while parsing the documents

Installation

Make sure to use a recent version of your runtime. Node.js >=18 and Deno >=1.26 are supported.

Deno

import { QueryConfiguration } from "https://deno.land/x/entsoe_api_client/mod.ts";

Node

npm install entsoe-api-client --save

Note Using an older version of Node.js? Use 0.x versions of this library for fetch compatibility.

Documentation

The structure of the documents and the parameters returned by this library closely resemble what you can find in the ENTSO-e REST API documentation. It is recommended that you also take a look there.

If you want a Publication_MarketDocument, the corresponding function in this library is queryPublication. In the resulting document (object), the key receiver_MarketParticipant.mRID will become receiverMarketParticipantId. The same transformation applies to the parameters. We recommend enabling auto-completion in your editor, as the types will provide great help in navigating the parameters and document objects.

Another difference compared to the source documents is that most IDs automatically come with a complementary description, where applicable. For example, <businessType>B33</.. in the raw XML will result in the keys businessType: “B33” and businessTypeDescription: “Area Control Error” in the output.

Note The full library and method documentation can be found at deno.land/x/entsoe_api_client.

Methods

Querying

Method Interface Description
Query (securityToken, params)
=>
Promise
Fetch any document, and return a array of typed and
parsed JavaScript object(s). Primarily internal, but exported.
QueryPublication (securityToken, params)
=>
Promise
Request Publication_MarketDocument(s), and return
a array of typed and parsed JavaScript object(s)
QueryGL (securityToken, params)
=>
Promise
Same, for GL_MarketDocument
QueryUnavailability (securityToken, params)
=>
Promise
Same, for Unavailability_MarketDocument
QueryConfiguration (securityToken, params)
=>
Promise
Same, for Configuration_MarketDocument
QueryBalancing (securityToken, params)
=>
Promise
Same, for Balancing_MarketDocument(s)
QueryTransmissionNetwork (securityToken, params)
=>
Promise
Same, for Transmission_MarketDocument(s)
QueryCriticalNetworkElement (securityToken, params)
=>
Promise
Same, for CriticalNetworkElement_MarketDocument(s)

Translations

Helper functions for translating human-readable descriptions to IDs that can be used by the API.

Method Interface Description
Area (identifier)
=>
string[] | undefined
Finds internal id (10YL-1001A00074) of all areas
having aspecific identier (CTA|SE, BZN|DE-LU etc…)
AllAreas (identifier)
=>
string | undefined
Same as above, but return first match
DocumentType (name)
=>
string | undefined
Get document type from Document name
ProcessType (name)
=>
string | undefined
Get process type from process name
BusinessType (name)
=>
string | undefined
Get business type from business name
PsrType (name)
=>
string | undefined
Get psr type from psr name
AuctionType (name)
=>
string | undefined
Get auction type from auction name
AuctionCategory (name)
=>
string | undefined
Get auction category type from auction category name
Direction (name)
=>
string | undefined
Get direction id from direction name
DocStatus (name)
=>
string | undefined
Get document status id from document status name
MarketAgreementType (name)
=>
string | undefined
Get market agreement type id from market agreement type name
MarketProduct (name)
=>
string | undefined
Get Market product id from market product name

Parsing

Method Interface Description
ParseDocument (xmlDocument)
=>
PublicationDocument|BalancingDoc…
Parses raw XML into a typed object.
Primarily internal, but exported and usable.

Note The parsing function is mainly intended for internal use within the library.

Query Parameters

All parameters that can be passed to Query(), QueryPublication(), etc.

Parameter Name Type Name in ENSO-e REST API Note
documentType string DocumentType
processType (optional) string ProcessType
businessType (optional) string BusinessType
psrType (optional) string PsrType
inDomain (optional) string In_Domain
inBiddingZoneDomain (optional) string InBiddingZone_Domain
biddingZoneDomain (optional) string BiddingZone_Domain
outDomain (optional) string Out_Domain
outBiddingZoneDomain (optional) string OutBiddingZone_Domain
startDateTime(optional) Date TimeInterval ISO8601 string
endDateTime (optional) Date TimeInterval ISO8601 string
startDateTimeUpdate (optional) Date TimeIntervalUpdate ISO8601 string
endDateTimeUpdate (optional) Date TimeIntervalUpdate ISO8601 string
offset (optional) number Offset Enables fetching more than x documents by using pagination
implementationDateAndOrTime (optional) string Implementation_DateAndOrTime ISO8601 string
contractMarketAgreementType (optional) string Contract_MarketAgreement.Type
auctionType (optional) string Auction.Type
auctionCategory (optional) string Auction.Category
classificationSequenceAICPosition (optional) string ClassificationSequence_(…).Position
connectingDomain (optional) string connecting_Domain
standardMarketProduct (optional) string Standard_MarketProduct
originalMarketProduct(optional) string Original_MarketProduct
registeredResource (optional) string registeredResource
acquiringDomain (optional) string Acquiring_Domain
mRID (optional) string mRID
docStatus (optional) string DocStatus

Examples

Examples can be found in the /examples directory.

To run the examples, pass your ENTSO-e API key as an environment variable called API_TOKEN. Deno

Powershell

$env:API_TOKEN="your-api-token"; deno run -A .\spot-prices-today.ts

Bash

API_TOKEN="your-api-token" deno run -A .\spot-prices-today.ts

Node

Powershell

$env:API_TOKEN="your-api-token"; node .\spot-prices-today.ts

Bash

API_TOKEN="your-api-token" node .\spot-prices-today.ts

Contributing

Deno CI Node CI

All contributions are welcome.

The module is developed in Deno. The Node module is generated using dnt, as described in scripts/build_npm.ts.

For more information, please refer to the Contribution Guide.

Note Please run deno task precommit before each commit to ensure that every file is tested, formatted, and linted to standards.

Donations

Sponsor me on GitHub, or

Buy Me a Coffee at ko-fi.com

License

MIT License