Getting started =============== This tutorial will walk you through the process of installing python-muckrock and making your first requests. Installation ------------ Provided that you have `pip `_ installed, you can install the library like so: :: $ pip install python-muckrock Creating a client ----------------- Before you can interact with MuckRock, you first must import the library and initialize a client to talk with the site on your behalf. :: >>> from muckrock import MuckRock >>> client = MuckRock(USERNAME, PASSWORD) You can also specify a custom uri if you have installed your own version of MuckRock :: >>> client = MuckRock(USERNAME, PASSWORD, base_uri="https://your.muckrock.domain/api/", auth_uri="https://your.account.server.domain/api/") If you need to debug, you can pass a logging level as a parameter to the client when you instantiate. You will need to import logging first. There are several `logging levels `_ depending on your needs. For this example, we will use the DEBUG level. :: >>> import logging >>> client = MuckRock(USERNAME, PASSWORD, loglevel=logging.DEBUG) Searching for requests ----------------------- You can now you use the client to interact with the MuckRock API. A search for requests about recipes would look like this: :: >>> request_list = client.requests.list(search="Recipe") >>> request_list , , , , ]> The response will be a set of requests with each request labelled with its ID (62755 for example), then the request title. The results are paginated, so if there are more than 25 results returned, you can use `.next` and `.previous` to traverse the results. You may view the next 25 results like so: :: >>> request_list.next Retrieving a single request ----------------------- Let's say we want to retrieve a single request (like request 62755 from above).. You may retrieve this single request by its ID like so: :: >>> request_test = client.requests.retrieve(62755) >>> request_test Retrieving your organization ID ----------------------- To file requests using the API, you need to know which organization to file the requests under. The easiest way to find the organization IDs of organizations you belong to is by accessing the user endpoint. :: >>> my_user = client.users.me() >>> my_user >>> my_user.organizations [1, 24695] You may decide which organization to file under depending on which one has available credits remaining. You may retrieve an organization by its ID to help you decide which one to file under like so: :: >>> my_first_org = client.organizations.retrieve(1) >>> my_first_org Searching for agencies ----------------------- Before you can file a request using the MuckRock API, you need to know where to file the request. Similar to the requests endpoint, the agencies endpoint has filters that allow you to find the agencies of interest. You can provide a search term or other filter. Consult the agencies portion of this documentation for more options. Here is an example of how to find agencies that belong to jurisdiction 1 (Massachusetts) :: >>> agency_list = client.agencies.list(jurisdiction__id=1) >>> agency_list , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ]> Filing a single request ----------------------- Filing a single request is similar to filing a multi-request, except that single requests do not go through a review process. Calling create returns the link to your request(s). You may file a single request like so: :: >>> new_request_data = { "title": "Your request title here", "requested_docs": "This is a test FOIA request.", "organization": 1, # You must replace this with the integer of an organization you have access to. "agencies": [248], # Replace this with the ID of the actual agency you plan on filing with. } >>> new_request = client.requests.create(**new_request_data) https://www.muckrock.com/foi/multirequest/your-request-title-here-151010/ Filing a multi-request ----------------------- The only difference between filing a single and multi-request is that you provide multiple agencies. :: >>> new_request_data = { "title": "Your request title here", "requested_docs": "This is a test FOIA request.", "organization": 1 # Replace this with your org id, "agencies": [248, 18529] # Replace this with your list of agencies. } >>> new_request = client.requests.create(**new_request_data) https://www.muckrock.com/foi/multirequest/your-request-title-here-151010/ You may still edit or delete the request before it is filed (30 minutes after creation) on the site. Finding communications and files tied to a request ----------------------- We can find communications and files (to download them for example) tied to a request by first retrieving the request and then using the request object's `get_communications()` method. :: >>> request = client.requests.retrieve(14313) >>> comms_list = request.get_communications() >>> comms_list , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ]> We can then see if any communication has a file by accessing the communication object's `get_files()` method :: >>> all_files = [] >>> for comm in comms_list: files = list(comm.get_files()) if files: # Filters out comms with no actual files all_files.extend(files) >>> print(all_files) >>> [, , , , , , , , , , , , ,...] Now that we have each file we can easily retrieve the link to each file :: >>> for file in all_files: ... print(file.ffile) https://cdn.muckrock.com/foia_files/WRD000_244.jpg https://cdn.muckrock.com/foia_files/WRD345.jpg https://cdn.muckrock.com/foia_files/12-2-14_MR14313_INT_ID1313992-000.pdf https://cdn.muckrock.com/foia_files/2024/02/01/20-00038-FR.pdf https://cdn.muckrock.com/foia_files/2024/02/01/REFERRAL_DETERMINATION.docx etc