Featured APIs 💸 Incentives — comprehensive, up-to-date information about electrification incentive programs and eligibility. Serves 100,000s of users in our calculator and available to embed on your site. 😷 Health Impacts — models the health and air quality benefits of residential electrification. 🏡 Residential Electrification Model — predictions of the effects of residential upgrades based on home address and current heating fuel.
Get an API key Visit this link to create a new account, sign in to our documentation site, and get an API key. Usage of the API is free, subject to acceptance of our API Terms of Service (including Acceptable Use Policy) and Privacy Policy.
Talk to us We welcome feedback, suggestions, and questions via email to api@rewiringamerica.org.
https://api.rewiringamerica.orgCompute 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
gas_utility
other
utility
The ID of your electric utility company, as returned from /api/v1/utilities. Required if authority_types includes "utility". If absent, no incentives offered by electric utilities will be returned.
gas_utility
The ID of your gas utility company, as returned from /api/v1/utilities, or the special string none indicating that you do not have gas service. A value other than none is required if authority_types includes "gas_utility". If this parameter is absent or none, no incentives offered by gas utilities will be returned. In some jurisdictions, your gas utility can affect your eligibility for incentives offered by other authorities; in such cases, if this parameter is absent, incentives with gas-utility-dependent eligibility will not 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
cool_roof
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 taxes. If this parameter is absent, incentives whose eligibility depends on tax filing status will not be included in the results.
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 electric and gas 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
Returns all incentive programs by location and optionally, utility
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 programs that may be available in this ZIP code. Exactly one of this and "address" is required.
address
Find programs that may be available at this address. Exactly one of this and "zip" is required.
authority_types
Find programs offered by these types of authorities. If absent, programs from all types of authorities will be considered.
federal
city
county
state
utility
gas_utility
other
utility
The ID of your electric utility company, as returned from /api/v1/utilities. Required if authority_types includes "utility". If absent, no programs offered by electric utilities will be returned.
gas_utility
The ID of your gas utility company, as returned from /api/v1/utilities, or the special string none indicating that you do not have gas service. A value other than none is required if authority_types includes "gas_utility". If this parameter is absent or none, no programs offered by gas utilities will be returned. In some jurisdictions, your gas utility can affect your eligibility for programs offered by other authorities; in such cases, if this parameter is absent, programs with gas-utility-dependent eligibility will not be returned.
language
Optional choice of language for user-visible strings.
en
es
1
Predict a user's annual savings using the Residential Electrification Model.
This API makes predictions of the energy, emissions, and energy bill changes for an existing home based on the upgrade type, the address of the home being upgraded, and the current heating fuel.
Using the provided address, we first query 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.
The response JSON is a dictionary with three components:
fuel_results: This is a dictionary of the main results from the model, one for each fuel type: electricity, fuel_oil, natural_gas, propane, total (for the total of all the others).rates: A summary of the rates used to calculate the annual cost in dollars for each fuel. These vary from region to region based local fuel costs.emissions_factors: A summary of the local emissions factors used to calculate annual emissions. Electricity emissions vary from region to region based on how electricity is generated.
Within the fuel_results subsection for each of the fuel types, there are three components:
baseline: the annual usage of the fuel before the upgrade across all end uses (e.g., heating, cooling, water heating, drying, cooking).upgrade: the annual usage of the fuel after the upgrade across all end uses.delta: the change in usage of the fuel across all end uses.Inside those three, there are parallel structures with statistics for the energy consumption for each fuel, as well as the emissions and cost incurred by the consumption of each fuel. The electricity emissions factors are long run marginal emissions rates assuming a 95% decarbonized grid by 2050.
The emissions and costs are computed with the rates and emissions_factors data mentioned above, where the costs reflect the annual costs from both volumetric charges and fixed charges. Note that the fixed charges are based on the presence of the given fuel in the baseline scenario, and not assumed to change in the upgrade scenario.
All of the statistics are for a full typical weather year. The units for each of the statistics are also provided and are as appropriate for the fuel, emissions, or cost.
If baseline is specified as the upgrade in the request, fuel_results will exclude upgrade and delta since baseline represents the home's current state without any upgrades.
A note on statistics: For each value we provide statistics for, we provide a mean, a median, and the 20th and 80th percentile values over all the set of sample homes in the Monte Carlo simulation. It is important to note that the statistics are taken over the distribution of the values they represent. This means, for example, that the median electricity usage before the upgrade, the median electricity usage after the upgrade, and the median change of electricity usage might all be from the same modeled home. So adding the median change to the median usage before the upgrade might not produce the number reported as the median usage after the upgrade.
Note that because we are modeling whole home energy consumption over a set of building samples, and the building set contains homes with a variety of fuels for the non-heating appliances, you may see consumption of fuels other than the passed heating fuel, particularly for the mean.
Demonstrations
There are two sample Python notebooks that demonstrate the API in action.
There are also examples showing how to integrate the REM API into a web site. See the full list here.
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
upgrade
The upgrade whose effects we want to analyze. Supported values are as follows:
baseline: Baseline building with no upgrades applied.combination__all_electric__hvac_seer24_hspf13__weatherization: A whole-home upgrade including a high efficiency air source heat pump for the home’s HVAC system, basic weatherization, a heat pump water heater, a heat pump dryer, and an induction stove. HVAC heat pump is SEER 24, HSPF 13 for ducted systems; SEER 29.3, HSPF 14 for ductless systems, heat pump water heater is UEF 3.35-3.45, and heat pump dryer is Combined Energy Factor (CEF) 5.2. Additional details can be found in measure package 9 (on page 9) of this document.combination__hvac_seer18_hspf10__weatherization: A medium-efficiency heat pump upgrade for the home's HVAC system, plus a basic weatherization upgrade. The heat pump is SEER 18, HSPF 10 for ducted systems; SEER 18, HSPF 10.5 for ductless systems. The nominal capacity is sized equal to the larger of heating/cooling design loads, and the heating and cooling are modeled without setpoint setbacks. The basic weatherization component of this upgrade includes attic floor insulation, air sealing, duct sealing, and drill-and-fill insulation. Attic floor insulation levels are upgraded for compliance with IECC-Residential 2021 and range from R-30 to R-60 depending on climate zone. Attic floor insulation only applies to dwelling units with vented attics. Air sealing is performed to reduce ACH50 by 30%, duct sealing is performed to reduce duct leakage to 10%, and a drill-and-fill insulation level of R-13 is applied to uninsulated wood stud walls. Additional details can be found in measure package 1 (on page 4) of this document.hvac__heat_pump_seer15_hspf9: A relatively-low efficiency air source heat pump upgrade for the home’s HVAC system. Heat pump is SEER 15, HSPF 9 for both ducted and ductless systems.Additional details can be found in measure package 3 (on page 5) of this document.hvac__heat_pump_seer18_hspf10: A medium-efficiency heat pump upgrade for the home's HVAC system. SEER 18, HSPF 10 for ducted systems; SEER 18, HSPF 10.5 for ductless systems. The nominal capacity is sized equal to the larger of heating/cooling design loads, and the heating and cooling are modeled without setpoint setbacks.hvac__heat_pump_seer24_hspf13: A high efficiency air source heat pump upgrade for the home’s HVAC system. Heat pump is SEER 24, HSPF 13 for ducted systems; SEER 29.3, HSPF 14 for ductless systems. Additional details can be found in measure package 4 (on page 6) of this document.weatherization__insulation_air_duct_sealing: A basic weatherization upgrade for the home. Measures include attic floor insulation, air sealing, duct sealing, and drill-and-fill insulation. Attic floor insulation levels are upgraded for compliance with IECC-Residential 2021 and range from R-30 to R-60 depending on climate zone. Attic floor insulation only applies to dwelling units with vented attics. Air sealing is performed to reduce ACH50 by 30%, duct sealing is performed to reduce duct leakage to 10%, and a drill-and-fill insulation level of R-13 is applied to uninsulated wood stud walls. Additional details can be found in measure package 1 (on page 4) of this document.baseline
weatherization__insulation_air_duct_sealing
hvac__heat_pump_seer15_hspf9
hvac__heat_pump_seer24_hspf13
combination__all_electric__hvac_seer24_hspf13__weatherization
hvac__heat_pump_seer18_hspf10
combination__hvac_seer18_hspf10__weatherization
address
The full address for a location including street number and name, city, state, and zip code.
heating_fuel
The heating fuel used in the home before the upgrade. Supported values are as follows:
electricity: the home is currently heated with electric heating, such as
electric resistance heating or a heat pump.natural_gas: The home is currently heated with natural gas.fuel_oil: The home is currently heated with fuel oil.propane: The home is currently heated with propane.electricity
fuel_oil
natural_gas
propane
1
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.
Read the companion report.
For examples of how the API can be called, see this sample notebook in GitHub.
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
One or more metrics describing air pollution and premature mortality impacts of residential electrification. The air pollution impacts describe the changes in annual emissions of fine particulates, ammonia, nitrogen oxides, volatile organic compounds, and sulfur dioxide associated with a given home electrification upgrade. Exposure to these pollutants are implicated in a variety of adverse health outcomes, including asthma attacks, upper respiratory diseases, and premature mortality. The premature mortality impacts include changes in the annual incidence of premature mortality associated with a given home electrification upgrade as well as its dollar valuation.
Supported values are as follows:
ammonia: Avoided emissions of ammonia.avoided_premature_mortality_incidence: Avoided premature mortality due to improved outdoor air quality.avoided_premature_mortality_valuation: Economic valuation of avoided premature mortality.fine_particulate_matter: Avoided emissions of fine particulate matter (PM 2.5), a pollutant heavily implicatedin adverse health effects including premature mortality.nitrogen_oxides: Avoided emissions of nitrogen oxides, most associated with methane gas combustion.sulfur_dioxide: Avoided emissions of sulfur dioxide.volatile_organic_compounds: Avoided emissions of volatile organic compounds.upgrade
One or more home electrification upgrade options. A home electrification upgrade replaces a fossil fuel-powered or less efficient electric appliance with a high-efficiency electric appliance. Options include air source heat pumps, air source heat pumps with an insulation package, heat pump water heaters, and heat pump dryers.
Supported values are as follows (click for additional details) on each upgrade:
state_fips
One or more states specified using two-digit FIPS codes. A list can be found here. If absent, health impacts for all states will be returned. '*' will also return all states. Alaska and Hawaii are not included; DC is included.
county_fips
One or more counties specified using three-digit FIPS codes. A list can be found here. A state must be specified to return specific counties. '*' will return all counties in a given state if the state is specified. If absent, results will be returned at the state level.
group_by
Housing characteristics by which results should be disaggregated. Housing characteristics include binned square footage, housing type as defined by the American Community Survey (Variable B25024), the type of cooling system present pre-home electrification upgrade, and the fuel powering the appliance pre-home electrification upgrade. Results may also be disaggregated by upgrade option if multiple upgrade options were chosen.
Supported values are as follows:
house_size_square_feet_binned: Binned housing size in square feet.housing_type: Single- vs. multi-family.cooling_type: Type of cooling system.baseline_appliance_fuel: Baseline appliance fuel (methane gas, propane, etc.).upgrade_option: Electrification upgrade option (see upgrade parameter).1
{
"metrics": [
"avoided_premature_mortality_incidence"
],
"upgrade": [
"hvac__heat_pump_seer18_hspf10"
],
"state_fips": [
"55"
]
}Return the OpenAPI spec for this API, in JSON form.
1