The MuckRock API

The MuckRock API, or application programming interface, provides a way to access MuckRock data programmatically. This guide will give you what you need to get up and running.

Rate Limiting

The API (and generally, the entire site) is rate limited to one request per second, however you can burst these requests up to 20 per second for as long as the average runs less than 1 per second over a 20 second period.

Examples

We provide a public GitHub repository of example code that uses the API. This is a collection of simple python scripts that should give an idea of what kind of things are possible. Since it’s public, feel free to fork the repository and make a pull request with your own examples!

For more examples, check out the projects that resulted from the BuzzFeed FOIA hackathon.

Endpoints

The current API endpoint is https://www.muckrock.com/api_v1/. It is accessible without any authentication. Making a query against this top-level address will provide a list of available objects and their endpoints. The current list of available objects includes:

  • jurisdiction
  • agency
  • foia
  • communication
  • question
  • statistics
  • user
  • news

Authentication

Most endpoints are accessible without providing any authentication. To access protected data, like your embargoed requests, you’ll need a request token. Your token can be obtained on the bottom left-hand side of your profile page.

When making a request, the token should be included as an authentication header.

headers = {'Authorization': 'Token %s' % token}

We provide a convenience method for getting and storing your token.

Pagination

Our responses are paginated, with a default of 50 items per page. The number of results per page can be changed by providing a page_size query argument.

Response Formats

By default, requests to endpoints will return an HTML “explorer” view that is very easy to use in a browser, but not-so-much in code. To get JSON-formatted responses, either include the application/json value to the content-type header or include the format=json query argument.

Submitting Requests

FOIA Requests can be filed through our API! This can be done by sending an authenticated POST request to the /foia/ endpoint. The following parameters are available

agency (Int or List of Ints) *Required
Sets the agency for the request, based on the primary key of they agency. You can obtain the agencies key from the agency API. If you supply a list of ints, one request will be created for each agency.
embargo (Bool)
Will embargo this request as private until 30 days after a response is received. You must have a pro or org account to use this feature.
permanent_embargo (Bool)
Will permanently embargo the request. This option implicitly sets embargo. You must have an org account to use this feature.
title (String) *Required
The title of the request
document_request (String)
The documents you are requesting. This will be inserted into the default form language for a request. Either this or full_text must be specified
full_text (String)
The full text of your request. This fully overrides the default text. Either this or document_request must be specified
attachments (List of strings)
A list of publically available URLs for documents to attach to the request. This is limited to 3 attachments. Documents must be a PDF, image, Word Document, HTML or text document.

Filing a request through the API will subtract from your account’s available FOIA request count. If no requests have been purchased, the request will be saved as a draft but not sent. After purchasing more requests from your account page, the draft request can be filed manually. Filing a request without any purchased requests will return a HTTP 402 error.

Questions

Reach out to us on Twitter or by email.