Basics of importing data using dhis2-python-client

This section walks you through importing data values into DHIS2 using the dhis2-python-client library.

Below are crucial steps to follow:

Get credentials
Connect to DHIS2 and verify access
Build a valid dataValueSets payload (JSON or CSV)
Send your payload

1) Configure your environment and connect to DHIS2¶

from dhis2_client import DHIS2Client
from dhis2_client.settings import ClientSettings

# Client configuration
cfg = ClientSettings(
  base_url="https://play.im.dhis2.org/stable-2-42-3-1",
  username="admin",
  password="district")

client = DHIS2Client(settings=cfg)
info = client.get_system_info()

# Check if everything is working.
# You should see your current DHIS2 version info.
print("▶ Current DHIS2 version:", info["version"])

▶ Current DHIS2 version: 2.42.2-SNAPSHOT

2) Construct payload¶

Data values can be sent to DHIS2 in batch, by submitting the data values to the api/dataValueSets endpoint of the DHIS2 REST API. Below is a sample payload demonstrating how to manually create the data payload to send to the API endpoint:

payload = {
    "dataValues": [
        {
            "orgUnit": "O6uvpzGd5pu",
            "period": "20250101",
            "value": "23.68",
            "dataElement": "VJwwPOOvge6"
        },
        {
            "orgUnit": "fdc6uOvgoji",
            "period": "20250101",
            "value": "23.96",
            "dataElement": "VJwwPOOvge6"
        },
        {
            "orgUnit": "lc3eMKXaEfw",
            "period": "20250101",
            "value": "24.52",
            "dataElement": "VJwwPOOvge6"
        },
        {
            "orgUnit": "jUb8gELQApl",
            "period": "20250101",
            "value": "23.06",
            "dataElement": "VJwwPOOvge6"
        },
        {
            "orgUnit": "PMa2VCrupOd",
            "period": "20250101",
            "value": "24.45",
            "dataElement": "VJwwPOOvge6"
        },
        {
            "orgUnit": "kJq2mPyFEHo",
            "period": "20250101",
            "value": "23.27",
            "dataElement": "VJwwPOOvge6"
        }
    ]
}

However, if you have followed the steps for aggregating climate data to org units, you need a way to construct this JSON payload from a pandas.DataFrame. For the sake of this tutorial, let’s assume your data has already been aggregated by someone else and provided to you in a CSV file, which can be loaded into a pandas.DataFrame:

import pandas as pd
df = pd.read_csv('../data/sample_payload.csv')
df

To construct a valid JSON payload for importing a pandas.DataFrame into DHIS2, we can use the dhsi2eo utility function dataframe_to_dhis2_json:

from dhis2eo.integrations.pandas import dataframe_to_dhis2_json
payload = dataframe_to_dhis2_json(
    df = df,                        # pandas.DataFrame
    org_unit_col = 'orgUnit',            # column containing the org unit id
    period_col = 'period',      # column containing the period
    value_col = 'value',              # column containing the value
    data_element_id = 'VJwwPOOvge6' # id of the DHIS2 data element
)
payload

{'dataValues': [{'orgUnit': 'O6uvpzGd5pu',
   'period': '20250101',
   'value': 23.68,
   'dataElement': 'VJwwPOOvge6'},
  {'orgUnit': 'fdc6uOvgoji',
   'period': '20250101',
   'value': 23.96,
   'dataElement': 'VJwwPOOvge6'},
  {'orgUnit': 'lc3eMKXaEfw',
   'period': '20250101',
   'value': 24.52,
   'dataElement': 'VJwwPOOvge6'},
  {'orgUnit': 'jUb8gELQApl',
   'period': '20250101',
   'value': 23.06,
   'dataElement': 'VJwwPOOvge6'},
  {'orgUnit': 'PMa2VCrupOd',
   'period': '20250101',
   'value': 24.45,
   'dataElement': 'VJwwPOOvge6'},
  {'orgUnit': 'kJq2mPyFEHo',
   'period': '20250101',
   'value': 23.27,
   'dataElement': 'VJwwPOOvge6'}]}

3) Send your payload¶

Once we are done preparing our payload we can proceed to send it to DHIS2. dhis2-python-client provides both direct access to raw DHIS2 API like client.post(/api/dataValueSets, ...) and convenient method like client.post_data_value_set(...). Since we saw convenient methods in the above metadata creation steps, let’s use raw DHIS2 API access this time.

res = client.post("/api/dataValueSets", json=payload)

4) Troubleshooting¶

Unauthorized: Check credentials and user permissions.
Not found: Verify data element, org unit, and combos (if you have used non-default ones) exist.
Conflicts: Ensure dataset assignments and period are correct.
Locked periods: Unlock dataset period if needed.
Value types: Match the data element value type.