{"id":13948784,"url":"https://github.com/jdemaeyer/brightsky","last_synced_at":"2025-07-20T10:32:45.558Z","repository":{"id":41505466,"uuid":"247023533","full_name":"jdemaeyer/brightsky","owner":"jdemaeyer","description":"JSON API for DWD's open weather data.","archived":false,"fork":false,"pushed_at":"2025-04-30T10:38:26.000Z","size":2907,"stargazers_count":347,"open_issues_count":25,"forks_count":18,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-07-14T05:04:38.624Z","etag":null,"topics":["api","dwd","open-data","weather"],"latest_commit_sha":null,"homepage":"https://brightsky.dev/","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/jdemaeyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":"jdemaeyer"}},"created_at":"2020-03-13T08:34:19.000Z","updated_at":"2025-07-13T15:10:46.000Z","dependencies_parsed_at":"2024-01-12T04:52:56.616Z","dependency_job_id":"be6217e1-b5ca-44f1-9cfc-e07705627e6f","html_url":"https://github.com/jdemaeyer/brightsky","commit_stats":{"total_commits":344,"total_committers":4,"mean_commits":86.0,"dds":0.008720930232558155,"last_synced_commit":"0da2c9ba05457ffe270b516a7812dc2663174045"},"previous_names":[],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/jdemaeyer/brightsky","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdemaeyer%2Fbrightsky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdemaeyer%2Fbrightsky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdemaeyer%2Fbrightsky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdemaeyer%2Fbrightsky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdemaeyer","download_url":"https://codeload.github.com/jdemaeyer/brightsky/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdemaeyer%2Fbrightsky/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265407524,"owners_count":23760046,"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":["api","dwd","open-data","weather"],"created_at":"2024-08-08T05:01:30.789Z","updated_at":"2025-07-20T10:32:45.549Z","avatar_url":"https://github.com/jdemaeyer.png","language":"Python","funding_links":["https://github.com/sponsors/jdemaeyer"],"categories":["Atmosphere"],"sub_categories":["Meteorological Observation and Forecast"],"readme":"\u003cimg src=\"docs/favicon.svg\" align=\"right\" style=\"height: 140px\"\u003e\n\n# Bright Sky\n\n[![API Status](https://img.shields.io/website?down_message=offline\u0026label=api\u0026up_message=online\u0026url=https%3A%2F%2Fapi.brightsky.dev%2F)](https://api.brightsky.dev/)\n[![Docs Status](https://img.shields.io/website?down_message=offline\u0026label=docs\u0026up_message=online\u0026url=https%3A%2F%2Fbrightsky.dev%2Fdocs%2F)](https://brightsky.dev/docs/)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/jdemaeyer/brightsky/main.yml)](https://github.com/jdemaeyer/brightsky/actions)\n[![PyPI Release](https://img.shields.io/pypi/v/brightsky)](https://pypi.org/project/brightsky/)\n[![Docker Hub Release](https://img.shields.io/docker/v/jdemaeyer/brightsky/latest?label=docker)](https://hub.docker.com/r/jdemaeyer/brightsky)\n\n### JSON API for DWD's open weather data.\n\nThe DWD ([Deutscher Wetterdienst](https://www.dwd.de/)), as Germany's\nmeteorological service, publishes a myriad of meteorological observations and\ncalculations as part of their [Open Data\nprogram](https://www.dwd.de/DE/leistungen/opendata/opendata.html).\n\n[**Bright Sky**](https://brightsky.dev/) is an open-source project aiming to\nmake some of the more popular data — in particular weather observations from\nthe DWD station network and weather forecasts from the MOSMIX model — available\nin a free, simple JSON API.\n\n\n### Looking for something specific?\n\n#### I just want to retrieve some weather data\n\nYou can use the free [public Bright Sky instance](https://brightsky.dev/)!\n\n#### I want to run my own instance of Bright Sky\n\nCheck out the [infrastructure\nrepo](https://github.com/jdemaeyer/brightsky-infrastructure/)!\n\n#### I want to parse DWD weather files from the command line or in Python\n\nThe parsing core for Bright Sky is maintained in a separate package named\n[`dwdparse`](https://github.com/jdemaeyer/dwdparse), which has no dependencies\noutside the standard library. If you find that's not quite serving your needs,\ncheck out [`wetterdienst`](https://github.com/earthobservations/wetterdienst).\n\n#### I want to contribute to Bright Sky's source code\n\nRead on. :)\n\n\n### On Bright Sky's versioning\n\nStarting from version 2.0, where we extracted the parsing core into a [separate\npackage](https://github.com/jdemaeyer/dwdparse), Bright Sky is **no longer\nintended to be used as a Python library**, but only as the service available at\n[`brightsky.dev`](https://brightsky.dev/).\n\nConsequentially, we adjust our version numbers from the _perspective of that\nservice and its users_ – i.e., we will increase the major version number only\nwhen we introduce backwards-incompatible (or otherwise very major) changes to\nthe actual JSON API interface, e.g. by changing URLs or parameters. This means\nthat **increases of the minor version number may introduce\nbackwards-incompatible changes to the internals of the `brightsky` package,\nincluding the database structure**. If you use `brightsky` as a Python library,\nplease version-pin to a minor version, e.g. by putting `brightsky==2.0.*` in\nyour `requirements.txt`.\n\n\n## Quickstart\n\n### Running a full-fledged API instance\n\n_Note: These instructions are aimed at running a Bright Sky instance for\ndevelopment and testing. Check out our [infrastructure\nrepository](https://github.com/jdemaeyer/brightsky-infrastructure/) if you want\nto set up a production-level API instance._\n\nJust run `docker-compose up` and you should be good to go. This will set up a\nPostgreSQL database (with persistent storage in `.data`), run a Redis server,\nand start the Bright Sky worker and webserver. The worker periodically polls\nthe DWD Open Data Server for updates, parses them, and stores them in the\ndatabase. The webserver will be listening to API requests on port 5000.\n\n\n## Architecture\n\n![Bright Sky's Architecture](docs/img/architecture.svg)\n\nBright Sky is a rather simple project consisting of four components:\n\n * The `brightsky` worker, which leverages the logic contained in the\n   `brightsky` Python package to retrieve weather records from the DWD server,\n   parse them, and store them in a database. It will periodically poll the DWD\n   servers for new data.\n\n * The `brightsky` webserver (API), which serves as gate to our database and\n   processes all queries for weather records coming from the outside world.\n\n * A PostgreSQL database consisting of two relevant tables:\n\n    * `sources` contains information on the locations for which we hold weather\n      records, and\n    * `weather` contains the history of actual meteorological measurements (or\n      forecasts) for these locations.\n\n   The database structure can be set up by running the `migrate` command, which\n   will simply apply all `.sql` files found in the `migrations` folder.\n\n * A Redis server, which is used as the backend of the worker's task queue.\n\nMost of the tasks performed by the worker and webserver can also be performed\nindependently. Run `docker-compose run --rm brightsky` to get a list of\navailable commands.\n\n\n## Hacking\n\nConstantly rebuilding the `brightsky` container while working on the code can\nbecome cumbersome, and the default setting of parsing records dating all the\nway back to 2010 will make your development database unnecessarily large. You\ncan set up a more lightweight development environment as follows:\n\n 1. Create a virtual environment and install our dependencies:\n    `python -m virtualenv .venv \u0026\u0026 source .venv/bin/activate \u0026\u0026 pip install -r\n    requirements.txt \u0026\u0026 pip install -e .`\n\n 2. Start a PostgreSQL container:\n    `docker-compose run --rm -p 5432:5432 postgres`\n\n 3. Start a Redis container:\n    `docker-compose run --rm -p 6379:6379 redis`\n\n 4. Point `brightsky` to your containers, and configure a tighter date\n    threshold for parsing DWD data, by adding the following `.env` file:\n    ```\n    BRIGHTSKY_DATABASE_URL=postgres://postgres:pgpass@localhost\n    BRIGHTSKY_BENCHMARK_DATABASE_URL=postgres://postgres:pgpass@localhost/benchmark\n    BRIGHTSKY_REDIS_URL=redis://localhost\n    BRIGHTSKY_MIN_DATE=2020-01-01\n    ```\n\nYou should now be able to directly run `brightsky` commands via `python -m\nbrightsky`, and changes to the source code should be effective immediately.\n\n\n### Tests\n\nLarge parts of our test suite run against a real Postgres database. By default,\nthese tests will be skipped. To enable them, make sure the\n`BRIGHTSKY_DATABASE_URL` environment variable is set when calling `pytest`,\ne.g. via:\n```\nBRIGHTSKY_DATABASE_URL=postgres://postgres:pgpass@localhost/brightsky_test pytest\n```\n\nBeware that adding this environment variable to your `.env` file will not work\nas that file is not read by `pytest`. The database will be **dropped and\nrecreated** on every test run, so don't use your normal Bright Sky database. ;)\n\n\n## Acknowledgements\n\nBright Sky's development is boosted by the priceless guidance and support of\nthe [Open Knowledge Foundation](https://www.okfn.de/)'s [Prototype\nFund](https://prototypefund.de/) program, and is generously funded by Germany's\n[Federal Ministry of Education and Research](https://www.bmbf.de/). Obvious as\nit may be, it should be mentioned that none of this would be possible without\nthe painstaking, never-ending effort of the [Deutscher\nWetterdienst](https://www.dwd.de/).\n\n\u003ca href=\"https://prototypefund.de/\"\u003e\u003cimg src=\"docs/img/pf.svg\" alt=\"Prototype Fund\" height=\"100\"\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n\u003ca href=\"https://okfn.de/\"\u003e\u003cimg src=\"docs/img/okfde.svg\" alt=\"Open Knowledge Foundation Germany\" height=\"100\"\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n\u003ca href=\"https://www.bmbf.de/\"\u003e\u003cimg src=\"docs/img/bmbf.svg\" alt=\"Bundesministerium für Bildung und Forschung\" height=\"100\"\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n\u003ca href=\"https://www.dwd.de/\"\u003e\u003cimg src=\"docs/img/dwd.svg\" alt=\"Deutscher Wetterdienst\" height=\"100\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdemaeyer%2Fbrightsky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdemaeyer%2Fbrightsky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdemaeyer%2Fbrightsky/lists"}