sdgdata 0.1.0__tar.gz

sdgdata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vassily Trubetskoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sdgdata-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-exclude tests *
+prune tests

sdgdata-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+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.

sdgdata-0.1.0/README.md

@@ -0,0 +1,88 @@
+# 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.

sdgdata-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sdgdata"
+version = "0.1.0"
+description = "Simple Python client for the United Nations Statistics Division SDG API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Vassily Trubetskoy", email = "3219751+v-a-s-a@users.noreply.github.com" },
+]
+requires-python = ">=3.12"
+keywords = [
+    "sdg",
+    "statistics",
+    "sustainable-development-goals",
+    "united-nations",
+    "unsd",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.12.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/v-a-s-a/sdgdata"
+Repository = "https://github.com/v-a-s-a/sdgdata"
+Issues = "https://github.com/v-a-s-a/sdgdata/issues"
+Documentation = "https://github.com/v-a-s-a/sdgdata#readme"
+
+[dependency-groups]
+dev = [
+    "openapi-python-client==0.28.4",
+    "pytest>=8.0.0",
+    "respx>=0.22.0",
+    "ruff>=0.8.0",
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "mock: deterministic tests that mock the UNSD API",
+    "live: tests that call the live UNSD API",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src", "tests", "scripts"]
+exclude = [
+    "generated/openapi_python_client",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sdgdata*"]

sdgdata-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sdgdata-0.1.0/src/sdgdata/__init__.py

@@ -0,0 +1,5 @@
+from .client import SDGClient
+
+__all__ = [
+    "SDGClient",
+]

sdgdata-0.1.0/src/sdgdata/client.py

@@ -0,0 +1,305 @@
+from collections.abc import Mapping, Sequence
+
+import httpx
+
+from sdgdata.models import (
+    ApiDimension,
+    ApiGeoArea,
+    ApiGoal,
+    ApiIndicator,
+    ApiSerie,
+    ApiTarget,
+    ConceptsMasterData,
+    SDMXMetaDataResponse,
+)
+
+from . import debug
+from .metadata import IndicatorSeriesMetadata, SeriesMetadata, TargetSeriesMetadata
+from .utilities import (
+    DimensionArgument,
+    _coarsest_dimension_filters,
+    _dimension_payload,
+    _normalize_observation,
+    _period_query_params,
+    _release_sort_key,
+    _series_code_list,
+)
+from .utilities import (
+    is_single_time_series as is_single_time_series,
+)
+
+# standard UNSD API base URL
+BASE_URL = "https://unstats.un.org/sdgapi/v1"
+
+
+def _group_series_metadata(
+    series_items: list[ApiSerie],
+    dimensions_by_code: Mapping[str, list[ApiDimension]],
+) -> list[SeriesMetadata]:
+    """
+    Groups repeated UNSD release rows into one discovery record per series code.
+    """
+    series_by_code: dict[str, list[ApiSerie]] = {}
+    for series in series_items:
+        if series.code is None:
+            continue
+        series_by_code.setdefault(series.code, []).append(series)
+
+    grouped_series = []
+    for code, releases in series_by_code.items():
+        latest = max(releases, key=lambda item: _release_sort_key(item.release))
+        release_codes = sorted(
+            {release.release for release in releases if release.release is not None},
+            key=_release_sort_key,
+        )
+        grouped_series.append(
+            SeriesMetadata(
+                code=code,
+                description=latest.description,
+                uri=latest.uri,
+                latest_release=latest.release,
+                releases=release_codes,
+                dimensions=dimensions_by_code.get(code, []),
+            )
+        )
+
+    return sorted(grouped_series, key=lambda series: series.code)
+
+
+def _indicator_series_metadata(
+    indicator: ApiIndicator,
+    dimensions_by_code: Mapping[str, list[ApiDimension]],
+) -> IndicatorSeriesMetadata:
+    """
+    Builds the public discovery model for one generated UNSD indicator model.
+    """
+    return IndicatorSeriesMetadata(
+        code=indicator.code or "",
+        description=indicator.description,
+        tier=indicator.tier,
+        uri=indicator.uri,
+        series=_group_series_metadata(indicator.series or [], dimensions_by_code),
+    )
+
+
+class SDGClient:
+    def __init__(self):
+        self.client = httpx.Client(base_url=BASE_URL, timeout=30.0)
+
+    def _get(self, url: str, *, params: dict | None = None) -> httpx.Response:
+        request = self.client.build_request("GET", url, params=params)
+        debug.print_query(request)
+        return self.client.send(request)
+
+    def get_targets(self, include_children: bool = False) -> list[ApiTarget]:
+        """
+        Fetches all targets, optionally including their indicators and series.
+        """
+        response = self._get("/sdg/Target/List", params={"includechildren": include_children})
+        response.raise_for_status()
+        data = response.json()
+        return [ApiTarget(**item) for item in data]
+
+    def get_series_codes(
+        self, target_code: str | None = None, *, all_releases: bool = False
+    ) -> list[ApiSerie]:
+        """
+        Returns latest series codes and descriptions, optionally filtered by target code.
+        """
+        targets = self.get_targets(include_children=True)
+        series_list = []
+        for target in targets:
+            if target_code and target.code != target_code:
+                continue
+            if target.indicators:
+                for indicator in target.indicators:
+                    if indicator.series:
+                        series_list.extend(indicator.series)
+        if all_releases:
+            return series_list
+
+        latest_by_code = {}
+        for series in series_list:
+            if series.code is None:
+                continue
+            current = latest_by_code.get(series.code)
+            if current is None or _release_sort_key(series.release) > _release_sort_key(
+                current.release
+            ):
+                latest_by_code[series.code] = series
+
+        return list(latest_by_code.values())
+
+    def get_indicator_series(self, indicator_code: str) -> IndicatorSeriesMetadata:
+        """
+        Returns grouped series metadata and dimensions for an indicator.
+        """
+        for target in self.get_targets(include_children=True):
+            for indicator in target.indicators or []:
+                if indicator.code == indicator_code:
+                    series_codes = {
+                        series.code for series in indicator.series or [] if series.code is not None
+                    }
+                    dimensions_by_code = {
+                        code: self.get_series_dimensions(code) for code in series_codes
+                    }
+                    return _indicator_series_metadata(indicator, dimensions_by_code)
+
+        raise ValueError(f"indicator code {indicator_code!r} was not found")
+
+    def get_target_series(self, target_code: str) -> TargetSeriesMetadata:
+        """
+        Returns grouped indicator and series metadata for a target.
+        """
+        for target in self.get_targets(include_children=True):
+            if target.code != target_code:
+                continue
+
+            series_codes = {
+                series.code
+                for indicator in target.indicators or []
+                for series in indicator.series or []
+                if series.code is not None
+            }
+            dimensions_by_code = {code: self.get_series_dimensions(code) for code in series_codes}
+            return TargetSeriesMetadata(
+                code=target.code or "",
+                title=target.title,
+                description=target.description,
+                uri=target.uri,
+                indicators=[
+                    _indicator_series_metadata(indicator, dimensions_by_code)
+                    for indicator in target.indicators or []
+                ],
+            )
+
+        raise ValueError(f"target code {target_code!r} was not found")
+
+    def get_geo_areas(self) -> list[ApiGeoArea]:
+        """
+        Returns a list of geographic areas and their M49 codes.
+        """
+        response = self._get("/sdg/GeoArea/List")
+        response.raise_for_status()
+        data = response.json()
+        return [ApiGeoArea(**item) for item in data]
+
+    def get_goals(self) -> list[ApiGoal]:
+        """
+        Fetches all SDG goals.
+        """
+        response = self._get("/sdg/Goal/List")
+        response.raise_for_status()
+        data = response.json()
+        return [ApiGoal(**item) for item in data]
+
+    def get_indicators(self, include_series: bool = True) -> list[ApiTarget]:
+        """
+        Fetches all indicators, optionally including their series.
+        """
+        response = self._get("/sdg/Indicator/List", params={"includechildren": include_series})
+        response.raise_for_status()
+        data = response.json()
+        return [ApiTarget(**item) for item in data]
+
+    def get_concepts(self) -> list[ConceptsMasterData]:
+        """
+        Fetches all concepts.
+        """
+        response = self._get("sdg/SDMXMetadata/GetConceptsMasterList")
+        response.raise_for_status()
+        return [ConceptsMasterData(**item) for item in response.json()]
+
+    def get_sdmx_series(self) -> list[SDMXMetaDataResponse]:
+        """
+        Fetches all SDMX series metadata.
+        """
+        response = self._get("sdg/SDMXMetadata/GetSeries")
+        response.raise_for_status()
+        return [SDMXMetaDataResponse(**item) for item in response.json()]
+
+    def get_series_dimensions(self, series_code: str) -> list[ApiDimension]:
+        """
+        Fetches available disaggregation dimensions for a series.
+        """
+        response = self._get(f"/sdg/Series/{series_code}/Dimensions")
+        response.raise_for_status()
+        return [ApiDimension(**item) for item in response.json()]
+
+    def get_series_data(
+        self,
+        series_codes: Sequence[str],
+        area_code: str | None = None,
+        start_period: str | None = None,
+        end_period: str | None = None,
+        release_code: str | None = None,
+        dimensions: DimensionArgument = "coarsest",
+    ) -> list[dict]:
+        """
+        Pulls actual data observations for given series codes across all pages.
+        Returns a list of dictionaries, making it easy to create a Polars or Pandas DataFrame.
+        """
+        series_codes = _series_code_list(series_codes)
+        params = {"pageSize": 1000}
+        if area_code:
+            params["areaCode"] = area_code
+        if release_code:
+            params["releaseCode"] = release_code
+        time_period_params = _period_query_params(start_period, end_period)
+        if time_period_params == {}:
+            return []
+        if time_period_params is not None:
+            params.update(time_period_params)
+
+        if dimensions == "coarsest":
+            all_observations = []
+            for series_code in series_codes:
+                series_params = {**params, "seriesCode": series_code}
+                coarsest_dimensions = _coarsest_dimension_filters(
+                    self.get_series_dimensions(series_code)
+                )
+                if coarsest_dimensions:
+                    series_params["dimensions"] = _dimension_payload(coarsest_dimensions)
+                all_observations.extend(self._fetch_series_data(series_params))
+            return all_observations
+
+        params["seriesCode"] = ",".join(series_codes)
+        if dimensions != "all":
+            if not isinstance(dimensions, Mapping):
+                raise ValueError('dimensions must be "coarsest", "all", or a mapping')
+            params["dimensions"] = _dimension_payload(dimensions)
+
+        return self._fetch_series_data(params)
+
+    def _fetch_series_data(self, params: dict) -> list[dict]:
+        time_periods = params.get("timePeriod")
+        if isinstance(time_periods, list) and len(time_periods) > 1 and "dimensions" in params:
+            all_observations = []
+            for time_period in time_periods:
+                period_params = {**params, "timePeriod": [time_period]}
+                all_observations.extend(self._fetch_series_data(period_params))
+            return all_observations
+
+        params = {**params, "page": 1}
+        all_observations = []
+
+        while True:
+            # /sdg/Series/Data is often more direct than generic Observation for this
+            response = self._get("/sdg/Series/Data", params=params)
+            response.raise_for_status()
+
+            page_data = response.json()
+            observations = page_data.get("data", [])
+            all_observations.extend(_normalize_observation(item) for item in observations)
+
+            total_pages = page_data.get("totalPages")
+            if total_pages is not None and params["page"] >= int(total_pages):
+                break
+
+            # UNSD may omit totalPages, so fall back to response size.
+            if not observations or len(observations) < params.get("pageSize", 100):
+                break
+
+            params["page"] += 1
+
+        return all_observations

sdgdata-0.1.0/src/sdgdata/debug.py

@@ -0,0 +1,36 @@
+import sys
+
+import httpx
+
+_enabled = False
+
+
+def enable() -> None:
+    """
+    Enables debug query output for all sdgdata clients in this process.
+    """
+    global _enabled
+    _enabled = True
+
+
+def disable() -> None:
+    """
+    Disables debug query output for all sdgdata clients in this process.
+    """
+    global _enabled
+    _enabled = False
+
+
+def is_enabled() -> bool:
+    """
+    Returns whether debug query output is enabled.
+    """
+    return _enabled
+
+
+def print_query(request: httpx.Request) -> None:
+    """
+    Prints the fully constructed request URL when debug mode is enabled.
+    """
+    if _enabled:
+        print(f"sdgdata query: {request.url}", file=sys.stderr)

sdgdata-0.1.0/src/sdgdata/metadata.py

@@ -0,0 +1,28 @@
+from pydantic import BaseModel, Field
+
+from sdgdata.models import ApiDimension
+
+
+class SeriesMetadata(BaseModel):
+    code: str
+    description: str | None = None
+    uri: str | None = None
+    latest_release: str | None = None
+    releases: list[str] = Field(default_factory=list)
+    dimensions: list[ApiDimension] = Field(default_factory=list)
+
+
+class IndicatorSeriesMetadata(BaseModel):
+    code: str
+    description: str | None = None
+    tier: str | None = None
+    uri: str | None = None
+    series: list[SeriesMetadata] = Field(default_factory=list)
+
+
+class TargetSeriesMetadata(BaseModel):
+    code: str
+    title: str | None = None
+    description: str | None = None
+    uri: str | None = None
+    indicators: list[IndicatorSeriesMetadata] = Field(default_factory=list)