Metadata-Version: 2.4
Name: parsimony-destatis
Version: 0.0.1
Summary: Destatis (German federal statistics) connector for the parsimony framework
Project-URL: Homepage, https://www.destatis.de
Project-URL: Repository, https://github.com/ockham-sh/parsimony-connectors
Project-URL: Issues, https://github.com/ockham-sh/parsimony-connectors/issues
Author-email: "Ockham.sh" <team@ockham.sh>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: connectors,data,destatis,finance,parsimony
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pandas<3,>=2.3.0
Requires-Dist: parsimony-core[catalog]>=0.0.1
Requires-Dist: parsimony-shared>=0.0.1
Requires-Dist: pydantic<3,>=2.11.1
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.15.10; extra == 'dev'
Description-Content-Type: text/markdown

# parsimony-destatis

Destatis (German Federal Statistical Office) connector — fetches and enumerates tables from the public GENESIS-Online REST API.

Part of the [parsimony-connectors](https://github.com/ockham-sh/parsimony-connectors) monorepo. Distributed standalone on PyPI as `parsimony-destatis`.

## Connectors

| Name | Kind | Description |
|---|---|---|
| `destatis_fetch` | fetch | Fetch a GENESIS table by code (e.g. `61111-0001`), with optional `start_year` / `end_year`. JSON-stat 2.0 is parsed into long-format rows; German month/quarter labels are normalized to ISO dates. |
| `enumerate_destatis` | enumerator | Enumerate GENESIS statistics and their tables (catalog indexing) by crawling `/statistics`, `/statistics/{code}/information`, and `/statistics/{code}/tables`. |
| `destatis_search` | tool | Semantic-search the published Destatis catalog and map a natural-language query to a table code (feed it to `destatis_fetch(name=...)`). |

## Coverage

The keyless GENESIS-Online REST API exposes **3,009 predefined tables across 331 statistics**
(prices, population, national accounts, labour, foreign trade, production, transport, health,
environment, earnings, …). `enumerate_destatis` walks the authoritative path — `/statistics`
then a per-statistic `/tables` fan-out — which is lossless (every statistic's table list comes
back in full, no pagination cap, no table shared across statistics), so the catalog contains
every fetchable table. Each table is itself multi-dimensional: `destatis_fetch` returns one row
per (classification combination × period), with the classification dimensions preserved as
columns. Time is parsed from the JSON-stat period keys (annual, monthly, quarterly, semester,
reference-date, school-year — all normalized to ISO dates).

The multidimensional **cube / custom-table** power-user surface of classic GENESIS is **not**
part of this keyless API (it belonged to the retired registration-gated webservice) and is out
of scope.

## Install

```bash
pip install parsimony-destatis
```

Pulls in `parsimony-core>=0.7,<0.8` automatically. Verify discovery:

```bash
python -c "from parsimony import discover; print([p.name for p in discover.iter_providers()])"
```

## Configuration

**No credentials required.** GENESIS-Online allows anonymous access — there is no API key, username, or password to set.

The only optional setting is the catalog-snapshot URL used by `destatis_search`:

```bash
export PARSIMONY_DESTATIS_CATALOG_URL="hf://your-org/destatis"   # optional; overrides the default snapshot
```

## Quick start

```python
from parsimony_destatis import CONNECTORS

result = CONNECTORS["destatis_fetch"](name="61111-0001")
print(result.data.head())
```

For multi-plugin composition:

```python
from parsimony import discover
connectors = discover.load_all()
```

## Provider

- Homepage: https://www.destatis.de
- GENESIS-Online API: https://genesis.destatis.de/genesis/api/rest

## License

See [LICENSE](./LICENSE).
