Metadata-Version: 2.4
Name: sdgdata
Version: 0.1.0
Summary: Simple Python client for the United Nations Statistics Division SDG API
Author-email: Vassily Trubetskoy <3219751+v-a-s-a@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/v-a-s-a/sdgdata
Project-URL: Repository, https://github.com/v-a-s-a/sdgdata
Project-URL: Issues, https://github.com/v-a-s-a/sdgdata/issues
Project-URL: Documentation, https://github.com/v-a-s-a/sdgdata#readme
Keywords: sdg,statistics,sustainable-development-goals,united-nations,unsd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.12.3
Dynamic: license-file

# 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:

```bash
uv add sdgdata
```

or:

```bash
pip install sdgdata
```

## Quick Start

```python
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](https://unstats.un.org/sdgapi/swagger/).

## Documentation

- [Development](docs/development.md): setup, tests, fixture refreshes, builds, and CI behavior.
- [Model generation](docs/model-generation.md): generated models, stale checks, and OpenAPI source data.
