This is the main API for the OpenAQ project.
Starting with index.js, there is a web-accessible API that provides endpoints to query the air quality measurements. Documentation can be found at https://docs.openaq.org/.
openaq-fetch takes care of fetching new data and inserting into the database. Data format is explained in openaq-data-format.
To run the API locally, you will need both Node.js and PostgreSQL installed.
Install necessary Node.js packages by running
npm install
Make sure you have a PostgreSQL database available (with PostGIS extension) and have the DB settings in knexfile.js.
Now you can get started with:
npm start
For production deployment, you will need to have certain environment variables set as in the table below (for production deployments, these are stored in an S3 bucket).
| Name | Description | Default |
|---|---|---|
| API_URL | Base API URL after deployment | http://:3004 |
| NEW_RELIC_LICENSE_KEY | New Relic API key for system monitoring | not set |
| WEBHOOK_KEY | Secret key to interact with openaq-api | '123' |
| USE_REDIS | Use Redis for caching? | not set (so not used) |
| REDIS_URL | Redis instance URL | redis://localhost:6379 |
| KEEN_PROJECT_ID | Keen project ID for analytics. | not set |
| KEEN_WRITE_KEY | Keen write key for analytics. | not set |
| DO_NOT_UPDATE_CACHE | Ignore updating cache, but still use older cached results. | not set |
| REQUEST_LIMIT | Max number of items that can be requested at one time. | 10000 |
| UPLOADS_ENCRYPTION_KEY | Key used to encrypt upload token for /upload in database. | 'not_secure' |
| S3_UPLOAD_BUCKET | The bucket to upload external files to for /upload. | not set |
Via an undocumented /upload endpoint, there is the ability to generate presigned S3 PUT URLs so that external clients can authenticate using tokens stored in the database and upload data to be ingested by openaq-fetch. There is a small utility file called encrypt.js that you can use like UPLOADS_ENCRYPTION_KEY=foo node index.js your_token_here to generate encrytped tokens to be manually stored in database.
To confirm that everything is working as expected, you can run the tests with
npm test
There is a Dockerfile included that will turn the project into a Docker container. The container can be found here and is currently mostly used for deployment purposes for AWS ECS. If someone wanted to make it better for local development, that'd be a great PR!
There are a lot of ways to contribute to this project, more details can be found in the contributing guide.