Querying IIASA databases

You can query scenario data from an IIASA database instance directly via Python, R or a Rest API. The pyam package allows to directly query both the new Scenario Apps and the (legacy) Scenario Explorer databases (2018-2024).

import pyam
df = pyam.read_iiasa("<slug>", region="World", ...)

Here, the slug is the name of the database. To avoid large queries, you can also filter by model, scenario or variable.

Tip

Learn more about the Python package pyam on Read The Docs.

There is a tutorial to use pyam with R via the reticulate package.

The approach for more complex queries depends on the database backend:

• Scenario Apps and ixmp4 instances

• Legacy Scenario Explorer instances

Note

Access and permission management for project-internal databases

By default, your can connect to all public scenario database instances via the API. If you have permission to connect to a private, project-internal database instance, you can set your credentials by running the following command in a console:

ixmp4 login <username>

You will be prompted to enter your password.

Your username and password will be saved locally in plain-text for future use.

Scenario Apps and ixmp4 instances

New Scenario Explorer instances (set up since 2025) use the ScSe Apps infrastructure and the ixmp4 package as a database backend. You can list all ixmp4 platforms hosted by IIASA (and to which you have access) using pyam.iiasa.platforms().

You can use pyam.read_iiasa() for simple queries or the ixmp4 package for connecting to a platform and executing other requests.

import ixmp4

# connect to a database platform
platform = ixmp4.Platform("<slug>")

# get a table of all "scenario runs" in the database
platform.runs.tabulate()

# get a table of all IAMC variables
platform.iamc.variables.tabulate()

Legacy Scenario Explorer instances

You can use the pyam package to connect to a legacy Scenario Explorer instance developed by the Scenario Services and Scientific Software team from 2018 until 2024.

You can use pyam.read_iiasa() for simple queries or the pyam.iiasa.Connection class to get a list of available instances or for more elaborate queries.

import pyam

# get a list of all available legacy database instances
pyam.iiasa.Connection().valid_connections

# connect to a specific legacy database instance
database = pyam.iiasa.Connection("<slug>")

# get a table of all scenarios in this database
database.properties()