sdgdata 0.1.0

Simple Python client for the United Nations Statistics Division SDG API

sdgdata

sdgdata is an unofficial Python client for SDG data from the UNSD SDG API.

It provides a simple client to retrieve Sustainable Development Goal metadata and data from Python, with models derived from the UNSD SDG API schema.

Features

• Fetch SDG goals, targets, indicators, and series metadata.
• Look up geographic areas and M49 area codes.
• Retrieve paginated SDG series observations with simple Python calls.
• Validate structured API responses with Pydantic models.
• Load observation data into analysis tools such as pandas or Polars.

Installation

Install from PyPI:

uv add sdgdata

or:

pip install sdgdata

Quick Start

from sdgdata import SDGClient
from sdgdata.client import is_single_time_series

client = SDGClient()

# Find available geographic areas and SDG targets.
areas = client.get_geo_areas()
targets = client.get_targets()

# Find latest-release series codes for a target.
series = client.get_series_codes(target_code="3.8")
series_code = series[-1].code
area_code = areas[0].geoAreaCode

# Inspect available disaggregation dimensions for a series.
dimensions = client.get_series_dimensions(series_code)

# Fetch the coarsest available disaggregation by default.
data = client.get_series_data(
    series_codes=[series_code],
    area_code=area_code,
    start_period="2015",
    end_period="2026",
)

assert is_single_time_series(data)

# To fetch every disaggregation, opt into the unfiltered API response.
all_disaggregations = client.get_series_data(
    series_codes=[series_code],
    area_code=area_code,
    start_period="2015",
    end_period="2026",
    dimensions="all",
)

# Or request a specific disaggregation slice.
custom_slice = client.get_series_data(
    series_codes=[series_code],
    area_code=area_code,
    dimensions={"Reporting Type": "G"},
)

get_series_data() returns a list of dictionaries, making it straightforward to create a dataframe for analysis. It normalizes singleton goal, target, and indicator arrays to strings, and integral timePeriodStart values to integers. By default, it filters to the coarsest available disaggregation, such as all ages, both sexes, and total groups when those dimension values exist. For the upstream observation field descriptions, see the UNSD SDG API Swagger documentation.

Documentation

• Development: setup, tests, fixture refreshes, builds, and CI behavior.
• Model generation: generated models, stale checks, and OpenAPI source data.