sdgdata 0.1.0__py3-none-any.whl

sdgdata/__init__.py

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

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/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/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)

sdgdata/models.py

@@ -0,0 +1,374 @@
+# generated by scripts/generate_models.py
+#   source: data/un-api-openapi.json
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class ApiDisaggregatedDimenions(BaseModel):
+    id: str | None = None
+    goal: int | None = None
+    target: str | None = None
+    indicator: str | None = None
+    seriesCode: str | None = None
+    disaggregatedCategory: str | None = None
+
+
+class ApiOneSeriesMultiArea(BaseModel):
+    indicator: str | None = None
+    seriesCode: str | None = None
+    seriesTitle: str | None = None
+    disaggregationType: str | None = None
+    units: str | None = None
+    countryData: list[ApiCountrywiseData] | None = None
+
+
+class ApiCountrywiseData(BaseModel):
+    geoAreaCode: str | None = None
+    geoAreaName: str | None = None
+    chartColor: str | None = None
+    yearWiseData: list[ApiYearWiseData] | None = None
+
+
+class ApiYearWiseData(BaseModel):
+    year: str | None = None
+    value: str | None = None
+
+
+class ApiMultiSeriesOneArea(BaseModel):
+    geoAreaCode: str | None = None
+    geoAreaName: str | None = None
+    ctSeriesWiseData: list[ApiSeriesData] | None = None
+
+
+class ApiSeriesData(BaseModel):
+    indicator: str | None = None
+    seriesCode: str | None = None
+    seriesTitle: str | None = None
+    disaggregationType: str | None = None
+    units: str | None = None
+    chartColor: str | None = None
+    yearWiseData: list[ApiYearWiseData] | None = None
+
+
+class ApiCompareIndicatorsAcrossCountries(BaseModel):
+    goalId: str | None = None
+    goalName: str | None = None
+    indicators: list[ApiIndicatorPercentage] | None = None
+
+
+class ApiIndicatorPercentage(BaseModel):
+    code: str | None = None
+    description: str | None = None
+    percentage: str | None = None
+
+
+class ApiCountriesAcrossAllGoals(BaseModel):
+    goals: list[SDGGoals] | None = None
+    goalsCountryDetails: list[GoalsCountrywiseData] | None = None
+
+
+class SDGGoals(BaseModel):
+    goalId: int | None = None
+    goalName: str | None = None
+
+
+class GoalsCountrywiseData(BaseModel):
+    geoAreaCode: int | None = None
+    geoAreaName: str | None = None
+    goal1: float | None = None
+    goal2: float | None = None
+    goal3: float | None = None
+    goal4: float | None = None
+    goal5: float | None = None
+    goal6: float | None = None
+    goal7: float | None = None
+    goal8: float | None = None
+    goal9: float | None = None
+    goal10: float | None = None
+    goal11: float | None = None
+    goal12: float | None = None
+    goal13: float | None = None
+    goal14: float | None = None
+    goal15: float | None = None
+    goal16: float | None = None
+    goal17: float | None = None
+
+
+class ApiGeoArea(BaseModel):
+    geoAreaCode: str | None = Field(None, description="geoAreaCode is equivalent to M49")
+    geoAreaName: str | None = Field(
+        None, description="geoArea Name is the offician UN name for that country or region."
+    )
+
+
+class ApiGeoTree(BaseModel):
+    geoAreaCode: int | None = Field(None, description="Gets or Sets code")
+    geoAreaName: str | None = Field(None, description="Gets or Sets name")
+    type: str | None = Field(None, description="Gets or Sets type")
+    children: list[ApiGeoTree] | None = Field(None, description="Gets or Sets children")
+
+
+class ApiGoalData(BaseModel):
+    code: str | None = Field(None, description="Gets or Sets Code")
+    title: str | None = Field(None, description="Gets or Sets Title")
+    description: str | None = Field(None, description="Gets or Sets Description")
+    uri: str | None = Field(None, description="Gets or Sets URI")
+    targets: list[ApiTargetData] | None = Field(None, description="Gets or Sets Targets")
+
+
+class ApiTargetData(BaseModel):
+    code: str | None = Field(None, description="Gets or Sets Code")
+    title: str | None = Field(None, description="Gets or Sets Title")
+    description: str | None = Field(None, description="Gets or Sets Description")
+    URI: str | None = Field(None, description="Gets or Sets URI")
+    indicators: list[ApiIndicatorData] | None = Field(None, description="Gets or Sets Indicators")
+
+
+class ApiIndicatorData(BaseModel):
+    code: str | None = Field(None, description="Gets or Sets Code")
+    description: str | None = Field(None, description="Gets or Sets Description")
+    tier: str | None = Field(None, description="Gets or Sets Tier")
+    uri: str | None = Field(None, description="Gets or Sets URI")
+    series: list[ApiSerieData] | None = Field(None, description="Gets or Sets Series")
+
+
+class ApiSerieData(BaseModel):
+    release: str | None = Field(None, description="Gets or Sets Series")
+    code: str | None = None
+    description: str | None = Field(None, description="Gets or Sets Description")
+    uri: str | None = Field(None, description="Gets or Sets URI")
+    observations: list[ApiObservation] | None = Field(None, description="Gets or Sets attributes")
+
+
+class ApiObservation(BaseModel):
+    goal: list[str] | None = Field(None, description="Gets or Sets Goal")
+    target: list[str] | None = Field(None, description="Gets or Sets Target")
+    indicator: list[str] | None = Field(None, description="Gets or Sets Indicator")
+    series: str | None = Field(None, description="Gets or Sets Series")
+    seriesDescription: str | None = Field(None, description="Gets or Sets Series Description")
+    seriesCount: str | None = Field(None, description="Gets or Sets Series Count")
+    geoAreaCode: str | None = Field(None, description="Gets or Sets geoAreaCode")
+    geoAreaName: str | None = Field(None, description="Gets or Sets geoAreaName")
+    timePeriodStart: float | None = Field(None, description="Gets or Sets timePeriod Start")
+    value: str | None = Field(None, description="Gets or Sets Value")
+    valueType: str | None = Field(None, description="Gets or Sets ValueType")
+    time_detail: str | None = Field(None, description="Gets or Sets TimeDetail")
+    timeCoverage: str | None = Field(None, description="Gets or Sets TimeCoverage")
+    upperBound: str | None = Field(None, description="Gets or Sets UpperBound")
+    lowerBound: str | None = Field(None, description="Gets or Sets LowerBound")
+    basePeriod: str | None = Field(None, description="Gets or Sets BasePeriod")
+    source: str | None = Field(None, description="Gets or Sets Source")
+    geoInfoUrl: str | None = Field(None, description="Gets or Sets GeoInfoUrl")
+    footnotes: list[str] | None = Field(None, description="Gets or Sets Footnotes")
+    attributes: dict[str, str] | None = Field(None, description="Gets or Sets Attributes")
+    dimensions: dict[str, str] | None = Field(None, description="Gets or Sets Dimensions")
+
+
+class ApiGoal(BaseModel):
+    code: str | None = Field(None, description="Gets or Sets Code")
+    title: str | None = Field(None, description="Gets or Sets Title")
+    description: str | None = Field(None, description="Gets or Sets Description")
+    uri: str | None = Field(None, description="Gets or Sets URI")
+    targets: list[ApiTarget] | None = Field(None, description="Gets or Sets Targets")
+
+
+class ApiTarget(BaseModel):
+    goal: str | None = Field(None, description="Gets or Sets Code")
+    code: str | None = Field(None, description="Gets or Sets Code")
+    title: str | None = Field(None, description="Gets or Sets Title")
+    description: str | None = Field(None, description="Gets or Sets Description")
+    uri: str | None = Field(None, description="Gets or Sets URI")
+    indicators: list[ApiIndicator] | None = Field(None, description="Gets or Sets Indicators")
+
+
+class ApiIndicator(BaseModel):
+    goal: str | None = Field(None, description="Gets or Sets Goal")
+    target: str | None = Field(None, description="Gets or Sets Code")
+    code: str | None = Field(None, description="Gets or Sets Code")
+    description: str | None = Field(None, description="Gets or Sets Description")
+    tier: str | None = Field(None, description="Gets or Sets Tier")
+    uri: str | None = Field(None, description="Gets or Sets URI")
+    series: list[ApiSerie] | None = Field(None, description="Gets or Sets Series")
+
+
+class ApiSerie(BaseModel):
+    goal: list[str] | None = Field(None, description="Gets or Sets Goal")
+    target: list[str] | None = Field(None, description="Gets or Sets Target")
+    indicator: list[str] | None = Field(None, description="Gets or Sets Indicator")
+    release: str | None = Field(None, description="Gets or Sets Release")
+    code: str | None = Field(None, description="Gets or Sets Code")
+    description: str | None = Field(None, description="Gets or Sets Description")
+    uri: str | None = Field(None, description="Gets or Sets URI")
+
+
+class ApiDimension(BaseModel):
+    id: str | None = Field(None, description="Gets or Sets id")
+    codes: list[ApiCodeList] | None = Field(None, description="Gets or Sets codeList")
+
+
+class ApiCodeList(BaseModel):
+    code: str | None = Field(None, description="Gets or Sets code")
+    description: str | None = Field(None, description="Gets or Sets code")
+    sdmx: str | None = Field(None, description="Gets or Sets code")
+
+
+class ApiObservationPage(BaseModel):
+    size: int | None = Field(
+        None, description="Gets or Sets Size\r\nThe number of elements in the page"
+    )
+    totalElements: int | None = Field(
+        None, description="Gets or Sets TotalElements\r\nThe total number of elements"
+    )
+    totalPages: int | None = Field(
+        None, description="Gets or Sets totalPages\r\nThe total number of pages"
+    )
+    pageNumber: int | None = Field(
+        None, description="Gets or Sets pageNumber\r\nThe current page number"
+    )
+    attributes: list[ApiDimension] | None = Field(None, description="Gets or Sets attributes")
+    dimensions: list[ApiDimension] | None = Field(None, description="Gets or Sets dimensions")
+    data: list[ApiObservation] | None = Field(None, description="Gets or Sets data")
+
+
+class FileStreamResult(BaseModel):
+    fileStream: Stream | None = None
+    contentType: str | None = None
+    fileDownloadName: str | None = None
+    lastModified: datetime | None = None
+    entityTag: EntityTagHeaderValue | None = None
+
+
+class Stream(BaseModel):
+    canRead: bool | None = None
+    canSeek: bool | None = None
+    canTimeout: bool | None = None
+    canWrite: bool | None = None
+    length: int | None = None
+    position: int | None = None
+    readTimeout: int | None = None
+    writeTimeout: int | None = None
+
+
+class EntityTagHeaderValue(BaseModel):
+    tag: StringSegment | None = None
+    isWeak: bool | None = None
+
+
+class StringSegment(BaseModel):
+    buffer: str | None = None
+    offset: int | None = None
+    length: int | None = None
+    value: str | None = None
+    hasValue: bool | None = None
+
+
+class ApiObservationPivotPage(BaseModel):
+    size: int | None = Field(
+        None, description="Gets or Sets Size\r\nThe number of elements in the page"
+    )
+    totalElements: int | None = Field(
+        None, description="Gets or Sets TotalElements\r\nThe total number of elements"
+    )
+    totalPages: int | None = Field(
+        None, description="Gets or Sets totalPages\r\nThe total number of pages"
+    )
+    pageNumber: int | None = Field(
+        None, description="Gets or Sets pageNumber\r\nThe current page number"
+    )
+    attributes: list[ApiDimension] | None = Field(None, description="Gets or Sets attributes")
+    dimensions: list[ApiDimension] | None = Field(None, description="Gets or Sets dimensions")
+    data: list[ApiObservationPivot] | None = Field(None, description="Gets or Sets data")
+
+
+class ApiObservationPivot(BaseModel):
+    goal: str | None = Field(None, description="Gets or Sets Goal")
+    target: str | None = Field(None, description="Gets or Sets Target")
+    indicator: str | None = Field(None, description="Gets or Sets Indicator")
+    series: str | None = Field(None, description="Gets or Sets Series")
+    seriesDescription: str | None = Field(None, description="Gets or Sets Series")
+    seriesCount: str | None = Field(None, description="Gets or Sets Series")
+    geoAreaCode: str | None = Field(None, description="Gets or Sets geoAreaCode")
+    geoAreaName: str | None = Field(None, description="Gets or Sets geoAreaName")
+    timeCoverage: str | None = Field(None, description="Gets or Sets TimeCoverage")
+    upperBound: str | None = Field(None, description="Gets or Sets UpperBound")
+    lowerBound: str | None = Field(None, description="Gets or Sets LowerBound")
+    basePeriod: str | None = Field(None, description="Gets or Sets BasePeriod")
+    source: str | None = Field(None, description="Gets or Sets Source")
+    geoInfoUrl: str | None = Field(None, description="Gets or Sets GeoInfoUrl")
+    age: str | None = Field(None, description="Gets or Sets age")
+    freq: str | None = Field(None, description="Gets or Sets freq")
+    sex: str | None = Field(None, description="Gets or Sets sex")
+    location: str | None = Field(None, description="Gets or Sets location")
+    units: str | None = Field(None, description="Gets or Sets Units")
+    level_status: str | None = Field(None, description="Gets or Sets level/status")
+    name_of_international_agreement: str | None = Field(
+        None, description="Gets or Sets name of international agreement"
+    )
+    education_level: str | None = Field(None, description="Gets or Sets education level")
+    type_of_product: str | None = Field(None, description="Gets or Sets type of product")
+    type_of_facilities: str | None = Field(None, description="Gets or Sets type of facilities")
+    name_of_international_institution: str | None = Field(
+        None, description="Gets or Sets name of international institution"
+    )
+    type_of_occupation: str | None = Field(None, description="Gets or Sets type of occupation")
+    tariff_regime_status: str | None = Field(None, description="Gets or Sets tariff regime status")
+    mode_of_transportation: str | None = Field(
+        None, description="Gets or Sets mode of transportation"
+    )
+    type_of_mobile_technology: str | None = Field(
+        None, description="Gets or Sets type of mobile technology"
+    )
+    name_of_non_communicable_disease: str | None = Field(
+        None, description="Gets or Sets name of non-communicable disease"
+    )
+    type_of_skill: str | None = Field(None, description="Gets or Sets type of skill")
+    type_of_speed: str | None = Field(None, description="Gets or Sets type of speed")
+    migratory_status: str | None = Field(None, description="Gets or Sets migratory status")
+    disability_status: str | None = Field(None, description="Gets or Sets disability status")
+    hazard_type: str | None = Field(None, description="Gets or Sets hazard type")
+    ihr_capacity: str | None = Field(None, description="Gets or Sets ihr capacity")
+    reporting_type: str | None = Field(None, description="Gets or Sets Units")
+    cities: str | None = Field(None, description="Gets or Sets cities")
+    activity: str | None = Field(None, description="Gets or Sets Activity")
+    policy_domains: str | None = Field(None, description="Gets or Sets Policy Domains")
+    years: str | None = Field(None, description="Gets or Sets years")
+
+
+class SDMXMetaDataResponse(BaseModel):
+    series: str | None = None
+    seriesDesc: str | None = None
+    indicatorDesc: str | None = None
+    conceptId: str | None = None
+    conceptName: str | None = None
+    conceptDesc: str | None = None
+    conceptHTML: str | None = None
+    parentId: str | None = None
+
+
+class ConceptsMasterData(BaseModel):
+    conceptId: str | None = None
+    conceptName: str | None = None
+    parentId: str | None = None
+
+
+class ApiSliceData(BaseModel):
+    series: str | None = Field(None, description="Gets or Sets Series")
+    geoAreaCode: int | None = Field(None, description="Gets or Sets geoAreaCode")
+    geoAreaName: str | None = Field(None, description="Gets or Sets geoAreaName")
+    dimensions: list[dict[str, str]] | None = Field(
+        None, description="Gets or Sets Dimensions for slice data"
+    )
+
+
+class FileResult(BaseModel):
+    contentType: str | None = None
+    fileDownloadName: str | None = None
+    lastModified: datetime | None = None
+    entityTag: EntityTagHeaderValue | None = None
+
+
+ApiGeoTree.model_rebuild()

