We the People API

The We the People API currently provides read-only access to data within We the People, the White House petitions system. This API provides access to data on all petitions that passed the 150 signature threshold required to become publicly-available on the site. We've also published a gallery of projects leveraging the We the People API, including links to live examples and GitHub repositories.

Bulk Data Download: For those who don't need real time data, we've provided a SQL dump of the same dataset exposed via the API. You can download it here: https://api.whitehouse.gov/v1/downloads/data.sql.zip (203.5 MB, last updated 5/1/2013)

Developers and users leveraging the We the People API should keep the stability of the API's infrastructure and their own applications in mind. Individual users issuing requests in excess of 10 per second will experience degraded performance and may be blocked entirely. Additionally, there is currently a maximum limit of 1000 results per request. Having problems? Contact us.

To learn more about open data and open source projects at the White House, visit WhiteHouse.gov/developers or follow our tech team on Twitter @WHWeb.

petitions

GET /v1/petitions

Returns a list of petitions, individual petitions, and signatures attached to an individual petition. Unsupported non-Latin characters are replaced with an "x". Limits: 10 requests per second. Developers who need historic data on all public petitions should consider using our bulk data download, described above.

Arguments
  • int createdBefore GET (optional)
    Filters results to display items created before specified time. Accepts Unix timestamp. (There's a handy unix timestamp converter here.)
  • int createdAfter GET (optional)
    Filters results to display items created before specified time. Accepts Unix timestamp. (There's a handy unix timestamp converter here.)
  • int createdAt GET (optional)
    Filters results to display items created before specified time. Accepts Unix timestamp. (There's a handy unix timestamp converter here.)
  • int limit GET (optional)
    The maximum number of results that may be returned. E.g., to return results 10-20, an offset of 10 and limit of 10 would be passed. Maximum limit is 1000; developers who need historic data on all public petitions should consider using our bulk data download, described above.
  • int offset GET (optional)
    Offset the returned results by this number. E.g., to return results 10-20, an offset of 10 and limit of 10 would be passed.
  • string title GET (optional)
    Filters results by keyword or phrase in the Title.
  • string body GET (optional)
    Filters results by keyword or phrase in the Body.
  • int signatureThresholdCeiling GET (optional)
    Filters results by maximum Signature Threshold.
  • int signatureThreshold GET (optional)
    Filters results by exact Signature Threshold.
  • int signatureThresholdFloor GET (optional)
    Filters results by minimum Signature Threshold.
  • int signatureCountCeiling GET (optional)
    Filters results by maximum Signature Count.
  • int signatureCount GET (optional)
    Filters results by exact Signature Count.
  • int signatureCountFloor GET (optional)
    Filters results by minimum Signature Count.
  • string url GET (optional)
    Filters results by Petition URL.
  • string status GET (optional)
    Filters results by Status.
  • int responseID GET (optional)
    Filters results by Response ID .
  • int responseAssociationTimeBefore GET (optional)
    Filters results to display items with a Response Assocation before a specified time. Accepts Unix timestamp.
  • int mock GET (optional)
    When set to 1, this will cause the service to return a mock response.
Response Example
{
  "metadata": {
    "executionTime": 0.020001
  },
  "results": [
    {
      "id": "50cb6d2ba9a0b1c52e000017",
      "type": "petition",
      "title": "Immediately address the issue of gun control through the introduction of legislation in Congress.",
      "body": "The goal of this petition is to force the Obama Administration to produce legislation that limits access to guns. While a national dialogue is critical, laws are the only means in which we can reduce the number of people murdered in gun related deaths. Powerful lobbying groups allow the ownership of guns to reach beyond the Constitution's intended purpose of the right to bear arms. Therefore, Congress must act on what is stated law, and face the reality that access to firearms reaches beyond what the Second Amendment intends to achieve. The signatures on this petition represent a collective demand for a bipartisan discussion resulting in a set of laws that regulates how a citizen obtains a gun.",
      "issues": [
        {
          "id": "4",
          "name": "Civil Rights and Liberties"
        },
        {
          "id": "22",
          "name": "Firearms"
        }
      ],
      "signatureThreshold": 25000,
      "signatureCount": 197073,
      "signaturesNeeded": 0,
      "url": "https://petitions.whitehouse.gov/petition/immediately-address-issue-gun-control-through-introduction-legislation-congress/2tgcXzQC",
      "deadline": 1358101035,
      "status": "responded",
      "response": {
        "id": "681",
        "url": "https://petitions.whitehouse.gov/response/message-president-obama-about-your-petition-reducing-gun-violence",
        "associationTime": "1355963976"
      },
      "created": 1355509035
    },
    {
      "id": "alphanumericString",
      "type": "petition",
      "title": "Petition Title",
      "body": "Petition Body.",
      "issues": [
        {
          "id": "4",
          "name": "Civil Rights and Liberties"
        },
        {
          "id": "22",
          "name": "Firearms"
        }
      ],
      "signatureThreshold": 100000,
      "signatureCount": 90000,
      "signaturesNeeded": 10000,
      "url": "https://petitions.whitehouse.gov/petition/petition-title/alphanumericString",
      "deadline": 1363323600,
      "status": "open",
      "response": null,
      "created": 1360908000
    },
    {
      "id": "alphanumericString",
      "type": "petition",
      "title": "Petition Title",
      "body": "Petition Body.",
      "issues": [
        {
          "id": "4",
          "name": "Civil Rights and Liberties"
        },
        {
          "id": "22",
          "name": "Firearms"
        }
      ],
      "signatureThreshold": 100000,
      "signatureCount": 110000,
      "signaturesNeeded": 0,
      "url": "https://petitions.whitehouse.gov/petition/petition-title/alphanumericString",
      "deadline": 1363323600,
      "status": "pending response",
      "response": null,
      "created": 1360908000
    }
  ]
}

GET /v1/petitions/{petition_id}

Returns a petition matching the petition id.

Arguments
  • string URL
    The petition id of the petition to get.
  • int mock GET (optional)
    When set to 1, this will cause the service to return a mock response.
Response Example
{
  "metadata": {
    "executionTime": 0.01
  },
  "results": [
    {
      "id": "50cb6d2ba9a0b1c52e000017",
      "type": "petition",
      "title": "Immediately address the issue of gun control through the introduction of legislation in Congress.",
      "body": "The goal of this petition is to force the Obama Administration to produce legislation that limits access to guns. While a national dialogue is critical, laws are the only means in which we can reduce the number of people murdered in gun related deaths. Powerful lobbying groups allow the ownership of guns to reach beyond the Constitution's intended purpose of the right to bear arms. Therefore, Congress must act on what is stated law, and face the reality that access to firearms reaches beyond what the Second Amendment intends to achieve. The signatures on this petition represent a collective demand for a bipartisan discussion resulting in a set of laws that regulates how a citizen obtains a gun.",
      "issues": [
        {
          "id": "4",
          "name": "Civil Rights and Liberties"
        },
        {
          "id": "22",
          "name": "Firearms"
        }
      ],
      "signatureThreshold": 25000,
      "signatureCount": 197073,
      "signaturesNeeded": 0,
      "url": "https://petitions.whitehouse.gov/petition/immediately-address-issue-gun-control-through-introduction-legislation-congress/2tgcXzQC",
      "deadline": 1358101035,
      "status": "responded",
      "response": {
        "id": "681",
        "url": "https://petitions.whitehouse.gov/response/message-president-obama-about-your-petition-reducing-gun-violence",
        "associationTime": "1355963976"
      },
      "created": 1355509035
    }
  ]
}
Implementation Examples
JavaScript
Thermometer
Display the status of a petition as a thermometer.

GET /v1/petitions/{petition_id}/signatures

Display signatures attached to a petition. Unsupported non-Latin characters are replaced with an "x".

Arguments
  • string URL
    The petition id of the petition whose signatures we are getting.
  • string city GET (optional)
    Filters results by associated city.
  • string state GET (optional)
    Filters results by associated state.
  • int zipcode GET (optional)
    Filters results by associated zipcode.
  • string country GET (optional)
    Filters results by associated country.
  • int createdBefore GET (optional)
    Filters results to display items created before specified time. Accepts Unix timestamp. (There's a handy unix timestamp converter here.)
  • int createdAfter GET (optional)
    Filters results to display items created after specified time. Accepts Unix timestamp. (There's a handy unix timestamp converter here.)
  • int createdAt GET (optional)
    Filters results to display items created before specified time. Accepts Unix timestamp. (There's a handy unix timestamp converter here.)
  • int limit GET (optional)
    The maximum number of results that may be returned. E.g., to return results 10-20, an offset of 10 and limit of 10 would be passed. Maximum limit is 1000; developers who need historic data on all public petitions should consider using our bulk data download, described above.
  • int offset GET (optional)
    Offset the returned results by this number. E.g., to return results 10-20, an offset of 10 and limit of 10 would be passed.
  • int mock GET (optional)
    When set to 1, this will cause the service to return a mock response.
Response Example
{
  "metadata": {
    "resultset": {
      "count": 27899,
      "offset": 0,
      "limit": 16
    },
    "executionTime": 0.040001
  },
  "results": {
    "0": {
      "id": "5017a5ca6889385944000000",
      "type": "signature",
      "name": "DP",
      "zip": "94530",
      "created": 1343727050
    },
    "1": {
      "id": "5017a5ca6889385944000001",
      "type": "signature",
      "name": "BH",
      "zip": "02130",
      "created": 1343727050
    },
    "2": {
      "id": "5017a5ca6889385944000002",
      "type": "signature",
      "name": "NH",
      "zip": "21144",
      "created": 1343727050
    },
    "3": {
      "id": "5017a5ca6889385944000003",
      "type": "signature",
      "name": "NF",
      "zip": "20814",
      "created": 1343727050
    },
    "4": {
      "id": "5017a5ca6889385944000004",
      "type": "signature",
      "name": "MG",
      "zip": "20814",
      "created": 1343727050
    },
    "5": {
      "id": "5017a5ca6889385944000005",
      "type": "signature",
      "name": "DS",
      "zip": "20852",
      "created": 1343727050
    },
    "6": {
      "id": "5017a5ca6889385944000006",
      "type": "signature",
      "name": "BB",
      "zip": "22180",
      "created": 1343727050
    },
    "7": {
      "id": "5017a5ca6889385944000007",
      "type": "signature",
      "name": "AE",
      "zip": "21043",
      "created": 1343727050
    },
    "8": {
      "id": "5017a5ca6889385944000008",
      "type": "signature",
      "name": "PW",
      "zip": "20011",
      "created": 1343727050
    },
    "9": {
      "id": "5017a5ca6889385944000009",
      "type": "signature",
      "name": "CB",
      "zip": "20194",
      "created": 1343727050
    },
    "10": {
      "id": "5017a5ca6889385944000010",
      "type": "signature",
      "name": "JS",
      "zip": "78723",
      "created": 1343727050
    },
    "11": {
      "id": "5017a5ca6889385944000011",
      "type": "signature",
      "name": "MW",
      "zip": "03842",
      "created": 1343727050
    },
    "12": {
      "id": "5017a5ca6889385944000012",
      "type": "signature",
      "name": "JR",
      "zip": "20901",
      "created": 1343727050
    },
    "13": {
      "id": "5017a5ca6889385944000013",
      "type": "signature",
      "name": "IH",
      "zip": "21244",
      "created": 1343727050
    },
    "14": {
      "id": "5017a5ca6889385944000014",
      "type": "signature",
      "name": "MT",
      "zip": "20715",
      "created": 1343727050
    },
    "15": {
      "id": "5017966beab72a8048000015",
      "type": "signature",
      "name": "FT",
      "zip": "22304",
      "created": 1343727050
    }
  }
}