API Responses
Find eligible incentives
Endpoint: GET /api/v1/calculator
Compute incentives for which the user is eligible, given the criteria in the request parameters.
Type: object
is_under_80_ami
Type: boolean
Whether the given household income is below the "80% of Area Median Income" level for the given household size and location.
is_under_150_ami
Type: boolean
Whether the given household income is below the "150% of Area Median Income" level for the given household size and location.
is_over_150_ami
Type: boolean
Whether the given household income is above the "150% of Area Median Income" level for the given household size and location.
authorities
Type: dictionary
Information on the entities (government agencies, companies, other organizations) that offer incentives in this result set.
name
Type: string
logo
Type: object
| Property | Type | Description |
|---|---|---|
src | string | The URL to fetch the image from. |
width | number | The image's width in pixels. |
height | number | The image's height in pixels. |
coverage
Type: object
Which sub-national sets of incentives were considered for eligibility.
| Property | Type | Description |
|---|---|---|
state | string | Two-letter state code. Determined from the "location" request parameter. |
utility | string | Utility ID, as passed in the "utility" request parameter. |
location
Type: object
The computed location of the request's "zip" or "address" parameter.
| Property | Type | Description |
|---|---|---|
state | string | The two-letter abbreviation for the state, district, or territory of the location submitted in the request. |
city | string | The city name as determined by looking up the ZIP code in our database. |
county | string | The county name as determined by looking up the ZIP code in our database. |
data_partners
Type: dictionary
Information on organizations that assist in collecting, verifying, and maintaining incentive data included in this result set.
name
Type: string
logo
Type: object
| Property | Type | Description |
|---|---|---|
src | string | The URL to fetch the image from. |
width | number | The image's width in pixels. |
height | number | The image's height in pixels. |
incentives
Type: array
payment_methods
Type: array
How a consumer receives value from this incentive.
rebate: a post-purchase rebate.pos_rebate: a "point-of-sale" rebate; an upfront discount.tax_credit: a credit against federal or state taxes paid.account_credit: a credit on the consumer's utility account.assistance_program: no-cost products or services.performance_rebate: a post-purchase rebate that depends on measured or modeled efficiency improvements.unknown: something else.
Possible values: rebate, pos_rebate, tax_credit, account_credit, assistance_program, performance_rebate, unknown
authority_type
Type: string
The nature of the entity offering the incentive.
Possible values: federal, city, county, state, utility, other
authority
Type: string
The government agency, company, or organization that offers this incentive. This generally means the entity that the consumer will interact with to claim the incentive, as opposed to the entity that sets the program rules, or that provides funding.
program
Type: string
Consumer-facing name of the program that this incentive is part of. If the program has no distinct brand name, this string will usually include the name of the offering authority as well.
program_url
Type: string
A URL to the best available official source of information on this program.
more_info_url
Type: string
A URL to supplemental information on the program, usually from a third party rather than the offering authority. Localized according to the language request parameter.
items
Type: array
What products or services the incentive can be used on. NOTE: we expect to add possible values to this field over time. Client code should gracefully handle unknown values it sees here.
Possible values: air_sealing, air_to_water_heat_pump, attic_or_roof_insulation, basement_insulation, battery_storage_installation, central_air_conditioner, crawlspace_insulation, door_replacement, duct_replacement, duct_sealing, ducted_heat_pump, ductless_heat_pump, ebike, efficiency_rebates, electric_outdoor_equipment, electric_panel, electric_stove, electric_thermal_storage_and_slab, electric_vehicle_charger, electric_wiring, energy_audit, evaporative_cooler, floor_insulation, geothermal_heating_installation, heat_pump_clothes_dryer, heat_pump_water_heater, new_electric_vehicle, new_plugin_hybrid_vehicle, non_heat_pump_clothes_dryer, non_heat_pump_water_heater, other, other_heat_pump, other_insulation, other_weatherization, rooftop_solar_installation, smart_thermostat, used_electric_vehicle, used_plugin_hybrid_vehicle, wall_insulation, whole_house_fan, window_replacement, heat_pump_air_conditioner_heater, weatherization
amount
Type: object
The amount of monetary value that a consumer can receive from this incentive.
This format does not capture the full range of possible incentive structures, which can be very complex and dependent on a wide range of factors. It is a simplification in many cases. There are three amount structures, distinguished by the type field:
dollar_amount: a flat amount. This value is also used as a catchall for amount structures that don't fit into the other categories; in such cases, the aim is to at least capture the maximum value the incentive can have.dollars_per_unit: an amount that scales with the size or capacity of the equipment.percent: an amount that is a percentage of the cost of the product or service.
| Property | Type | Description |
|---|---|---|
type | string | The structure of the amount. Possible values: dollar_amount, percent, dollars_per_unit |
number | number | The dollar amount for dollar_amount and dollars_per_unit types, and a number between 0 and 1 inclusive for percent type (where 1 means 100%). |
maximum | number | The maximum dollar amount the incentive can have. |
representative | number | For non-flat amounts, an estimate of the incentive's typical value. |
unit | string | For dollars_per_unit type, the unit the amount depends on. Possible values: ton, kilowatt, watt, btuh10k, cfm50, square_foot, kilowatt_hour |
owner_status
Type: array
Whether the consumer must be a homeowner or renter (or either) to claim this incentive.
Possible values: homeowner, renter
start_date
Type: string
The time period when the incentive began, or will begin, to be available. Format is similar to an ISO-8601 date, but with some modifications and additions. Examples:
2025: incentive begins some time during that year.2025-03: incentive begins some time during that month.2025-03-10: incentive begins that day.2025H2: incentive begins some time during that half-year.2025Q3: incentive begins some time during that quarter.
end_date
Type: string
The date when the incentive stopped, or will stop, being available. Format is the same as for start_date.
short_description
Type: string
A short display description for the incentive, localized according to the language request parameter. English descriptions are 150 characters or less in almost all cases. May be slightly longer in other languages. Attempts to capture important data not expressed in other fields, such as required equipment specs, restrictions on existing home situation, etc.
Find utilities by location
Endpoint: GET /api/v1/utilities
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.
Type: object
location
Type: object
The computed location of the request's "zip" or "address" parameter.
| Property | Type | Description |
|---|---|---|
state | string | The two-letter abbreviation for the state, district, or territory of the location submitted in the request. |
city | string | The city name as determined by looking up the ZIP code in our database. |
county | string | The county name as determined by looking up the ZIP code in our database. |
utilities
Type: dictionary
A map of utility IDs to info about each utility.
| Property | Type | Description |
|---|---|---|
name | string | The customer-facing brand name of the utility. This may differ from the name of the utility's legal entity. |
Get state rollout status
Endpoint: GET /api/v1/states
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.
Type: dictionary
| Property | Type | Description |
|---|---|---|
status | string | Possible values: launched, beta, none |
Residential Electrification Model Get by Address
Endpoint: GET /api/v1/rem/address
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 of homes chosen from a conditional probability distribution based on the properties that we do know. We then predict the energy consumption for each sample building under baseline and upgrade scenarios 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 heating fuel type, which are:electricityfuel_oilnatural_gaspropanetotal(for the total of all the others).
rates: A summary of the local rates used to calculate the cost in dollars of the fuels used.emissions_factors: A summary of the emissions factors used to calculate emissions. The electricity emissions factors are long run marginal emissions rates assuming a 95% decarbonized grid by 2050, which vary by state based on how electricity is generated.
Within the fuel_results subsection for each of the fuel types, there are three components:
baseline: the usage of the fuel before the upgradeupgrade: the usage of the fuel after the upgradedelta: the change is usage of the fuel.
Inside those three, there are parallel structures with statistics for the energy used in
the form the
fuel, the emissions associated with the use of the fuel, and the cost of the fuel.
The emissions and costs are computed with the help of the numbers returned in the rates
and emissions_factors data mentioned above, where the costs only reflect only the volumetric charges
without the monthly fixed charge.
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.
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 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. The median values for electricity usage before the upgrade (baseline), the median electricity usage after the upgrade (upgrade), and median change in electricity usage after the upgrade (delta) may be not be derived from the same home sample, meaning that adding the median delta value to the median baseline value will likely not exactly equal the median upgrade value.
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 when looking at the mean.