geokachel 0.1.0__tar.gz

geokachel-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+# Every push and pull request. Fast on purpose: no network, no portals.
+#
+# The tests here never touch a state surveying office. Everything they check is
+# built in the test — archives, grids, indexes, malformed headers — because a
+# suite that needs sixteen public portals to be up fails on their maintenance
+# window and teaches people to ignore red. Whether those portals still serve
+# what this registry claims is `sources.yml`, weekly, and it opens an issue
+# instead of failing.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy geokachel
+      - run: pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+      - run: pip install --upgrade build twine
+      - run: python -m build
+      # A wheel that claims to be typed and ships no marker silently un-types
+      # every consumer. That happened once; it does not happen again.
+      - name: The wheel must carry py.typed and both licence files
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import glob, zipfile, sys
+          names = zipfile.ZipFile(sorted(glob.glob("dist/*.whl"))[-1]).namelist()
+          need = {"py.typed": any(n.endswith("geokachel/py.typed") for n in names),
+                  "LICENSE": any(n.endswith("licenses/LICENSE") for n in names),
+                  "NOTICE": any(n.endswith("licenses/NOTICE") for n in names)}
+          for what, there in need.items():
+              print(f"{'ok ' if there else 'MISSING'} {what}")
+          sys.exit(0 if all(need.values()) else 1)
+          PY
+      - run: twine check dist/*

geokachel-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,92 @@
+# Publish to PyPI when a version tag is pushed.
+#
+# **No token anywhere.** This uses PyPI Trusted Publishing (OIDC): GitHub mints
+# a short-lived identity for this exact workflow in this exact repository, and
+# PyPI trusts that instead of a long-lived secret. Nothing to leak, nothing to
+# rotate, nothing to paste into a terminal.
+#
+# One-time setup on PyPI — https://pypi.org/manage/account/publishing/ :
+#
+#     PyPI Project Name   geokachel
+#     Owner               JanderHungrige
+#     Repository name     geokachel
+#     Workflow name       release.yml
+#     Environment name    pypi
+#
+# Then, to release:
+#
+#     git tag v0.1.0 && git push origin v0.1.0
+#
+# A PyPI version can never be reused, even after deletion, so the tag is the
+# point of no return. `test` below publishes to TestPyPI first if you want a
+# rehearsal: push a tag ending in `rc1`.
+name: release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+
+      - name: The tag and the version must agree
+        run: |
+          set -euo pipefail
+          tagged="${GITHUB_REF_NAME#v}"
+          declared=$(python -c "import tomllib,pathlib; \
+            print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          echo "tag $tagged, pyproject $declared"
+          # A version published under the wrong number cannot be taken back.
+          [ "$tagged" = "$declared" ] || {
+            echo "::error::tag v$tagged does not match pyproject $declared"; exit 1; }
+
+      - run: pip install --upgrade build
+      - run: python -m build
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  rehearse:
+    # A tag ending in rc goes to TestPyPI and no further.
+    if: contains(github.ref_name, 'rc')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish:
+    if: ${{ !contains(github.ref_name, 'rc') }}
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # The whole mechanism: a short-lived OIDC identity instead of a secret.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

geokachel-0.1.0/.github/workflows/sources.yml

@@ -0,0 +1,85 @@
+# Are the state surveying offices still serving what the registry says?
+#
+# Deliberately NOT part of the CI suite. A suite that needs
+# sixteen state portals to be up fails on their maintenance window, teaches
+# people to ignore red, and says nothing about this repository's code.
+#
+# So this job does not fail. When something has moved it opens an issue — or
+# adds to the open one — and stays green, because a red build nobody can fix by
+# changing code is a red build everybody learns to scroll past.
+name: sources
+
+on:
+  schedule:
+    # Monday, early, off the hour: sixteen public offices, not an API.
+    - cron: "17 4 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: sources
+  cancel-in-progress: false
+
+jobs:
+  ask:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+
+      - run: pip install .
+
+      - name: Ask every source whether it is still there
+        id: ask
+        env:
+          # Say who is asking. These offices publish at their own expense, and
+          # a request from a CI runner with no contact in it is rude.
+          GEOKACHEL_USER_AGENT: >-
+            geokachel/0.1 (+https://github.com/${{ github.repository }};
+            weekly source check)
+        run: |
+          set +e
+          geokachel check > report.txt 2>&1
+          echo "moved=$?" >> "$GITHUB_OUTPUT"
+          cat report.txt
+          exit 0
+
+      - name: Say so, once, where somebody will see it
+        if: steps.ask.outputs.moved != '0'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          {
+            echo "A source this project reads has changed. It is not a code failure —"
+            echo "a state has moved its files, rotated a share token, renamed a coverage"
+            echo "or retired a tile."
+            echo
+            echo "Re-read it from the source and correct the registry and its doc:"
+            echo "an entry is a request that was answered, and this one no longer is."
+            echo
+            echo '```'
+            cat report.txt
+            echo '```'
+            echo
+            echo "[The run]($RUN)"
+          } > body.md
+
+          open=$(gh issue list --label sources --state open \
+                   --json number --jq '.[0].number // empty')
+          if [ -n "$open" ]; then
+            gh issue comment "$open" --body-file body.md
+          else
+            gh label create sources --color BFD4F2 \
+              --description "A state moved its data" 2>/dev/null || true
+            gh issue create --title "A source has moved" \
+              --label sources --body-file body.md
+          fi

geokachel-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

geokachel-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+The most useful contribution is **a state that is missing, or a state that
+moved** — and both follow one rule.
+
+## An entry is a request that was answered
+
+Never a portal page that says a thing exists. Before a source goes in the
+registry, somebody has to have asked for a real tile and got real bytes back,
+and the entry records which tile and how many bytes:
+
+```python
+TileSource(
+    name="xx-dgm1", **terms("XX"), product=TileProduct.DGM1, tile_km=1,
+    fmt="GeoTIFF",
+    _url=lambda e, n: f"https://…/{e}_{n}.tif",
+    _name=lambda e, n: f"{e}_{n}",
+    vertical_step_m=0.01,
+    probed_bytes=2_558_672,          # what came back
+    probed_tile=(690, 5334),         # when asked for this square kilometre
+)
+```
+
+`geokachel check xx-` then asks again, forever.
+
+## A credit is a licence obligation
+
+`attribution` is required and has no default, on purpose. Put the publisher's
+**exact** wording in it, copied from their own terms page — not a tidied
+version, not a translation. `dl-de/by-2-0` and `CC BY 4.0` both require the
+named credit, and a height shown without it is a height used outside its
+licence.
+
+If a licence forbids this kind of use, or charges for it, the state gets **no
+entry**, however a catalogue describes it. That judgement is made once here so
+that nobody downstream has to make it.
+
+## Three things that will surprise you
+
+They surprised us, each measured rather than assumed:
+
+- **A status code is not an answer.** One state's index lists tiles that 404;
+  another answers a stale row with HTTP 200 and an HTML apology. `health.py`
+  checks the bytes, not the status.
+- **A tile is not always full.** Border tiles come short — 730,232 lines
+  instead of a million — with holes inside a row, and several states emit no
+  NoData marker at all: a cell nobody surveyed is simply an absent line. So
+  values are placed by their own coordinates, never by counting.
+- **Politeness is load-bearing.** Sixteen offices publish this at their own
+  expense, with no quota and no contract. Keep the delay, keep the cap, and set
+  `GEOKACHEL_USER_AGENT` to something with a contact in it.
+
+## Running it
+
+```bash
+pip install -e ".[dev]"
+ruff check . && mypy geokachel && pytest -q
+```
+
+**No test may touch the network.** Archives, grids, indexes and malformed
+headers are all built inside the tests. A suite that needs sixteen state
+portals to be up fails on their maintenance window and teaches people to ignore
+red. Whether the portals still serve what the registry claims is a separate,
+weekly job that opens an issue instead of failing a build.
+
+## Releasing
+
+`pyproject.toml` version, then a tag:
+
+```bash
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+Trusted Publishing does the rest — there is no token. A tag ending in `rc1`
+goes to TestPyPI instead. A PyPI version can never be reused, even after
+deletion, so the tag is the point of no return; CI refuses a tag that does not
+match the version in `pyproject.toml`.
+
+## Where this came from
+
+Extracted from [NinaNatur](https://github.com/JanderHungrige/NinaNatur), a
+garden-planning app that needed to know how much sun a flower bed gets. The
+pre-extraction history, and the design notes behind most of these decisions,
+are in that repository under `.mdd/docs/` — docs 102 to 110.

geokachel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JanderHungrige
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geokachel-0.1.0/NOTICE

@@ -0,0 +1,49 @@
+geokachel
+=========
+
+Copyright (c) 2026 JanderHungrige. Licensed under the MIT License (see LICENSE).
+
+The MIT licence covers **this software**. It does not, and cannot, relicense
+the data this software fetches.
+
+
+The data is somebody else's
+---------------------------
+
+This library fetches open geodata published by the German state surveying
+authorities, by the Bundesamt für Kartographie und Geodäsie, and by the
+Copernicus programme. Each dataset is licensed by whoever published it —
+`dl-de/by-2-0`, `dl-de/zero-2-0` or `CC BY 4.0` — and **most of them require a
+named credit wherever the data is shown**.
+
+A height displayed without its credit is a height used outside its licence.
+
+Every source in this registry carries the exact credit its licence asks for, in
+the words the publisher chose, as a required field on the source itself. It is
+not optional metadata and it is not decoration:
+
+    from geokachel import ground_tiles_for
+    source = ground_tiles_for("BY")
+    print(source.attribution)
+    # Datenquelle: Bayerische Vermessungsverwaltung – www.geodaten.bayern.de
+
+If you show a number this library gave you, show that string with it.
+
+A source whose licence forbids this kind of use is not in the registry at all,
+however a catalogue describes it — that check happens once, here, rather than
+in every program that installs this.
+
+
+Not affiliated
+--------------
+
+geokachel is not affiliated with, endorsed by, or produced by any
+Landesvermessungsamt or Landesbetrieb, the Arbeitsgemeinschaft der
+Vermessungsverwaltungen der Länder der Bundesrepublik Deutschland (AdV), the
+Bundesamt für Kartographie und Geodäsie (BKG), the European Space Agency, or
+the Copernicus programme.
+
+Where those names and brands appear in this software, they appear because a
+licence requires the publisher to be named as the source of the data — never to
+suggest a relationship. In particular the string "GeoBasis-DE" is the surveying
+authorities' own brand and appears only inside the credit that they require.

geokachel-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: geokachel
+Version: 0.1.0
+Summary: Official German open elevation, surface, building and point-cloud data — one interface, all sixteen Bundesländer, with the credit each licence requires.
+Project-URL: Homepage, https://github.com/JanderHungrige/geokachel
+Project-URL: Source, https://github.com/JanderHungrige/geokachel
+Project-URL: Issues, https://github.com/JanderHungrige/geokachel/issues
+Project-URL: Changelog, https://github.com/JanderHungrige/geokachel/releases
+Author: JanderHungrige
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: bundesland,citygml,dem,deutschland,dgm1,dl-de,dom,dsm,dtm,elevation,geodata,geotiff,germany,hoehendaten,laz,lidar,lod2,open-data,opendata,pointcloud,utm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: numpy>=1.26
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# geokachel
+
+**Official German open elevation, surface, building and point-cloud data — one
+interface, all sixteen Bundesländer, with the credit each licence requires.**
+
+Germany publishes superb elevation data and publishes it sixteen different
+ways. Every state runs its own surveying office, and they agree about almost
+nothing: where the UTM zone goes in a filename, whether a tile is one kilometre
+or two, whether a grid starts on an even easting or an odd one, whether you get
+a GeoTIFF or a million lines of text, whether there is a tile to address at all
+or only a twelve-gigabyte regional archive.
+
+This is one interface over all of it, plus a record of which requests were
+actually answered, and when.
+
+```bash
+pip install geokachel
+```
+
+```python
+from geokachel import ground_tiles_for, read_raster, net
+
+source = ground_tiles_for("BY")
+print(source.attribution)
+# Datenquelle: Bayerische Vermessungsverwaltung – www.geodaten.bayern.de
+
+url = source.url_for(690, 5334)          # UTM32 kilometres, Munich
+raster = read_raster(net.get_bytes(url))  # 1000 x 1000 metres of ground
+```
+
+## What is in it
+
+| | states | what you get |
+|---|---|---|
+| **Ground** (DGM1) | **16 — all of them** | 1 m terrain, ±10–30 cm |
+| **Surface** (DOM / nDOM / bDOM) | 15 | what stands on it, 0.2–1 m |
+| **Buildings** (LoD2 CityGML) | 13 | measured height *and* surveyed roof shape |
+| **Point clouds** (LAZ) | 7 | the returns themselves, 4–20 pts/m² |
+
+Plus Copernicus GLO-30 as a worldwide fallback, and the sixteen state coverage
+services (WCS) where a state runs one.
+
+## Three rules it keeps
+
+**An entry is a request that was answered**, dated — never a portal page that
+says a thing exists. Every entry records the tile it was verified at and the
+bytes that came back, which is what makes `geokachel check` possible.
+
+**A credit is a licence obligation, not a caption.** `dl-de/by-2-0` and
+`CC BY 4.0` both require a named credit. A height displayed without it is a
+height used outside its licence, so `attribution` is a required field on every
+source and carries the publisher's exact wording. A source whose licence
+forbids this kind of use is not in the registry at all. See [NOTICE](NOTICE).
+
+**A gap is a gap.** No state borrows its neighbour's ground, and nothing
+unsurveyed is guessed at: it is `NaN`, and it says so.
+
+## Three ways a tile has an address
+
+Handled behind one function, because a caller should not have to care:
+
+- **computed** — the name is arithmetic on two UTM kilometre numbers. Most
+  states. A tile's address is a template and two integers, never a lookup.
+- **listed** — the name carries a survey year (2005 in one tile, 2025 in its
+  neighbour), so the state's own index is read once. What is taken out of it is
+  a *file name*; the scheme, the host and the shape of the address stay ours,
+  so a compromised index cannot redirect a fetch.
+- **archived** — the state publishes no tile at all, only 0.5–12.5 GB regional
+  archives. A zip keeps its index at its **end**, so one member comes out over
+  HTTP range requests: **0.38 % of a 559 MB file**, measured.
+
+## Checking that it is all still there
+
+States move their files. In the two days this registry was built, four of them
+changed underneath it — one moved host entirely, one still lists tiles that
+404, one carries dead share tokens, and one answers a stale row with **HTTP 200
+and an HTML apology**. A checker that read status codes would have called all
+four healthy.
+
+```bash
+geokachel check              # every source, a few kB each, ~2 minutes
+geokachel check sn- rp-      # just these
+geokachel check --quiet      # only what is wrong; exit 1 if anything is
+geokachel credits BY TH      # the exact credit those states require
+```
+
+A source passes only when the bytes are what it claims — `II*` for a TIFF,
+`LASF` for a cloud, a root element for CityGML, numbers for a text grid, a
+directory that still holds the square kilometre it held before.
+
+It is deliberately **not** a test suite: one that needs sixteen state portals
+to be up fails on their maintenance window and teaches people to ignore red.
+It is a command with an exit code, meant for a scheduled job.
+
+## What it deliberately does not do
+
+**It does not choose your coordinate frame.** You get a north-up raster in the
+source's own UTM with `NaN` for unknown. Putting that on your own axes is
+yours, because the right answer differs for a shadow model, a flood model and a
+map — and because UTM grid north is up to 2.3° off true north in Germany, which
+some callers must correct for and others must not.
+
+**It does not geocode.** `state=` is a required argument. A library that
+reverse-geocoded every call would rate-limit whoever looped over ten thousand
+plots, and that is not a failure to inflict from inside a dependency.
+
+**It does not fetch anything itself.** Every function that needs bytes takes a
+callable. `geokachel.net` is a polite default — a pause between requests, a
+size cap, a User-Agent — and you should set `geokachel.net.USER_AGENT` to
+something with your own contact in it before pulling anything in anger. These
+are public offices publishing at their own expense.
+
+## Installing
+
+Requires Python 3.11+. Depends on `numpy`, `defusedxml` and `requests` — no
+GDAL, no rasterio, no pyproj. The GeoTIFF reader and the UTM projection are
+both here, because a hundred-megabyte wheel to read a single-band raster is a
+poor trade.
+
+## Licence
+
+MIT, for the software. The *data* is somebody else's and carries its own terms
+— read [NOTICE](NOTICE) before you publish anything derived from it.
+
+Not affiliated with any Landesvermessungsamt, the AdV, the BKG, ESA or
+Copernicus. Their names appear only inside the credits their licences require.

geokachel-0.1.0/README.md

@@ -0,0 +1,126 @@
+# geokachel
+
+**Official German open elevation, surface, building and point-cloud data — one
+interface, all sixteen Bundesländer, with the credit each licence requires.**
+
+Germany publishes superb elevation data and publishes it sixteen different
+ways. Every state runs its own surveying office, and they agree about almost
+nothing: where the UTM zone goes in a filename, whether a tile is one kilometre
+or two, whether a grid starts on an even easting or an odd one, whether you get
+a GeoTIFF or a million lines of text, whether there is a tile to address at all
+or only a twelve-gigabyte regional archive.
+
+This is one interface over all of it, plus a record of which requests were
+actually answered, and when.
+
+```bash
+pip install geokachel
+```
+
+```python
+from geokachel import ground_tiles_for, read_raster, net
+
+source = ground_tiles_for("BY")
+print(source.attribution)
+# Datenquelle: Bayerische Vermessungsverwaltung – www.geodaten.bayern.de
+
+url = source.url_for(690, 5334)          # UTM32 kilometres, Munich
+raster = read_raster(net.get_bytes(url))  # 1000 x 1000 metres of ground
+```
+
+## What is in it
+
+| | states | what you get |
+|---|---|---|
+| **Ground** (DGM1) | **16 — all of them** | 1 m terrain, ±10–30 cm |
+| **Surface** (DOM / nDOM / bDOM) | 15 | what stands on it, 0.2–1 m |
+| **Buildings** (LoD2 CityGML) | 13 | measured height *and* surveyed roof shape |
+| **Point clouds** (LAZ) | 7 | the returns themselves, 4–20 pts/m² |
+
+Plus Copernicus GLO-30 as a worldwide fallback, and the sixteen state coverage
+services (WCS) where a state runs one.
+
+## Three rules it keeps
+
+**An entry is a request that was answered**, dated — never a portal page that
+says a thing exists. Every entry records the tile it was verified at and the
+bytes that came back, which is what makes `geokachel check` possible.
+
+**A credit is a licence obligation, not a caption.** `dl-de/by-2-0` and
+`CC BY 4.0` both require a named credit. A height displayed without it is a
+height used outside its licence, so `attribution` is a required field on every
+source and carries the publisher's exact wording. A source whose licence
+forbids this kind of use is not in the registry at all. See [NOTICE](NOTICE).
+
+**A gap is a gap.** No state borrows its neighbour's ground, and nothing
+unsurveyed is guessed at: it is `NaN`, and it says so.
+
+## Three ways a tile has an address
+
+Handled behind one function, because a caller should not have to care:
+
+- **computed** — the name is arithmetic on two UTM kilometre numbers. Most
+  states. A tile's address is a template and two integers, never a lookup.
+- **listed** — the name carries a survey year (2005 in one tile, 2025 in its
+  neighbour), so the state's own index is read once. What is taken out of it is
+  a *file name*; the scheme, the host and the shape of the address stay ours,
+  so a compromised index cannot redirect a fetch.
+- **archived** — the state publishes no tile at all, only 0.5–12.5 GB regional
+  archives. A zip keeps its index at its **end**, so one member comes out over
+  HTTP range requests: **0.38 % of a 559 MB file**, measured.
+
+## Checking that it is all still there
+
+States move their files. In the two days this registry was built, four of them
+changed underneath it — one moved host entirely, one still lists tiles that
+404, one carries dead share tokens, and one answers a stale row with **HTTP 200
+and an HTML apology**. A checker that read status codes would have called all
+four healthy.
+
+```bash
+geokachel check              # every source, a few kB each, ~2 minutes
+geokachel check sn- rp-      # just these
+geokachel check --quiet      # only what is wrong; exit 1 if anything is
+geokachel credits BY TH      # the exact credit those states require
+```
+
+A source passes only when the bytes are what it claims — `II*` for a TIFF,
+`LASF` for a cloud, a root element for CityGML, numbers for a text grid, a
+directory that still holds the square kilometre it held before.
+
+It is deliberately **not** a test suite: one that needs sixteen state portals
+to be up fails on their maintenance window and teaches people to ignore red.
+It is a command with an exit code, meant for a scheduled job.
+
+## What it deliberately does not do
+
+**It does not choose your coordinate frame.** You get a north-up raster in the
+source's own UTM with `NaN` for unknown. Putting that on your own axes is
+yours, because the right answer differs for a shadow model, a flood model and a
+map — and because UTM grid north is up to 2.3° off true north in Germany, which
+some callers must correct for and others must not.
+
+**It does not geocode.** `state=` is a required argument. A library that
+reverse-geocoded every call would rate-limit whoever looped over ten thousand
+plots, and that is not a failure to inflict from inside a dependency.
+
+**It does not fetch anything itself.** Every function that needs bytes takes a
+callable. `geokachel.net` is a polite default — a pause between requests, a
+size cap, a User-Agent — and you should set `geokachel.net.USER_AGENT` to
+something with your own contact in it before pulling anything in anger. These
+are public offices publishing at their own expense.
+
+## Installing
+
+Requires Python 3.11+. Depends on `numpy`, `defusedxml` and `requests` — no
+GDAL, no rasterio, no pyproj. The GeoTIFF reader and the UTM projection are
+both here, because a hundred-megabyte wheel to read a single-band raster is a
+poor trade.
+
+## Licence
+
+MIT, for the software. The *data* is somebody else's and carries its own terms
+— read [NOTICE](NOTICE) before you publish anything derived from it.
+
+Not affiliated with any Landesvermessungsamt, the AdV, the BKG, ESA or
+Copernicus. Their names appear only inside the credits their licences require.