Onlinekommentar Python Client

Python client for accessing the public Onlinekommentar APIs more easily.

This project is not official, associated with, or affiliated with Onlinekommentar. It was developed independently as a convenience wrapper around the publicly documented Onlinekommentar APIs.

Note: The official Onlinekommentar website and API documentation are the actual and authoritative reference for the APIs.

Installation

uv sync

Quick Start

For a tour of the public APIs, see also examples/onlinekommentar_demo.ipynb.

from onlinekommentar import OnlinekommentarClient

with OnlinekommentarClient() as client:
    # List recent published commentaries
    results = client.list_commentaries(language="en", page=1)

    for commentary in results.commentaries[:5]:
        print(commentary.title, commentary.html_link)

    # Search commentaries
    search_results = client.list_commentaries(
        language="de",
        search="universalversammlung",
    )

    # Fetch a specific commentary by API ID
    commentary = client.get_commentary(search_results.commentaries[0].commentary_id)
    print(commentary.title)

    # Access OAI-PMH metadata as XML
    identify_xml = client.identify()
    print(identify_xml[:200])

API Reference

Commentaries

results = client.list_commentaries(
    language="en",          # "en", "de", "fr", "it"; defaults to configured language
    search="data protection",
    legislative_act="2cdeaaed-30b6-416e-a6ca-7eaef78dfd69",
    sort="-date",           # "title", "-title", "date", "-date"
    page=1,
    request_timeout=60.0,   # optional per-call timeout
)

commentary = client.get_commentary("c9f28a48-39a2-42c4-baa8-7024899156b1")

list_commentaries() returns a CommentarySearchResult with parsed Commentary items. get_commentary() returns a single Commentary.

Raw JSON helpers are available when you need fields that are not modeled yet:

raw_page = client.list_commentaries_raw(language="de", search="Datenschutz")
raw_commentary = client.get_commentary_raw("c9f28a48-39a2-42c4-baa8-7024899156b1")

OAI-PMH

The public OAI-PMH endpoint returns XML. The client provides small helpers and returns the XML text unchanged.

identify = client.identify()
formats = client.list_metadata_formats()
sets = client.list_sets()

identifiers = client.list_identifiers(
    metadata_prefix="oai_dc",
    from_date="2026-01-01",
    set_spec="legal_domain:civil-procedure",
)

records = client.list_records(metadata_prefix="oai_openaire")

record = client.get_record(
    identifier="oai:onlinekommentar.ch:commentary:40eb831a-088b-4b27-9fe2-31f049c790a5",
    metadata_prefix="oai_dc",
)

For unsupported or advanced OAI-PMH combinations, use the generic helper:

xml = client.oai(
    verb="ListRecords",
    metadata_prefix="oai_dc",
    resumption_token="token-from-previous-response",
)

Configuration

Runtime defaults are loaded from config.yaml when present. Constructor arguments such as base_url, timeout, rate_limit_delay, and default_language override configured defaults.

onlinekommentar:
  base_url: "https://onlinekommentar.ch"
  timeout: 30.0
  rate_limit_delay: 0.2
  default_language: "en"

client = OnlinekommentarClient(timeout=10.0, rate_limit_delay=0.5, default_language="de")

Typed Models

from onlinekommentar import (
    Commentary,
    CommentarySearchResult,
    LegislativeAct,
    Person,
)

The client models stable high-use shapes and preserves unknown fields in each model's raw attribute. Raw JSON helpers are available for consumers that need exact API payloads.

Scope

This package covers the public routes documented on the Onlinekommentar API page:

• GET /api/commentaries
• GET /api/commentaries/{id}
• GET /oai with OAI-PMH verbs Identify, ListMetadataFormats, ListSets, ListIdentifiers, ListRecords, and GetRecord

The client does not scrape website pages and does not cover private or undocumented routes.

Fair Use

This independent client accesses public Onlinekommentar endpoints.

Important

Please be kind to the server, keep rate limiting enabled for batch work, mention Onlinekommentar as the data source when appropriate, and avoid sending confidential or personal data to public endpoints. Also consider contributing to Onlinekommentar.

Development

uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -v

License

This Python client is licensed under the MIT License.

The MIT License applies only to this client code. It does not apply to Onlinekommentar data, API content, or other source materials returned by the service. For data and content licensing details, consult Onlinekommentar and the respective original data sources.