API Documentation

Learn ▼

Access PolicyEngine's powerful tax-benefit microsimulation engine programmatically

AI & ML API Microsimulation Benefit Access Educational Use Open Source

PolicyEngine REST API

Build tax and benefit policy analysis into your applications with our comprehensive API

Getting Started

PolicyEngine's REST API (https://household.api.policyengine.org) simulates tax-benefit policy outcomes and reform impacts for households. Access to the API requires a Client ID and Client Secret given by PolicyEngine. Use these credentials to request an authentication token, which expires monthly. This token must be passed within the authorization heading of each request you make to the API. For more information or to request your own Client ID, reach out to PolicyEngine at hello@policyengine.org.

Fetch an authentication token

Execute a credentials exchange, using your client ID and client secret to obtain an authentication token. This token must be included within the authorization header of every HTTP request you make to the PolicyEngine API in the format "Bearer YOUR_TOKEN" (including the space). Tokens expire every month for security purposes.

Request

python

import requests

import json

CLIENT_ID = "YOUR_CLIENT_ID"

CLIENT_SECRET = "YOUR_CLIENT_SECRET"

payload = {

"client_id": CLIENT_ID,

"client_secret": CLIENT_SECRET,

"audience": "https://household.api.policyengine.org",

"grant_type": "client_credentials"

}

headers = { "content-type": "application/json" }

auth_response = requests.post("https://policyengine.uk.auth0.com/oauth/token", headers=headers, json=payload)

result = auth_response.json()

print(result["access_token"])

Response

json

{

"access_token": "YOUR_ACCESS_TOKEN",

"token_type": "Bearer"

}

Calculate household-level policy outcomes

Returns household-level policy outcomes. Pass in a household object defining people, groups and any variable values. Then, pass in null values for requested variables - these will be filled in with computed values.

`POST /us/calculate`

Request

python

import requests

url = "https://household.api.policyengine.org/us/calculate"

headers = {

"Authorization": "Bearer YOUR_TOKEN_HERE",

"Content-Type": "application/json",

}

response = requests.post(url, headers=headers, json={

"household": {

"people": {

"parent": {

"age": {

"2023": 30

"employment_income": {

"2023": 20000

}

"child": {

"age": {

"2023": 5

}

"households": {

"household": {

"members": [

"parent",

"child"

]

}

})

print(response.json())

Response

json

{}

Variable and parameter metadata

Access information about all available variables and parameters in the PolicyEngine API. This endpoint returns metadata about all the inputs and outputs that can be used in calculations.