bolster.data_sources.nisra.pxstat
=================================

.. py:module:: bolster.data_sources.nisra.pxstat

.. autoapi-nested-parse::

   NISRA PxStat API client.

   Provides access to the NISRA open data API at https://data.nisra.gov.uk/,
   powered by the PxStat platform (https://github.com/CSOIreland/PxStat).

   The API is publicly accessible without authentication and has no observed
   rate limits, making it a more reliable alternative to scraping Excel files
   from publication pages.

   API endpoint pattern::

       GET https://ws-data.nisra.gov.uk/public/api.restful/
           PxStat.Data.Cube_API.ReadDataset/{MATRIX}/CSV/1.0/en

   CSV responses include a UTF-8 BOM — always decode with ``utf-8-sig``.

   Example::

       >>> from bolster.data_sources.nisra.pxstat import read_dataset
       >>> df = read_dataset("WDTHS")
       >>> "VALUE" in df.columns
       True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.pxstat.logger


Exceptions
----------

.. autoapisummary::

   bolster.data_sources.nisra.pxstat.PxStatError


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.pxstat.read_dataset


Module Contents
---------------

.. py:data:: logger

.. py:exception:: PxStatError

   Bases: :py:obj:`Exception`


   Raised when the PxStat API returns an unexpected response.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: read_dataset(matrix, timeout = 30)

   Fetch a dataset from the NISRA PxStat API as a DataFrame.

   :param matrix: Dataset matrix code (e.g. ``"WDTHS"`` for weekly deaths).
   :param timeout: HTTP request timeout in seconds.

   :returns: DataFrame with raw API columns. The ``VALUE`` column contains the
             numeric values; all other columns are dimension labels and codes.

   :raises PxStatError: If the API returns a non-200 response.

   .. rubric:: Example

   >>> df = read_dataset("WDTHS")
   >>> "VALUE" in df.columns
   True