🌍 Geo Anki

🗺️ Overview

Generate map-based Anki flashcards from real geographic boundary data. Choose the subdivisions you want to learn and export a deck with embedded maps. Cards show the country and subdivision on the front, and a highlighted map on the back.

🚀 Getting started

Geo Anki is available on PyPI.

• To install Geo Anki, see Installation.
• To create a deck, see Usage.

🖼️ Example flashcards

Indonesia

Front: Indonesia: Muaro Jambi

Back: Kabupaten Muaro Jambi — Jambi

Here, Jambi is the province, highlighted with a pale fill and bold outline.

Philippines

Front: Philippines: Camarines Sur

Back: Camarines Sur

Camarines Sur is highlighted in orange on a map of the whole Philippines.

The map also names a reference city or town for the province.

Bangladesh

Front: Bangladesh: ঢাকা

Back: Dhaka

Dhaka district is highlighted in orange on a map of the whole country, with reference cities marked. Card fronts use the English country name followed by the Bengali district name; map titles show both Bengali and English names.

Germany

Front: Germany: Nordfriesland

Back: Kreis Nordfriesland — Schleswig-Holstein

The district is highlighted on a map of its entire Bundesland, with fixed reference cities for that state.

Japan

Front: Japan: 広島県

Back: Hiroshima

Hiroshima is highlighted on a map of Japan's main islands, with reference cities and Okinawa in a boxed inset. Remote southern and southeastern islands are omitted. Card fronts use Japanese prefecture names; map titles show Japanese and English.

📦 Installation

Requires Python 3.12+. Install the current release from PyPI:

pip install geo-anki

For development installation, see Development.

🃏 Usage

Generate a deck using the example Indonesia selection:

geo_anki \
  --country indonesia \
  --targets examples/indonesia.txt \
  --output outputs/indonesia.apkg

--targets accepts your own UTF-8 text file with one subdivision name per line. For Indonesia, use kabupaten/kota names without a province. For example:

Kutai Kartanegara
Muaro Jambi

Each supported country has a sample selection of 10 subdivisions in examples/, with generated decks in examples/outputs/:

• Indonesia: example input · generated deck
• Philippines: example input · generated deck
• Bangladesh: example input · generated deck
• Germany: example input · generated deck
• Japan: example input · generated deck

Copy or edit an example input to choose your own subdivisions.

🧭 Build your own selection: targets/ contains the full lists, with the exact dataset spellings to copy into your target file.

• Indonesia: kabupaten/kota names
• Philippines: province names
• Bangladesh: district names
• Germany: district names
• Japan: prefecture names

We recommend using an AI chatbot of your choice to filter a list from targets/ into the subset you want, for example, "only Java kabupaten & kota". Save the resulting list as your --targets file.

Boundary data downloads automatically and is cached locally. Unknown or ambiguous names raise an error. The command produces an .apkg to import into Anki, PNG maps, and a JSON manifest. Run geo_anki --help for additional options.

For Bangladesh, target files accept either Bengali or English district names.

For Japan, target files accept English or Japanese prefecture names (including Japanese names without their suffix) and two-digit JIS codes. Card fronts use the Japanese name, while backs show its English name and a map with reference cities and a boxed Okinawa inset. Remote southern and southeastern islands are omitted. Map titles show both names.

For Germany, a shared name such as München selects the Landkreis; München (kreisfreie Stadt) selects the separate city. Official five-digit district codes (AGS) are also accepted.

📍 Data sources

Geo Anki's code is MIT-licensed; third-party data and fonts retain their own terms. See Third-party notices for source and license links, attribution, and outstanding source-license verification.

Indonesia boundaries come from Indonesia-Geojson-2026 (MIT; mashadinoor and ardian28). Coverage may be incomplete or outdated.

Philippines boundaries come from philippines-json-maps (PSGC 3Q 2026; MIT maps by James Faeldon), based on NAMRIA and PSA boundaries via OCHA COD-AB (CC BY-IGO 3.0).

Bangladesh district boundaries and bilingual names come from bangladesh-geocode (MIT; Nuhil Mehdy). Bengali text uses the bundled Noto Sans Bengali font (SIL Open Font License 1.1).

Germany uses BKG VG250 state and district boundaries (2026-01-01), converted to GeoJSON by Michael Kreil. © GeoBasis-DE / BKG 2026 (Daten verändert), licensed under Datenlizenz Deutschland – Namensnennung 2.0.

Japan prefecture boundaries come from MLIT National Land Numerical Information (N03, 2019-01-01), converted by Fabio Crisci in open-data-jp-prefectures-geojson (MIT conversion; MLIT source and terms). Japanese text uses a renamed subset of Noto Sans CJK JP, bundled under the SIL Open Font License 1.1.

💻 Development

Clone the repository and install its dependencies with uv:

git clone https://github.com/chrbrunk/geo-anki.git
cd geo-anki
uv sync --locked

From a repository checkout, use uv run geo_anki instead of geo_anki for the commands in Usage.

After setup, install the Git hooks once per checkout:

uv run pre-commit install

Hooks check configuration files, merge conflicts, filename case conflicts, debugger statements, whitespace, Ruff linting and formatting, and ty types. Commit messages must follow Conventional Commits, for example feat: add a country or fix: correct a map label. To run all configured checks across the repository manually:

uv run pre-commit run --all-files

Tox tests the built wheel with independently resolved dependencies on Python 3.12–3.15 in CI, without using uv.lock. To run locally (requires those Python versions), use uvx tox; for just Python 3.12, use uvx tox -e py312.