Rewiring America’s API offers comprehensive, up-to-date information about electrification incentive programs and eligibility.
We are actively developing the "v1" revision of this API. It currently powers our incentives calculator, and we aim for it to be suitable for inclusion in third-party applications.
The "v0" of this API is still available, but deprecated; we plan to remove it in the near future, and new applications should not use it.
To generate an API key, click on the "Sign In" button. You can also use this link to sign up if needed.
If you have feedback, or if you've stumbled across this page by accident and you'd like to learn more, reach out to us at api@rewiringamerica.org.
Usage of the API is governed by our API Terms of Service (including our API Guidelines and Acceptable Use Policy) and our Privacy Policy.
https://api.rewiringamerica.org
Query and aggregate results of Rewiring America's health impacts modeling data.
Rewiring America's health impacts research models the health and air quality benefits of residential electrification. This endpoint allows users to filter data by county, state, and upgrade options to return health and air quality benefits. It aggregates data based on specified pollutant and health-related metrics and provides the option to disaggregate results by specific housing characteristics enumerated below. Results describe the total annual benefit to the continental US.
Example Python Code
import requests
# Define the API endpoint
url = "https://api.rewiringamerica.org/api/v1/health_impacts/"
# Define the query parameters
params = {
"metrics": "pm25-pri_kg_delta",
"upgrade": "hp_dryer",
"county_fips": "*",
"state": "NY"
}
# Define the headers with correct Authorization scheme
headers = {
"Authorization": "Bearer YOUR TOKEN HERE"
}
# Send the GET request
response = requests.get(url, headers=headers, params=params)
# Check the response status and print the result
if response.status_code == 200:
print("Success:", response.json())
else:
print("Error:", response.status_code, response.text)
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
metrics
A list of pollutant emissions metrics or economic valuations to aggregate.
Valid inputs:
pm25-pri_kg_delta
: Change in primary PM2.5 emissions (kg)nh3_kg_delta
: Change in ammonia emissions (kg)nox_kg_delta
: Change in emissions of oxides of nitrogen (kg)voc_kg_delta
: Change in emissions of volatile organic compounds (kg)so2_kg_delta
: Change in emissions of sulfur dioxide (kg)premature_mortality_incidence_delta
: Avoided premature mortalitypremature_mortality_valuation_dollars_delta
: Avoided societal costs associated with avoided premature mortality (USD)upgrade
A list of upgrades to filter by.
Valid inputs:
hp_dryer
: Heat Pump Dryermed_eff_hp_hers_sizing_no_setback_basic_enclosure
: Medium Efficiency Heat Pump with Basic Insulationhp_water_heater
: Heat Pump Water Heatermed_eff_hp_hers_sizing_no_setback
: Medium Efficiency Heat Pumpelectric_resistance_dryer
: Electric Resistance Dryerstate
A list of two-letter state abbreviations to filter by.
NOTE: An empty state input will yield results for all states, disaggregated by state.
county_fips
A list of three-digit county FIPS codes to filter by or a *
to indicate all counties. A list can be found here. If a specific county FIPS code is input a specific state abbreviation must also be input.
NOTE: The parameter requires the last three digits of the FIPS code, not the first two which correspond to the state.
groupby
A list of housing characteristics by which results can be further disaggregated.
Valid values:
in_sqft_bin
: Group by square footage binsacs_housing_type
: Group by housing type (e.g., single-family, multi-family)in_hvac_cooling_type
: Group by HVAC cooling typebaseline_appliance_fuel
: Group by baseline appliance fuel typeupgrade_option
: Group by the upgrade option applied1
Compute incentives for which the user is eligible, given the criteria in the request parameters.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
zip
Your zip code helps determine the amount of discounts and tax credits you qualify for.
owner_status
Homeowners and renters qualify for different incentives.
homeowner
renter
household_income
Enter your gross income (income before taxes). Include wages and salary plus other forms of income, including pensions, interest, dividends, and rental income. If you are married and file jointly, include your spouse’s income.
tax_filing
Select "Head of Household" if you have a child or relative living with you, and you pay more than half the costs of your home. Select "Joint" if you file your taxes as a married couple.
hoh
joint
married_filing_separately
single
qualifying_widower_with_dependent_child
household_size
Include anyone you live with who you claim as a dependent on your taxes, and your spouse or partner if you file taxes together.
1
List all available incentives, before applying eligibility criteria. Note that there will be duplicates with only subtle differences between eligibility tiers. Use the calculator endpoint to get de-duped incentives.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
1
Compute incentives for which the user is eligible, given the criteria in the request parameters.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
zip
Find incentives that may be available in this ZIP code. Exactly one of this and "address" is required.
address
Find incentives that may be available at this address. Exactly one of this and "zip" is required.
authority_types
Find incentives offered by these types of authorities. If absent, incentives from all types of authorities will be considered.
federal
city
county
state
utility
other
utility
The ID of your utility company, as returned from /api/v1/utilities
. Required if authority_types includes "utility". If absent, no incentives offered by utilities will be returned.
items
Which types of product or service to fetch incentives for. If absent, include incentives for all products and services. Pass multiple values either comma-separated (items=new_electric_vehicle,used_electric_vehicle
), or as the same GET parameter multiple times (items=new_electric_vehicle&items=used_electric_vehicle
), or using empty square bracket notation (items[]=new_electric_vehicle&items[]=used_electric_vehicle
).
air_sealing
air_to_water_heat_pump
attic_or_roof_insulation
basement_insulation
battery_storage_installation
central_air_conditioner
crawlspace_insulation
owner_status
Whether the consumer owns or rents their home.
homeowner
renter
household_income
The consumer's gross income (pre-tax). Include wages and salary plus other forms of income, including pensions, interest, dividends, and rental income. Married taxpayers filing jointly should include their spouse's income.
tax_filing
The status under which the consumer files their federal taxes.
hoh
joint
married_filing_separately
single
qualifying_widower_with_dependent_child
household_size
The consumer's household size for tax purposes. Should include anyone the consumer lives with who they claim as a dependent on their taxes, and their spouse if they file taxes jointly.
language
Optional choice of language for user-visible strings.
en
es
include_beta_states
Option to include states which are in development and not fully launched.
1
Returns the electric utilities that may serve the given location. Because the location is imprecise, and because utility service territories aren't precisely defined, there may be multiple results, including utilities that don't actually serve the given location.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
zip
Find utilities that may serve this ZIP code. Exactly one of this or "address" is required.
address
Find utilities that may serve this address. Exactly one of this or "zip" is required.
language
Optional choice of language for user-visible strings.
en
es
1
For each state and territory (and Washington, DC), return the development status of its state-, utility-, and local-level incentive data. (Note that federal-level incentive data is available regardless of location.)
The response's keys are two-letter state or territory codes, as defined by the US Postal Service. The response includes all 50 states, Washington DC, and the territories of Puerto Rico, Guam, American Samoa, the US Virgin Islands, and the Northern Mariana Islands.
In each key's value, the possible status
properties are:
none
: state, local, and utility (SLU) incentives for the state are not in the API at all.beta
: SLU incentives have not been fully vetted, and will be returned from /api/v1/calculator
only if the include_beta_states
request parameter is true.launched
: SLU incentives are fully vetted and returned in the API.Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
1
Return the OpenAPI spec for this API, in JSON form.
1