This repo contains structured data about home electrification incentives in the US, and an API server that calculates which incentives a user is eligible for.
See public API docs at https://api.rewiringamerica.org/docs.
An instance of this API is live at https://api.rewiringamerica.org. An API key is required to use it; sign up for a key here.
(Optional) If you want the server to be able to accept addresses as well as ZIP codes, you'll need to get an API key for Geocodio. (RA employees: there's one in the internal password manager.)
Create a file called .env at the root of your working copy:
GEOCODIO_API_KEY=<YOUR_GEOCODIO_API_KEY>If you don't have a Geocodio key, just put nothing after the equals sign.
Install Node 18. We recommend using NVM.
Install Yarn by running corepack enable.
Run yarn install to install dependencies.
Run yarn build to build the SQLite database of geographic and income data.
Run yarn tsc to compile TS scripts
Run yarn dev to run the API server. It will automatically reload whenever you modify code. The server listens on port 3000 by default.
See CONTRIBUTING.md for a guide to the codebase.
You can run the API server as a Docker container, without setting up a development environment.
:rotating_light: We strongly recommend that you use Rewiring America's public API instance, rather than deploying your own instance. We'll be updating incentive data frequently, and it's important to keep up with those changes. If our public API doesn't meet your needs, please contact us to discuss.
Run docker build . to build the image.
The container listens for HTTP requests on port 8080.
If you have a Geocodio API key, put it in the environment variable GEOCODIO_API_KEY to enable the API server to accept addresses as well as ZIP codes.
The server does not deal with access control (e.g. API keys) or rate limiting. Rewiring America's public API instance uses Zuplo to handle those concerns.
There is also a Fastify plugin to handle CORS, but it's enabled only when NODE_ENV !== 'production', because RA's public API instance also uses Zuplo to handle CORS.
There are two versions of the API: v0 and v1. All API endpoint URLs are prefixed with a version.
v0 is used by the legacy IRA calculator and legacy embed calculator. It only has support for the federal incentives from the Inflation Reduction Act, will not get significant updates, and will be deprecated and removed at some point.
v1 is used by the newer calculator. This is where all new development happens. It has support for incentives from state governments and utilities. We are actively working on expanding the state/utility coverage, and evolving the API to capture the wider variety of incentive structures.
In summary: v0 is stable, but has limited incentive coverage and no future. v1 has better coverage and is under active development, but may still change in disruptive ways.
If you're looking to develop your own client of our API, expect breaking changes to v1 in the near term. If you're in contact with us, we'll notify you before deploying breaking changes, but we will be moving quickly.
Caveat: the roadmap for this project is planned and tracked internally at Rewiring America. What's reflected here may not be fully up to date.
As of November 2023, our highest priority efforts are:
Aligning to our mission, the scope of the incentive data we have collected so far is representative of the following household types and technologies.
Household Type:
Technology (Appliances / Product):
Refer to the Incentive data model definition to understand our approach to standardize the incentive data structure across all 50 states.
This data model is undergoing continuous refinement as we gather more comprehensive information about nationwide incentive programs. Our goal is to iteratively enhance the model by incorporating additional data points that complement the current broad survey of incentive data, typically derived from the market needs.
:construction: Our capacity to accept contributions is limited. We're not currently set up for external contributions of new incentive data, though we're working towards it.
That said, there are two situations we consider to be serious bugs, of which we gladly welcome reports:
eligible: true, given a specific set of inputs that would make someone ineligible for that incentive. If you see this, please file an issue.In general, we know that our incentive coverage is incomplete, and we're working to change that. However, we expect the coverage we have to be accurate, and if it's not, we want to fix that as soon as possible.
We also welcome reports of bugs that don't pertain to incentive data, such as unexpected errors from the API. Please file issues for these.
For further information, including guidance on working on code, see CONTRIBUTING.md.
See the Contributing section for specific situations where we'd like you to file an issue.
For other matters, you can email us at api@rewiringamerica.org.
For FAQs, refer to the IRA Calculator FAQ page.