sdgdata/utilities.py

@@ -0,0 +1,156 @@
+import json
+import re
+from collections.abc import Mapping, Sequence
+from typing import Literal
+
+from sdgdata.models import ApiDimension
+
+_RELEASE_PATTERN = re.compile(r"^(\d{4})\.Q(\d+)\.G\.(\d+)$")
+DimensionMode = Literal["coarsest", "all"]
+DimensionFilters = Mapping[str, str | Sequence[str]]
+DimensionArgument = DimensionMode | DimensionFilters
+
+
+def _series_code_list(series_codes: Sequence[str]) -> list[str]:
+    if isinstance(series_codes, str | bytes):
+        raise TypeError('series_codes must be a sequence of strings, such as ["SERIES_CODE"]')
+    return list(series_codes)
+
+
+def _normalize_singleton_list(value):
+    if isinstance(value, list) and len(value) == 1:
+        return value[0]
+    return value
+
+
+def _normalize_time_period_start(value):
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return value
+
+
+def _normalize_observation(observation: dict) -> dict:
+    normalized = {**observation}
+    for key in ("goal", "target", "indicator"):
+        normalized[key] = _normalize_singleton_list(normalized.get(key))
+    if "timePeriodStart" in normalized:
+        normalized["timePeriodStart"] = _normalize_time_period_start(normalized["timePeriodStart"])
+    return normalized
+
+
+def _release_sort_key(release: str | None) -> tuple[int, int, int]:
+    match = _RELEASE_PATTERN.match(release or "")
+    if match is None:
+        return (-1, -1, -1)
+    return tuple(int(part) for part in match.groups())
+
+
+def _period_value(period: str | None) -> int | None:
+    if period is None:
+        return None
+    return int(period)
+
+
+def _period_query_params(
+    start_period: str | None,
+    end_period: str | None,
+) -> dict[str, list[str]] | None:
+    start = _period_value(start_period)
+    end = _period_value(end_period)
+    if start is None and end is None:
+        return None
+    if end is None:
+        raise ValueError("start_period and end_period must be provided together")
+    if start is None:
+        raise ValueError("start_period and end_period must be provided together")
+    if end < start:
+        return {}
+    return {"timePeriod": [str(period) for period in range(start, end + 1)]}
+
+
+def _dimension_payload(dimensions: DimensionFilters) -> str:
+    payload = []
+    for name, values in dimensions.items():
+        if isinstance(values, str):
+            values = [values]
+        payload.append({"name": name, "values": list(values)})
+    return json.dumps(payload, separators=(",", ":"))
+
+
+def _coarsest_dimension_filters(dimensions: list[ApiDimension]) -> dict[str, str]:
+    filters = {}
+    preferred_codes = {
+        "age": ["ALLAGE"],
+        "sex": ["BOTHSEX"],
+        "location": ["ALLAREA"],
+        "reporting type": ["G", "N", "R"],
+    }
+    total_description_markers = (
+        "total",
+        "all ",
+        "all age",
+        "both",
+        "no break",
+        "no breakdown",
+        "national average",
+    )
+
+    for dimension in dimensions:
+        if dimension.id is None or not dimension.codes:
+            continue
+
+        dimension_id = dimension.id.lower()
+        selected_code = None
+
+        for preferred_code in preferred_codes.get(dimension_id, []):
+            selected_code = next(
+                (code for code in dimension.codes if code.code == preferred_code),
+                None,
+            )
+            if selected_code is not None:
+                break
+
+        if selected_code is None:
+            selected_code = next(
+                (code for code in dimension.codes if code.code == "_T" or code.sdmx == "_T"),
+                None,
+            )
+
+        if selected_code is None:
+            selected_code = next(
+                (
+                    code
+                    for code in dimension.codes
+                    if code.description
+                    and any(
+                        marker in code.description.lower() for marker in total_description_markers
+                    )
+                ),
+                None,
+            )
+
+        if selected_code is None:
+            selected_code = dimension.codes[0]
+
+        if selected_code.code is not None:
+            filters[dimension.id] = selected_code.code
+
+    return filters
+
+
+def _time_series_key(record: dict) -> tuple:
+    dimensions = record.get("dimensions") or {}
+    return (
+        record.get("series"),
+        record.get("geoAreaCode"),
+        tuple(sorted(dimensions.items())),
+    )
+
+
+def is_single_time_series(records: list[dict]) -> bool:
+    """
+    Returns whether records contain exactly one series/area/dimension time series.
+    """
+    if not records:
+        return False
+    return len({_time_series_key(record) for record in records}) == 1

