Documentation

The main aim of Releases API is to provide a way to download releases files programatically which can be employed to download releases files on regular basis or as they just got published.

Please note that this feature is only offered to customers purchasing an Enterprise or Global Enterprise licence.

To be able to consume the API, an API Key is needed.

API token is available under Settings > Releases API

You can activate/deactivate the API key at any time

Also you can generate new token which will revoke older one

Base URL for the API: www.iea.org/api  

Usage

The API key must be sent alongside each request as an authorization header

"Authorization: Bearer ..."

Description

Can be used to list user's purchased products and to gather details like product ID and access validity state

Request

POST /api/v1/products

Response

[
    {
        "id": 1,
        "title": "World Energy Balances",
        "releasesCount": 91,
        "latestReleaseDate": "2022-10-13"
    },
    ...
]

Description

Can be used to list product releases

Request

POST /api/v1/products/{product-id}/releases

Response

[
    {
        "id": 123,
        "title": "World Energy Outlook 2020",
        "publish_start_date": "2020-10-13",
        "date": "2021-09-15",
        "isScheduled": false
    }
    ...
]

Description

Can be used to get a release by its ID

Request

POST /api/v1/products/{product-id}/releases/{release-id}

Response

{
    "id": 123,
    "title": "October 2022 edition",
    "date": "2022-10-03",
    "combined_file": {
        "id": 12345,
        "format": "pdf",
        "filename": "October-files.zip",
        "size": "21.21 Mb"
    },
    "data_sets": [
        {
            "title": "Coal imports and exports, OECD and selected countries",
            "description": "Import and export data by country of origin for OECD member states and selected countries from 1978 to 2021.\n\nProducts: anthracite, coking coal, other bituminous coal, sub-bituminous coal, lignite, patent fuel, coke oven coke, gas coke, coal tar, BKB, gas works gas, coke oven gas, blast furnace gas, other recovered gases, peat, and peat products. The aggregates hard coal, brown coal and steam coal are also included.\n\nUnit: kilotons\n\nZIP files contain data in fixed-width TXT format.",
            "data": [
                {
                    "name": "Coal imports by origin, OECD and selected countries",
                    "updated_at": "2022-10-03",
                    "files": [
                        {
                            "id": 12345,
                            "format": "ivt",
                            "filename": "CoalImportsFiles.ivt",
                            "size": "22.15 Mb"
                        },
                        {
                            "id": 12345,
                            "format": "TXT",
                            "filename": "IVTIMPort.TXT",
                            "size": "14.52 Mb"
                        }
                    ]
                },
                ...
            ]
        },
        ...
    ]
}

Description

Can be used to get the latest release of a product

Request

POST /api/v1/products/{product-id}/releases/latest

Response

{
    "id": 123,
    "title": "October 2022 edition",
    "date": "2022-10-03",
    "combined_file": {
        "id": 12345,
        "format": "pdf",
        "filename": "October-files.zip",
        "size": "21.21 Mb"
    },
    "data_sets": [
        {
            "title": "Coal imports and exports, OECD and selected countries",
            "description": "Import and export data by country of origin for OECD member states and selected countries from 1978 to 2021.\n\nProducts: anthracite, coking coal, other bituminous coal, sub-bituminous coal, lignite, patent fuel, coke oven coke, gas coke, coal tar, BKB, gas works gas, coke oven gas, blast furnace gas, other recovered gases, peat, and peat products. The aggregates hard coal, brown coal and steam coal are also included.\n\nUnit: kilotons\n\nZIP files contain data in fixed-width TXT format.",
            "data": [
                {
                    "name": "Coal imports by origin, OECD and selected countries",
                    "updated_at": "2022-10-03",
                    "files": [
                        {
                            "id": 12345,
                            "format": "ivt",
                            "filename": "CoalImportsFiles.ivt",
                            "size": "22.15 Mb"
                        },
                        {
                            "id": 12345,
                            "format": "TXT",
                            "filename": "IVTIMPort.TXT",
                            "size": "14.52 Mb"
                        }
                    ]
                },
                ...
            ]
        },
        ...
    ]
}

Description

Can be used to get the download a release file

Request

POST /api/v1/product/download-file-by-ids

Headers

"Content-Type: application/json"

Body

{
    "productId": 1,
    "releaseId": 123,
    "fileId": 456
}

Response

File content

Implementation of above endpoints do exists in the Postman collection below. You will just need to set the token variable to the correct value