bolster.data_sources.niassembly.questions
=========================================

.. py:module:: bolster.data_sources.niassembly.questions

.. autoapi-nested-parse::

   NI Assembly Questions data module.

   Fetches oral and written question data from the NI Assembly AIMS API.
   Questions are indexed by department (using the AIMS OrganisationId) or by
   the tabling MLA (PersonId).

   The ``GetQuestionsByDepartment`` endpoint accepts a numeric ``departmentId``
   which corresponds to the ``OrganisationId`` returned by
   ``organisations.asmx/GetDepartmentListCurrent_JSON``.

   Known department IDs (as of 2026):
       76  DAERA, 78  Education, 79  Economy, 81  Finance,
       82  Health, 84  Infrastructure, 85  Communities,
       86  The Executive Office, 134 Justice

   Update frequency: Real-time.

   .. rubric:: Example

   >>> from bolster.data_sources.niassembly import questions
   >>> df = questions.get_questions_by_department(82)
   >>> len(df) > 100
   True
   >>> "QuestionText" in df.columns
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.niassembly.questions.logger
   bolster.data_sources.niassembly.questions.DEPARTMENT_NAME_TO_ID


Functions
---------

.. autoapisummary::

   bolster.data_sources.niassembly.questions.get_questions_by_department
   bolster.data_sources.niassembly.questions.get_questions_by_member


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

.. py:data:: logger

.. py:data:: DEPARTMENT_NAME_TO_ID
   :type:  dict[str, int]

.. py:function:: get_questions_by_department(department)

   Return all questions directed to a department as a DataFrame.

   :param department: Department name (full or abbreviation) or integer
                      AIMS OrganisationId.  E.g. ``"Department of Health"``, ``"DoH"``,
                      or ``82``.

   :returns: DataFrame with columns including DocumentId, Reference, TabledDate,
             QuestionText, TablerPersonId, TablerName, QOralAnswerRequested.
             Returns an empty DataFrame if no questions are found.

   :raises requests.HTTPError: If the API request fails.
   :raises ValueError: If the department name cannot be resolved.

   .. rubric:: Example

   >>> df = get_questions_by_department("Department of Health")
   >>> len(df) > 100
   True
   >>> "QuestionText" in df.columns
   True


.. py:function:: get_questions_by_member(person_id)

   Return all questions tabled by an MLA as a DataFrame.

   :param person_id: NI Assembly AIMS PersonId for the MLA.

   :returns: DataFrame with columns including DocumentId, Reference, TabledDate,
             QuestionText, DepartmentId, DepartmentName, QOralAnswerRequested.
             Returns an empty DataFrame if no questions are found.

   :raises requests.HTTPError: If the API request fails.

   .. rubric:: Example

   >>> df = get_questions_by_member(5797)
   >>> len(df) >= 0
   True