{"id":15893602,"url":"https://github.com/alexdlaird/air-quality-bot","last_synced_at":"2025-03-20T14:30:35.527Z","repository":{"id":33784163,"uuid":"158851859","full_name":"alexdlaird/air-quality-bot","owner":"alexdlaird","description":"Texting service to receive current air quality conditions and maps, powered by AirNow, Twilio, and AWS","archived":false,"fork":false,"pushed_at":"2024-09-23T10:56:53.000Z","size":1072,"stargazers_count":12,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-07T08:12:10.989Z","etag":null,"topics":["airnow","airquality","aqi","aws-lambda","bot","education","evacuation","fire","python","twilio","twilio-sms","wildfire"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexdlaird.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"alexdlaird","patreon":"alexdlaird","custom":["https://www.paypal.me/alexdlaird"]}},"created_at":"2018-11-23T15:50:01.000Z","updated_at":"2024-09-23T10:56:50.000Z","dependencies_parsed_at":"2023-02-10T16:01:35.771Z","dependency_job_id":"caf6f7d5-6954-4222-be89-0f928f025b18","html_url":"https://github.com/alexdlaird/air-quality-bot","commit_stats":{"total_commits":313,"total_committers":6,"mean_commits":"52.166666666666664","dds":0.6006389776357828,"last_synced_commit":"66e1cc4c9f61a7a26ed47660513df88d9b53bb50"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdlaird%2Fair-quality-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdlaird%2Fair-quality-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdlaird%2Fair-quality-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdlaird%2Fair-quality-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexdlaird","download_url":"https://codeload.github.com/alexdlaird/air-quality-bot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244075595,"owners_count":20393979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["airnow","airquality","aqi","aws-lambda","bot","education","evacuation","fire","python","twilio","twilio-sms","wildfire"],"created_at":"2024-10-06T08:12:14.682Z","updated_at":"2025-03-20T14:30:35.192Z","avatar_url":"https://github.com/alexdlaird.png","language":"Python","funding_links":["https://github.com/sponsors/alexdlaird","https://patreon.com/alexdlaird","https://www.paypal.me/alexdlaird"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg alt=\"Air Quality Bot - Text (415) 212-4229\" src=\"https://raw.githubusercontent.com/alexdlaird/air-quality-bot/main/logo.png\" /\u003e\u003c/p\u003e\n\n![Python Versions](https://img.shields.io/badge/python-%203.8%20|%203.9%20|%203.10%20|%203.11%20-blue)\n[![Coverage](https://img.shields.io/codecov/c/github/alexdlaird/air-quality-bot)](https://codecov.io/gh/alexdlaird/air-quality-bot)\n[![Build](https://img.shields.io/github/actions/workflow/status/alexdlaird/air-quality-bot/build.yml)](https://github.com/alexdlaird/air-quality-bot/actions/workflows/build.yml)\n[![GitHub License](https://img.shields.io/github/license/alexdlaird/air-quality-bot)](https://github.com/alexdlaird/air-quality-bot/blob/main/LICENSE)\n\nThe Air Quality Bot is generally available by texting a zip code (and optionally\nthe word \"map\") to (415) 212-4229. The bot will respond with the latest air\nquality report for your region.\n\nThe instructions below illustrate how to similarly setup the bot in your own\nAWS and Twilio environments.\n\n## Getting Started\n\n### AWS Initial Setup\n\nCreate a new Role from a Policy with the following permissions:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"logs:CreateLogGroup\",\n                \"logs:CreateLogStream\",\n                \"logs:PutLogEvents\",\n                \"cloudwatch:PutMetricData\",\n                \"dynamodb:CreateTable\",\n                \"dynamodb:GetItem\",\n                \"dynamodb:PutItem\",\n                \"dynamodb:UpdateItem\",\n                \"dynamodb:DescribeTable\",\n                \"dynamodb:GetShardIterator\",\n                \"dynamodb:GetRecords\",\n                \"dynamodb:ListStreams\",\n                \"dynamodb:Query\",\n                \"dynamodb:Scan\"\n            ],\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\nInstall and configure the [AWS CLI](https://docs.aws.amazon.com/lambda/latest/dg/setup-awscli.html)\nfor the same account for which the Role was created.\n\n### AWS Lambdas\n\nInitialize the deployment environment by running `make install` locally, then\nedit the `.env` file's `AWS_ROLE` with the ID of the Role created above and the\n`AIRNOW_API_KEYS` list with one or more [AirNow API keys](https://docs.airnowapi.org/).\n\nNote that, on initial deploy, your Lambdas will be pointing to the an endpoint\nthat does not exist until you complete the `AWS API Gateway Routes` section\nbelow and update the `AIR_QUALITY_API_URL` variable to point to the deployed endpoint.\n\nDeploy the Lambdas to your AWS environment using the deploy script:\n\n```sh\n./deploy.sh\n```\n\nOptionally, TTL for `ZipCode` fields in the DynamoDB table can be enabled by going\nto [the AWS console](https://console.aws.amazon.com/dynamodb/home?region=us-east-1#tables:)\nand enabling TTL on the `TTL` field.\n\n### AWS API Gateway Routes\n\nCreate an [API Gateway](https://console.aws.amazon.com/apigateway/home?region=us-east-1#/apis).\nIn the API, do the following:\n\n- Create a new \"Resource\" with a path of `/inbound`\n  - Create a new \"POST\" method with the \"Integration type\" of \"Lambda Function\" and point it to the Lambda `AirQuality_inbound_POST`\n    - Edit the \"POST\" method's \"Integration Request\"\n      - Under \"Mapping Templates\", add a \"Content-Type\" of `application/x-www-form-urlencoded` using the \"General template\" of \"Method Request Passthrough\"\n    - Edit the \"POST\" method's \"Method Response\"\n    - Edit the `200` response so it has a \"Content type\" of `application/xml`\n\nLast, under the \"Integration Response\" for `/inbound`, edit the `200` response. Under \"Mapping Templates\" of \"Content-Type\" of `application/xml` with the following template:\n\n```js\n#set($inputRoot = $input.path('$'))\n$inputRoot.body\n```\n\nAdditionally, create the following \"Resource\" paths:\n\n- `/aqi`\n\nUnder each of the above, do the following:\n\n- Create a new \"GET\" method with the \"Integration type\" of \"Lambda Function\" and point it to the Lambda `AirQuality_\u003cROUTE_NAME\u003e_GET`, where \u003cROUTE_NAME\u003e corresponds to the name of the Lambda we created\nto execute on this method\n  - Edit the \"GET\" method's \"Method Request\"\n    - Change the \"Request Validator\" to \"Validate query string parameters and header\"\n    - Add a required \"URL Query String Parameter\" of `zipCode`\n    - Edit the \"GET\" method's \"Integration Request\"\n          - Under \"Mapping Templates\", add a \"Content-Type\" of `application/json` using the \"General template\" of \"Method Request Passthrough\"\n\nDeploy the new API Gateway. Note the newly generated `Invoke URL` and update the\n`AIR_QUALITY_API_URL` variable in `.env`, then redeploy your Lambdas by running\n`./deploy.sh` again.\n\n### Setup Twilio\n\nIn Twilio, create a phone number and set it up. Under \"Messaging\", select\n\"Webhook\" for when \"A Message Comes In\", select \"POST\", and enter the deployed\nAPI Gateway URL for `/inbound`.\n\nThat's it! Your bot is now setup and ready to respond to texts.\n\n## Local Development\n\nTo test the bot locally, simple [Flask](https://flask.palletsprojects.com/en/1.1.x) server is included in\n`devserver.py`. Ensure proper `dev` values are in `.env.dev`, then execute:\n\n```sh\nmake run-devserver\n```\n\nThis will start a server with the appropriate routes and in-memory datastores,\nand it will also start a [ngrok](https://ngrok.com/) tunnel using\n[pyngrok](https://github.com/alexdlaird/pyngrok) so the bot can be fully tested\nend-to-end.\n\n## CI Build\n\nIf you would like the project to build for you in a CI system, you may\nneed to add the following environment variables to the CI's console. Their\nactual values do not matter (use dummy values, not real), but certain versions\nof the `boto` dependency need them to be present when initializing its\nconfiguration.\n\n- `AWS_ACCESS_KEY_ID`\n- `AWS_DEFAULT_REGION`\n- `AWS_SECRET_ACCESS_KEY`\n\n## Deploy Updates\n\nAfter the initial installation in to your AWS environment, updates to the Lambdas\ncan easily be redeployed at any time by rerunning the deploy script:\n\n```sh\n./deploy.sh\n```\n\n## Contributing\n\nIf you would like to get involved, be sure to review the [Contribution Guide](https://github.com/alexdlaird/air-quality-bot/blob/main/CONTRIBUTING.rst).\n\nWant to contribute financially? If you've found Air Quality Bot useful, [sponsorship](https://github.com/sponsors/alexdlaird) would\nalso be greatly appreciated!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdlaird%2Fair-quality-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexdlaird%2Fair-quality-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdlaird%2Fair-quality-bot/lists"}