Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,5 @@ dist/*
*.swp
.DS_Store
.env
.venv/
docs/_build/
Empty file added docs/_static/.gitkeep
Empty file.
50 changes: 36 additions & 14 deletions docs/agencies.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,28 +10,50 @@ AgencyClient

The agency client allows access to search and retrieval of agencies via the MuckRock API. The client supports querying, listing, and retrieving specific agencies. Accessed generally as ``client.agencies``.
::

>>> example_agency = client.agencies.retrieve(453)
>>> example_agency
<Agency: 453 - Executive Office of Public Safety and Security>

>>> agency_search_example = client.agencies.list(jurisdiction__id=1)
>>> agency_search_example
<APIResults: [<Agency: 18 - Department of Transitional Assistance>, <Agency: 26 - Office of Consumer Affairs and Business Regulation>, <Agency: 31 - Department of Education>, <Agency: 73 - Massachusetts State Lottery>, <Agency: 118 - Massachusetts Bay Transportation Authority (MBTA)>, <Agency: 123 - State Racing Commission>, <Agency: 131 - Parole Board>, <Agency: 138 - Executive Office of Health and Human Services>, <Agency: 139 - Human Resources Division>, <Agency: 141 - Office of the Comptroller>, <Agency: 146 - Executive Office for Administration and Finance>, <Agency: 154 - Commonwealth Health Insurance Connector Authority>, <Agency: 155 - Division of Insurance>, <Agency: 156 - Office of Medicaid>, <Agency: 159 - Office of Medicaid>, <Agency: 160 - Massachusetts Technology Collaborative>, <Agency: 161 - Executive Office of Housing and Economic Development>, <Agency: 162 - Department of Transportation>, <Agency: 163 - MassDevelopment>, <Agency: 164 - MassDevelopment>, <Agency: 171 - Massachusetts Clean Energy Center>, <Agency: 175 - Department of Revenue>, <Agency: 191 - Elections Division (Secretary of State)>, <Agency: 192 - University of Massachusetts>, <Agency: 193 - University of Massachusetts (Amherst)>, <Agency: 195 - Massachusetts Emergency Management Agency>, <Agency: 196 - University of Massachusetts School of Law>, <Agency: 230 - The Massachusetts Historical Commission>, <Agency: 231 - Department of Youth Services>, <Agency: 257 - Massachusetts Department of Criminal Justice Information Services>, <Agency: 267 - Division of Health Care Finance and Policy>, <Agency: 274 - Massachusetts State Police>, <Agency: 310 - Department of Correction>, <Agency: 330 - Supervisor of Public Records>, <Agency: 331 - Department of Public Safety, Architectural Access Board>, <Agency: 332 - Office of Consumer Affairs and Business Regulation Massachusetts, Consumer Assistance Unit>, <Agency: 410 - Registry of Motor Vehicles>, <Agency: 411 - Massachusetts Commission on Lesbian, Gay, Bisexual, Transgender, Queer and Questioning (LGBTQ) Youth (Commission)>, <Agency: 412 - Department of Children and Families>, <Agency: 432 - Department of Public Safety>, <Agency: 433 - Office of the Governor - Massachusetts>, <Agency: 443 - Inspector General>, <Agency: 452 - Commonwealth Fusion Center>, <Agency: 453 - Executive Office of Public Safety and Security>, <Agency: 480 - Massachusetts Port Authority>, <Agency: 501 - Energy Facilities Siting Board>, <Agency: 508 - Attorney General's Office>, <Agency: 562 - Department of Public Utilities>, <Agency: 651 - Metropolitan Law Enforcement Council (MetroLEC)>, <Agency: 714 - Department of Public Health, Division of Health Care Quality>]>
<APIResults: [<Agency: 18 - Department of Transitional Assistance>, <Agency: 26 - Office of Consumer Affairs and Business Regulation>, <Agency: 31 - Department of Education>, <Agency: 73 - Massachusetts State Lottery>, <Agency: 118 - Massachusetts Bay Transportation Authority (MBTA)>, <Agency: 123 - State Racing Commission>, <Agency: 131 - Parole Board>, <Agency: 138 - Executive Office of Health and Human Services>, <Agency: 139 - Human Resources Division>, <Agency: 141 - Office of the Comptroller>, <Agency: 146 - Executive Office for Administration and Finance>, <Agency: 154 - Commonwealth Health Insurance Connector Authority>, <Agency: 155 - Division of Insurance>, <Agency: 156 - Office of Medicaid>, <Agency: 159 - Office of Medicaid>, <Agency: 160 - Massachusetts Technology Collaborative>, <Agency: 161 - Executive Office of Housing and Economic Development>, <Agency: 162 - Department of Transportation>, <Agency: 163 - MassDevelopment>, <Agency: 164 - MassDevelopment>, <Agency: 171 - Massachusetts Clean Energy Center>, <Agency: 175 - Department of Revenue>, <Agency: 191 - Elections Division (Secretary of State)>, <Agency: 192 - University of Massachusetts>, <Agency: 193 - University of Massachusetts (Amherst)>, <Agency: 195 - Massachusetts Emergency Management Agency>, <Agency: 196 - University of Massachusetts School of Law>, <Agency: 230 - The Massachusetts Historical Commission>, <Agency: 231 - Department of Youth Services>, <Agency: 257 - Massachusetts Department of Criminal Justice Information Services>, <Agency: 267 - Division of Health Care Finance and Policy>, <Agency: 274 - Massachusetts State Police>, <Agency: 310 - Department of Correction>, <Agency: 330 - Supervisor of Public Records>, <Agency: 331 - Department of Public Safety, Architectural Access Board>, <Agency: 332 - Office of Consumer Affairs and Business Regulation Massachusetts, Consumer Assistance Unit>, <Agency: 410 - Registry of Motor Vehicles>, <Agency: 411 - Massachusetts Commission on Lesbian, Gay, Bisexual, Transgender, Queer and Questioning (LGBTQ) Youth (Commission)>, <Agency: 412 - Department of Children and Families>, <Agency: 432 - Department of Public Safety>, <Agency: 433 - Office of the Governor - Massachusetts>, <Agency: 443 - Inspector General>, <Agency: 452 - Commonwealth Fusion Center>, <Agency: 453 - Executive Office of Public Safety and Security>, <Agency: 480 - Massachusetts Port Authority>, <Agency: 501 - Energy Facilities Siting Board>, <Agency: 508 - Attorney General's Office>, <Agency: 562 - Department of Public Utilities>, <Agency: 651 - Metropolitan Law Enforcement Council (MetroLEC)>, <Agency: 714 - Department of Public Health, Division of Health Care Quality>]>

To find all agencies in a state, use the ``state`` filter with the ID of a state jurisdiction. Unlike ``jurisdiction__id``, which only matches agencies directly in that jurisdiction, ``state`` also includes local agencies (such as city and county agencies) within the state.
::

>>> state_agencies = client.agencies.list(state=168)

To search for agencies by keyword, use the ``search`` parameter. It can be combined with other filters such as ``state``.
For example, to find all of the police departments in Illinois you could do:
::

>>> il_police_agencies = client.agencies.list(search="police", state=168)

To filter agencies by type, use the ``type`` parameter. Unlike ``search``, this matches agencies tagged with that type, including ones without the keyword in their name (such as a sheriff's office tagged as Police).
::

>>> il_police_type_agencies = client.agencies.list(type="police", state=168)

.. method:: list(self, **params)

List all agencies with optional filtering by parameters. Filters include:

.. method:: list(self, **params)
- **name**: The agency name. Partial matches are supported.
- **jurisdiction__id**: The ID of the jurisdiction the agency belongs to.
- **state**: The ID of a state jurisdiction. Matches state-level agencies and local agencies within that state.
- **type**: The agency type name (e.g., ``type="police"``).
- **search**: A keyword search across agencies (e.g., ``search="police"``).

List all agencies with optional filtering by parameters. Filters include:
- name: The agency name. Partial matches are supported.
- jurisdiction__id: the ID of the Jurisidiction the agency belongs to.
:param params: Query parameters to filter results (e.g., `jurisdiction`, `name`).
:return: An :class:`APIResults` object containing the list of agencies.
:param params: Query parameters to filter results (e.g., `jurisdiction__id`, `name`, `state`, `type`, `search`).
:return: An :class:`APIResults` object containing the list of agencies.

.. method:: retrieve(self, agency_id)
.. method:: retrieve(self, agency_id)

Retrieve a specific agency by its unique identifier.
Retrieve a specific agency by its unique identifier.

:param agency_id: The unique ID of the agency to retrieve.
:return: A :class:`Agency` object representing the requested agency.
:param agency_id: The unique ID of the agency to retrieve.
:return: A :class:`Agency` object representing the requested agency.


Agency
Expand Down Expand Up @@ -62,7 +84,7 @@ Agency

.. attribute:: exempt

Indicates whether the agency is exempt from records laws
Indicates whether the agency is exempt from records laws.

.. attribute:: types

Expand All @@ -78,8 +100,8 @@ Agency

.. attribute:: parent

The ID of the parent agency
The ID of the parent agency.

.. attribute:: appeal_agency

The ID of the agency to which appeals are directed
The ID of the agency to which appeals are directed.
24 changes: 15 additions & 9 deletions docs/communications.rst
Original file line number Diff line number Diff line change
@@ -1,29 +1,35 @@
Communications
===========
==============

Methods for searching and retrieving FOIA communications.

CommunicationClient
----------------
-------------------
.. class:: muckrock.communications.CommunicationClient

The communication client allows access to search, list, and retrieve individual FOIA communications. Accessed generally as ``clients.communications``
The communication client allows access to search, list, and retrieve individual FOIA communications. Accessed generally as ``client.communications``.
::

>>> comms_list = client.communications.list(foia=14313)
>>> comms_list
<APIResults: [<Communication: 108835 - Communication 108835>, <Communication: 108843 - Communication 108843>, <Communication: 108907 - Communication 108907>, <Communication: 108966 - Communication 108966>, <Communication: 111795 - Communication 111795>, <Communication: 116217 - Communication 116217>, <Communication: 117300 - Communication 117300>, <Communication: 125824 - Communication 125824>, <Communication: 126598 - Communication 126598>, <Communication: 132173 - Communication 132173>, <Communication: 132516 - Communication 132516>, <Communication: 137925 - Communication 137925>, <Communication: 138088 - Communication 138088>, <Communication: 145537 - Communication 145537>, <Communication: 152476 - Communication 152476>, <Communication: 152664 - Communication 152664>, <Communication: 160437 - Communication 160437>, <Communication: 160672 - Communication 160672>, <Communication: 168785 - Communication 168785>, <Communication: 169623 - Communication 169623>, <Communication: 178866 - Communication 178866>, <Communication: 179077 - Communication 179077>, <Communication: 191560 - Communication 191560>, <Communication: 201224 - Communication 201224>, <Communication: 209319 - Communication 209319>, <Communication: 210054 - Communication 210054>, <Communication: 217196 - Communication 217196>, <Communication: 217378 - Communication 217378>, <Communication: 224981 - Communication 224981>, <Communication: 225368 - Communication 225368>, <Communication: 232374 - Communication 232374>, <Communication: 232639 - Communication 232639>, <Communication: 240709 - Communication 240709>, <Communication: 240818 - Communication 240818>, <Communication: 249100 - Communication 249100>, <Communication: 250002 - Communication 250002>, <Communication: 257558 - Communication 257558>, <Communication: 258751 - Communication 258751>, <Communication: 266697 - Communication 266697>, <Communication: 267332 - Communication 267332>, <Communication: 277200 - Communication 277200>, <Communication: 277719 - Communication 277719>, <Communication: 285848 - Communication 285848>, <Communication: 285988 - Communication 285988>, <Communication: 294296 - Communication 294296>, <Communication: 294402 - Communication 294402>, <Communication: 304474 - Communication 304474>, <Communication: 304853 - Communication 304853>, <Communication: 314973 - Communication 314973>, <Communication: 315197 - Communication 315197>]>

To find communications within a date range, use ``min_date`` (on or after) and ``max_date`` (on or before) with dates in ``YYYY-MM-DD`` format. They can be combined with other filters such as ``response``:
::

>>> responses_2024 = client.communications.list(foia=14313, response=True, min_date='2024-01-01', max_date='2024-12-31')

.. method:: list(self, **params)

List all FOIA communications with optional filtering. Available filters include:

- **max_date**: Filter communications before a specific date. Format: YYYY-MM-DD
- **min_date**: Filter communications after a specific date. Format: YYYY-MM-DD
- **max_date**: Filter communications on or before this date. Format: YYYY-MM-DD
- **min_date**: Filter communications on or after this date. Format: YYYY-MM-DD
- **foia**: Filter by the associated FOIA request's ID.
- **status**: Filter by the status of the communication (e.g., `submitted`, `ack`, `processed`, etc.).
- **response**: Filter communications based on whether they are a response (boolean).
- **status**: Filter by the status of the communication (e.g., ``submitted``, ``ack``, ``processed``).
- **response**: Filter by whether the communication is a response (boolean).

:param params: Query parameters to filter results (e.g., `foia`, `max_date`, `response`).
:param params: Query parameters to filter results (e.g., `foia`, `min_date`, `max_date`, `status`, `response`).
:return: An :class:`APIResults` object containing the list of communications.

.. method:: retrieve(self, communication_id)
Expand Down Expand Up @@ -91,7 +97,7 @@ Communication

.. attribute:: status

The status of the communication, such as `submitted`, `ack`, `processed`, `done`, etc.
The status of the communication, such as ``submitted``, ``ack``, ``processed``, ``done``, etc.

.. attribute:: files

Expand Down
5 changes: 3 additions & 2 deletions docs/files.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ FileClient

The file client allows access to search, list, and retrieve individual FOIA files. Accessed generally as ``client.files``.
::

>>> file_list = client.files.list(communication=108907)
>>> file_list
<APIResults: [<File: 30713 - File 30713 - Title: ~WRD000>]>
Expand All @@ -23,7 +24,7 @@ FileClient

- **communication**: Filter by the associated communication's ID.
- **title**: Filter by the file title.
- **doc_id**: Filter by unique identifier for the document (different than the ID of the file).
- **doc_id**: Filter by the unique slug for the file (different than the ID of the file).

:param params: Query parameters to filter results, such as `communication`, `title`, and `doc_id`.
:return: An :class:`APIResults` object containing the list of files.
Expand Down Expand Up @@ -71,7 +72,7 @@ File

.. attribute:: doc_id

Filter by the document identifier assigned to the file.
The unique slug assigned to the file (different than the ID of the file).

.. attribute:: pages

Expand Down
Loading
Loading