Rewiring America API
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.orgAuthentication
Retired Incentives
(Deprecated) Find eligible incentives
Compute incentives for which the user is eligible, given the criteria in the request parameters.
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Query Parameters
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.
Possible Enum Values
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.
Possible Enum Values
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
(Deprecated) List all incentives
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.
Headers
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
Incentives
Find eligible incentives
Compute incentives for which the user is eligible, given the criteria in the request parameters.
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Query Parameters
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.
Possible Enum Values
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).
Possible Enum Values
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.
Possible Enum Values
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.
Possible Enum Values
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.
Possible Enum Values
en
es
include_beta_states
Option to include states which are in development and not fully launched.
1
Find utilities by location
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.
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Query Parameters
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.
Possible Enum Values
en
es
1
Get state rollout status
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/calculatoronly if theinclude_beta_statesrequest parameter is true.launched: SLU incentives are fully vetted and returned in the API.
Headers
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
Residential Electrification Model
(Preview) Get By Address
Available in Preview Mode. Please reach out to Rewiring America at datascience@rewiringamerica.org for access.
Predict a user's savings using the Residential Electrification Model. This API makes predictions of the effects of an upgrade based on the address of the home being upgraded, and the current heating fuel.
Using the provided address, it first queries a large database of home properties that Rewiring America has assembled, which contains data such as home age, size, construction material, and much more. We don't know all of the properties needed to get a good estimate of energy consumption, so we perform a Monte Carlo simulation over a sample homes chosen from a conditional probability distribution based the properties that we do know. We then estimate the energy consumption for each sample building by running inference using a Machine Learning based surrogate model, trained on EnergyPlus simulations.
See API Responses for a detailed description of a successful response.
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Query Parameters
upgrade
The upgrade whose effects we want to analyze. Supported values are as follows:
basic_enclosure: A basic weatherization upgrade for the home as described in measure package 1 (on page 4) of this document.min_eff_hp_elec_backup: A relatively-low efficiency heat pump upgrade for the home’s HVAC system as described in measure package 3 (on page 5) of this document.high_eff_hp_elec_backup: A high efficiency heat pump upgrade for the home’s HVAC system as described in measure package 4 (on page 6) of this document.whole_home_electric_max_eff_basic_enclosure: A whole-home upgrade including a high efficiency heat pump for the home’s HVAC system, basic weatherization, a heat pump water heater, a heat pump dryer, and an induction stove as described in measure package 9 (on page 9) of this document.med_eff_hp_hers_sizing_no_setback: A medium-efficiency heat pump upgrade for the home's HVAC system. Rewiring America simulated this upgrade using the same tools NREL uses for ResStock.med_eff_hp_hers_sizing_no_setback_basic_enclosure: A custom upgrade based on a medium-efficiency heat pump and basic weatherization upgrade for the home. Rewiring America simulated this upgrade using the same tools NREL uses for ResStock.
Possible Enum Values
basic_enclosure
min_eff_hp_elec_backup
high_eff_hp_elec_backup
whole_home_electric_max_eff_basic_enclosure
med_eff_hp_hers_sizing_no_setback
med_eff_hp_hers_sizing_no_setback_basic_enclosure
address
The address of the home being upgraded.
heating_fuel
The heating fuel used in the home before the upgrade. Supported values are as follows:
electricity: the home was heated with electric heating, such as baseboard heating, an electric boiler, or an electric furnace.natural_gas: The home was heated with a natural gas furnace.fuel_oil: The home was heated with a fuel oil boiler or furnace.propane: The home was heated with a propane furnace.
Possible Enum Values
electricity
fuel_oil
natural_gas
propane
1
Electrification Tools
Health Impacts of Electrification
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)
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Request Body
metricsThe metric or metrics to report data on.
upgradestatecounty_fipsgroupby1
{
"metrics": "premature_mortality_incidence_delta",
"upgrade": "med_eff_hp_hers_sizing_no_setback",
"state": "WI"
}OpenAPI spec
Return the OpenAPI spec for this API, in JSON form.
1