OpenAQ API Version 2
A web-accessible API that provides endpoints to query the real-time and historical air quality measurements on the platform.
https://github.com/openaq/openaq-api-v2
Category: Natural Resources
Sub Category: Air Quality
Keywords from Contributors
air-quality
Last synced: about 19 hours ago
JSON representation
Repository metadata
OpenAQ API
- Host: GitHub
- URL: https://github.com/openaq/openaq-api-v2
- Owner: openaq
- Created: 2021-01-12T15:39:35.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-06-20T19:14:45.000Z (12 days ago)
- Last Synced: 2025-06-26T20:08:38.491Z (6 days ago)
- Language: Python
- Homepage: https://api.openaq.org
- Size: 3.41 MB
- Stars: 52
- Watchers: 7
- Forks: 11
- Open Issues: 9
- Releases: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
README.md
OpenAQ API
Overview
This repository contains the source code for the OpenAQ API, a publicly-accessible API that provides endpoints to query the real-time and historical air quality measurements on the OpenAQ platform.
[!NOTE]
This repository is for setting up and deploying the OpenAQ API. If you just wish to access the public API to query data from the OpenAQ platform, visit https://api.openaq.org or https://docs.openaq.org to learn more.
Package management
We are currently using Poetry to manage our dependencies and run locally.
Local development
In production, the OpenAQ API runs on AWS Lambda with the help of the mangum library. This allows the application to run in a serverless environment and take advantage of async Python and FastAPI routing. Despite the serverless deployment, running the API locally as a standard FastAPI application is largely unchanged, making local development much easier.
Settings
Settings can be loaded using .env
files, and multiple files can be kept and used. The easiest way to manage multiple environment files is to add an extension describing your environment. For example, if I wanted to keep a production, staging and local environment, I would save them as .env.production
, .env.staging
and .env.local
each with their own settings.
DATABASE_READ_USER=database-read-user
DATABASE_WRITE_USER=database-write-user
DATABASE_READ_PASSWORD=database-read-password
DATABASE_WRITE_PASSWORD=database-write-password
DATABASE_DB=database-name
DATABASE_HOST=localhost
DATABASE_PORT=5432
LOG_LEVEL=info
Running locally
The easiest way to run the API locally is to use uvicorn. Make sure that you have your settings (.env
) file setup. Once that is done, you can run the following from the openaq_api
directory. Variables from the .env
files can be overrode by setting them inline.
# Run using the default .env file
poetry run uvicorn openaq_api.main:app --reload --lifespan on
You can also specify which .env
file to load by passing the ENV
variable. This should not include the .env.
prefix
DOTENV=local poetry run uvicorn openaq_api.main:app --reload --lifespan on
If you are connecting to our production environment you will AWS credentials therefor you may need to provdide the profile name to access the right credentials.
AWS_PROFILE=optional-profile-name \
DOTENV=production \
poetry run uvicorn openaq_api.main:app --reload --lifespan on
And you can always override variables by setting them inline. This is handy for when you want to change something for the purpose of debugging.
# Run the staging environment and add verbose logging
ENV=staging LOG_LEVEL=debug uvicorn main:app --reload
DOTENV=staging \
LOG_LEVEL=debug \
poetry run uvicorn openaq_api.main:app --reload --lifespan on
Testing
From the root directory
DOTENV=local poetry run pytest tests/
Rate limiting
In the production environment, rate limiting is handled in two places, AWS WAF and at the application level with Starlette Middleware. The application rate limiting is configurable via environment variables. The rate limiting middleware requires access to an instance of a redis cluster. For local development, docker can be a convenient method to set up a local redis cluster. With docker, use the following command:
docker run -e "IP=0.0.0.0" -p 7000-7005:7000-7005 grokzen/redis-cluster:7.0.7
Now a redis instance will be available at http://localhost:7000
. Configure the REDIS_HOST to localhost
and REDIS_PORT to 7000
.
[!TIP]
On some macOS systems port 7000 is used by Airplay which can complicate the mapping of ports from the Docker container. The easiest option is to disable the Airplay reciever in system settings.System settings -> General -> Airplay receiver (toggle off)
Rate limiting values
Rate limiting can be toggled off for local develop via the RATE_LIMITING
environment variable. Other rate limiting values are:
RATE_AMOUNT_KEY
- The number of requests allowed with a valid API keyRATE_TIME
- The number of minutes for the rate
e.g. RATE_AMOUNT_KEY=5
and RATE_TIME=1
would allow 5 requests per 1 minute.
[!NOTE]
With AWS WAF, rate limiting also occurs at the cloudfront stage. The application level rate limiting should be less than or equal to the value set at AWS WAF.
Deployment
Deployment is managed with Amazon Web Services (AWS) Cloud Development Kit (CDK). Additional environment variables are required for a full deployment to the AWS Cloud.
Deploying
AWS_PROFILE=optional-profile-name DOTENV=production cdk deploy openaq-api-production
Platform Overview
openaq-fetch and openaq-fetch-lcs take care of fetching new data and writing to S3. Lambda functions defined in openaq-ingestor, then load data into the database, defined in openaq-db.
Contributing
There are many ways to contribute to this project; more details can be found in the contributing guide.
Owner metadata
- Name: OpenAQ Platform
- Login: openaq
- Email: [email protected]
- Kind: organization
- Description: An open platform for air quality data
- Website: https://openaq.org
- Location:
- Twitter: OpenAQ
- Company:
- Icon url: https://avatars.githubusercontent.com/u/11806583?v=4
- Repositories: 53
- Last ynced at: 2025-06-26T15:15:15.514Z
- Profile URL: https://github.com/openaq
GitHub Events
Total
- Issues event: 39
- Watch event: 10
- Issue comment event: 18
- Push event: 60
- Pull request event: 11
- Pull request review event: 6
- Pull request review comment event: 5
- Fork event: 3
- Create event: 4
Last Year
- Issues event: 39
- Watch event: 10
- Issue comment event: 18
- Push event: 60
- Pull request event: 11
- Pull request review event: 6
- Pull request review comment event: 5
- Fork event: 3
- Create event: 4
Committers metadata
Last synced: 7 days ago
Total Commits: 383
Total Committers: 7
Avg Commits per committer: 54.714
Development Distribution Score (DDS): 0.332
Commits in past year: 57
Committers in past year: 3
Avg Commits per committer in past year: 19.0
Development Distribution Score (DDS) in past year: 0.175
Name | Commits | |
---|---|---|
Russ Biggs | r****s@g****m | 256 |
Christian Parker | c****r@t****m | 106 |
Gabriel Fosse | 6****o | 9 |
David Bitner | b****r@d****m | 8 |
Heet Bhimani | h****z@g****m | 2 |
sruti | s****i@o****g | 1 |
Chris Hagerbaumer | 1****a | 1 |
Committer domains:
Issue and Pull Request metadata
Last synced: 2 days ago
Total issues: 126
Total pull requests: 273
Average time to close issues: 9 months
Average time to close pull requests: 4 days
Total issue authors: 39
Total pull request authors: 8
Average comments per issue: 1.26
Average comments per pull request: 0.18
Merged pull request: 258
Bot issues: 0
Bot pull requests: 0
Past year issues: 16
Past year pull requests: 25
Past year average time to close issues: about 1 month
Past year average time to close pull requests: 7 days
Past year issue authors: 5
Past year pull request authors: 4
Past year average comments per issue: 0.38
Past year average comments per pull request: 0.48
Past year merged pull request: 21
Past year bot issues: 0
Past year bot pull requests: 0
Top Issue Authors
- russbiggs (54)
- majesticio (17)
- sruti (5)
- caparker (5)
- MauriceHeinze (4)
- barronh (3)
- jeffmcwhirter (2)
- iAutom8 (2)
- davidasboth (2)
- c-odebroker (2)
- SaBaLeRo22 (2)
- dr226 (1)
- jkagevm (1)
- pavlovc2 (1)
- crx091081gb (1)
Top Pull Request Authors
- russbiggs (198)
- caparker (41)
- majesticio (27)
- heetu (2)
- sruti (2)
- JouzefB (1)
- bitner (1)
- zmoon (1)
Top Issue Labels
- bug (26)
- enhancement (17)
- documentation (3)
- infrastructure (2)
- help wanted (1)
Top Pull Request Labels
- enhancement (4)
- bug (1)
Dependencies
- attrs ==21.4.0
- aws-cdk-lib ==2.3.0
- aws-cdk.aws-apigatewayv2-alpha ==2.3.0a0
- aws-cdk.aws-apigatewayv2-integrations-alpha ==2.3.0a0
- cattrs ==22.1.0
- constructs ==10.1.16
- exceptiongroup ==1.0.0rc7
- jsii ==1.59.0
- publication ==0.0.3
- pydantic ==1.9.1
- python-dateutil ==2.8.2
- python-dotenv ==0.20.0
- six ==1.16.0
- typing_extensions ==4.2.0
- docker *
- actions/checkout v3 composite
- actions/setup-node v2 composite
- actions/setup-python v3 composite
- aws-actions/configure-aws-credentials master composite
- actions/checkout v3 composite
- actions/setup-node v2 composite
- actions/setup-python v3 composite
- aws-actions/configure-aws-credentials master composite
- boto3 ==1.24.28
- botocore ==1.27.28
- jmespath ==1.0.1
- pydantic ==1.9.1
- pyhumps ==3.7.2
- python-dateutil ==2.8.2
- s3transfer ==0.6.0
- six ==1.16.0
- typing_extensions ==4.3.0
- urllib3 ==1.26.10
- actions/checkout v3 composite
- actions/setup-python v3 composite
- public.ecr.aws/sam/build-python3.11 1.97.0-20230905191328-x86_64 build
- lightningcss ^1.18.0 development
- sass ^1.59.3 development
- vite ^4.2.0 development
- vite-plugin-lightningcss ^0.0.3 development
- vite-plugin-purgecss ^0.2.12 development
- @zxcvbn-ts/core ^2.2.1
- @zxcvbn-ts/language-common ^2.0.1
- @zxcvbn-ts/language-en ^2.1.0
- openaq-design-system github:openaq/openaq-design-system#v-4.0.0
- 176 dependencies
- Deprecated ==1.2.13
- Jinja2 ==3.1.2
- Markdown ==3.3.7
- MarkupSafe ==2.1.1
- PyPika ==0.48.9
- PyYAML ==6.0
- Pygments ==2.15.1
- SQLAlchemy ==1.4.36
- aiocache ==0.11.1
- annotated-types ==0.5.0
- anyio ==3.6.1
- asgiref ==3.5.2
- async-timeout ==4.0.2
- asyncpg ==0.28.0
- attrs ==22.1.0
- bcrypt ==4.0.1
- boto3 ==1.26.101
- botocore ==1.29.101
- buildpg ==0.4
- bump-pydantic ==0.1.0
- certifi ==2022.12.7
- charset-normalizer ==3.0.1
- click ==8.1.3
- coverage ==7.2.7
- dateparser ==1.1.1
- dnspython ==2.3.0
- email-validator ==2.0.0.post2
- exceptiongroup ==1.0.4
- fastapi ==0.100.0
- greenlet ==2.0.2
- h11 ==0.12.0
- httpcore ==0.14.7
- httpx ==0.22.0
- idna ==3.3
- importlib-metadata ==4.11.4
- iniconfig ==1.1.1
- jmespath ==1.0.1
- jq ==1.5.0
- libcst ==1.0.1
- mangum ==0.15.0
- markdown-it-py ==3.0.0
- mdurl ==0.1.2
- msgpack ==1.0.3
- mypy-extensions ==1.0.0
- orjson ==3.9.7
- packaging ==21.3
- passlib ==1.7.4
- pluggy ==1.0.0
- pydantic ==2.0.2
- pydantic-settings ==2.0.1
- pydantic_core ==2.1.2
- pyhumps ==3.7.1
- pyparsing ==3.0.9
- pytest ==7.2.0
- pytest-cov ==4.1.0
- python-dateutil ==2.8.2
- python-dotenv ==1.0.0
- python-multipart ==0.0.6
- pytz ==2022.1
- pytz-deprecation-shim ==0.1.0.post0
- redis ==4.3.3
- regex ==2022.3.2
- rfc3986 ==1.5.0
- rich ==13.4.2
- s3transfer ==0.6.0
- six ==1.16.0
- sniffio ==1.2.0
- starlette ==0.27.0
- tomli ==2.0.1
- typer ==0.9.0
- typing-inspect ==0.9.0
- typing_extensions ==4.7.1
- tzdata ==2022.1
- tzlocal ==4.2
- ujson ==5.8.0
- urllib3 ==1.26.15
- uvicorn ==0.17.6
- wrapt ==1.14.1
- zipp ==3.8.0
- zxcvbn ==4.4.28
- httpx * development
- pytest * development
- asyncpg *
- fastapi *
- fastapi-utils *
- mangum >=0.1.0
- pydantic *
- pypika *
- wheel *
Score: 6.056784013228625