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 |