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

Type: object

PropertyTypeDescription
srcstringThe URL to fetch the image from.
widthnumberThe image's width in pixels.
heightnumberThe image's height in pixels.

coverage

Type: object

Which sub-national sets of incentives were considered for eligibility.

PropertyTypeDescription
statestringTwo-letter state code. Determined from the "location" request parameter.
utilitystringUtility ID, as passed in the "utility" request parameter.

location

Type: object

The computed location of the request's "zip" or "address" parameter.

PropertyTypeDescription
statestringThe two-letter abbreviation for the state, district, or territory of the location submitted in the request.
citystringThe city name as determined by looking up the ZIP code in our database.
countystringThe 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

PropertyTypeDescription
srcstringThe URL to fetch the image from.
widthnumberThe image's width in pixels.
heightnumberThe 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

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.
PropertyTypeDescription
typestringThe structure of the amount. Possible values: dollar_amount, percent, dollars_per_unit
numbernumberThe 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%).
maximumnumberThe maximum dollar amount the incentive can have.
representativenumberFor non-flat amounts, an estimate of the incentive's typical value.
unitstringFor 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.

PropertyTypeDescription
statestringThe two-letter abbreviation for the state, district, or territory of the location submitted in the request.
citystringThe city name as determined by looking up the ZIP code in our database.
countystringThe 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.

PropertyTypeDescription
namestringThe 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/calculator only if the include_beta_states request parameter is true.
  • launched: SLU incentives are fully vetted and returned in the API.

Type: dictionary

PropertyTypeDescription
statusstringPossible values: launched, beta, none