IASO Client

The iaso-client Python library authenticates against an IASO instance and fetches organisation units, organisation unit types, forms, form versions and form submissions, with automatic pagination.

The library is maintained by the IASO team: see the iaso-client repository for its source code and full documentation.

Installation¶

iaso-client is pre-installed in the OpenHEXA notebook and pipeline images. To use it elsewhere (or to pin a specific version in a pipeline's requirements.txt):

pip install iaso-client

Usage¶

Connect to an instance¶

Create a IasoClient with the base URL of the IASO instance (without a trailing slash), then call login(). The bearer token is stored and reused for all subsequent requests.

In an OpenHEXA workspace, store the credentials in an IASO connection and read them with the SDK:

from openhexa.sdk import workspace
from iaso_client import IasoClient

con = workspace.iaso_connection("iaso-connection-identifier")

client = IasoClient(base_url=con.url.rstrip("/"))
client.login(con.username, con.password)

Read data¶

Every resource exposes *_list() and *_retrieve() methods. *_list() fetches every page and returns all matching items as a list. Filters are passed as keyword arguments.

# Organisation units
org_units = client.org_units_list(org_unit_type_id=5, project=149)
org_unit = client.org_units_retrieve(org_unit_id=781)

# Organisation unit types
org_unit_types = client.org_unit_types_list(project=149)

# Forms and form versions
forms = client.forms_list(projects_ids=[149])
form = client.forms_retrieve(form_id=276)
form_versions = client.form_versions_list(form_id=276)

# Form submissions (instances)
instances = client.instances_list(form_id=276, date_from="2025-01-01")
instance = client.instances_retrieve(instance_id=12345)

Get a pandas DataFrame¶

*_list() returns a list of dictionaries, which can be loaded into a DataFrame:

import pandas as pd

df = pd.json_normalize(client.instances_list(form_id=276))

See the iaso-client repository for the full list of filters.

Migrating from openhexa.toolbox.iaso¶