Houses of the Oireachtas Open Data API - Python SDK

A modern, lightweight Python client SDK for retrieving and querying open parliament data from the national parliament of Ireland (Houses of the Oireachtas).

📖 Full Documentation: The comprehensive interactive documentation built with MkDocs is available on GitHub Pages: https://irishsmurf.github.io/OireachtasAPI/

This client SDK makes metadata queries easy, allowing you to discover and locate specific official documents, bills, members, votes (divisions), and debates. Output formats point directly to XML/PDF datasets hosted at data.oireachtas.ie.

🚀 Key Features

• Modern Python 3 Support: Fully compatible with Python 3.8+ (legacy Python 2 support has been dropped).
• Fully Tested: Upgraded to use pytest with a complete suite of unit (mocked) and integration (live API) tests.
• Open Access: Works out of the box with the public Oireachtas API endpoints (no authentication tokens required).
• Automated CI/CD: GitHub Actions verify compatibility on every push and automatically build & publish new GitHub Releases when tags are created.

🛠 Installation

Installing via PyPI

You can install the package directly from PyPI:

pip install oireachtas-api

Installing directly from GitHub

To install the latest development version directly from GitHub:

pip install git+https://github.com/Irishsmurf/OireachtasAPI.git

Local Development Setup

To clone the repository and install it in editable mode with development dependencies:

# Clone the repository
git clone https://github.com/Irishsmurf/OireachtasAPI.git
cd OireachtasAPI

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install requirements
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt -r test-requirements.txt
pip install -e .

💡 Quick Start Example

This code demonstrates how to retrieve the 5 most recent active Constituencies:

import oireachtas_api
from pprint import pprint

# 1. Initialize the simplified client
client = oireachtas_api.Client()

try:
    # 2. Query constituencies (returns standard Python list/dict)
    response = client.constituencies(limit=5)
    
    # 3. Print the API response
    print("--- Oireachtas Constituencies ---")
    pprint(response)
except oireachtas_api.ApiException as e:
    print(f"Failed to query constituencies: {e}")

📂 Core API Reference

All requests call the live API endpoint: https://api.oireachtas.ie/v1.

Simplified Unified Client

The Client class consolidates all endpoints into a single wrapper. Method calls return standard Python dictionaries and lists, eliminating the need to interact with verbose auto-generated model objects:

import oireachtas_api

client = oireachtas_api.Client()

# Retrieve constituencies
constituencies = client.constituencies(limit=5)

# Access member information
members = client.members(limit=10)

Note: The legacy individual service API classes (ConstituenciesApi, MembersApi, etc.) and data models are still exported for backward compatibility.

🧪 Testing Guide

We use pytest for unit and integration tests.

1. Isolated Unit Tests (Mocked Network)

To run local test stubs using mock API responses (extremely fast, offline-safe):

pytest -m "not integration"

2. Live Integration Tests

To verify compatibility against the real, live Oireachtas API endpoints:

pytest -m "integration"

3. Run the Whole Test Suite

To run all tests:

pytest

🏷 Release Automation

This project tracks official releases automatically:

1. Ensure your version code is up to date in setup.py.
2. Commit your changes and tag the master branch:

   git tag v2.0.0
   git push origin v2.0.0
   

3. The Release Workflow will automatically build the package wheels, publish a GitHub Release with build assets attached, and publish the release to PyPI using OIDC Trusted Publishing.

📬 Contact & Support

• Official API Portal: beta.oireachtas.ie/en/open-data
• Email: open.data@oireachtas.ie