sdgdata-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+sdgdata/__init__.py,sha256=jPwpJcGdDu9MiEe4p-kvscpUz6opshz0e-M66dCeukI,62
+sdgdata/client.py,sha256=c1qiN9qm-FG9sUpTST3rkXqnj-nmfrIvmIlFdLlYa4c,11237
+sdgdata/debug.py,sha256=NMX0GHeFbkpMOKWg_QeGObAtORlAN8_1GJusCjKK8o8,686
+sdgdata/metadata.py,sha256=aIwV3BpLJNJZs-gavUrsS_kA2scF8WPCc1HN0ltyp6c,780
+sdgdata/models.py,sha256=ma1xm1Jwvk-dKYow-MV97vvvNeb9ky-CLS8F26ynhIg,16143
+sdgdata/utilities.py,sha256=CgJP2Xh5xh_ECI2-hviNLDI8LfKHDyqaHqbYG0uIII8,4672
+sdgdata-0.1.0.dist-info/licenses/LICENSE,sha256=76oGFukwtKfS25WTC9Y3ZJrtQmjsB49H1u3Pvq-C3h0,1075
+sdgdata-0.1.0.dist-info/METADATA,sha256=QitqPHPpLy46VhDZu8AVQJjME4HZOttgJESO9TvfhoQ,3753
+sdgdata-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sdgdata-0.1.0.dist-info/top_level.txt,sha256=npcQxoAftbOi1FZqR9FhHOnF-JIrfRnclf2Kzqef_q0,8
+sdgdata-0.1.0.dist-info/RECORD,,

sdgdata-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sdgdata-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+sdgdata