🌍 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.

The primary goal is to help you learn geography for GeoGuessr, which guides the selection of countries and subdivisions supported below.

🌐 Current country coverage

• Indonesia: kabupaten (regencies) and kota (cities), below provinces.
• Philippines: provinces.
• Bangladesh: districts.
• Germany: Landkreise (districts) and kreisfreie Städte (independent cities).
• Japan: prefectures.
• India: districts.
• Romania: județe (counties) and the municipality of Bucharest.

More countries are planned.

🚀 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.

India

Front: India: वाराणसी

Back: Varanasi — Uttar Pradesh

Varanasi is highlighted on a map of Uttar Pradesh, with reference cities marked.

District names on fronts use Devanagari in the Hindi-language states, Maharashtra, Goa and Sikkim; Bengali in West Bengal and Tripura; and English elsewhere.

Romania

Front: Romania: Bistrița-Năsăud

Back: Bistrița-Năsăud

Bistrița-Năsăud is highlighted on a map of the whole country, with reference cities marked.

📦 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
• India: example input · generated deck
• Romania: 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
• India: district names
• Romania: county and municipality names

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.

Country-specific details

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.

For India, targets accept English or supported native district names, names qualified as District — State, or LGD district codes. Fronts use Devanagari in the Hindi-language states, Maharashtra, Goa and Sikkim; Bengali in West Bengal and Tripura; and English elsewhere. Backs show the English district and state or union territory, with a map of that state or territory.

For Romania, targets accept Romanian names with or without diacritics, ISO county codes, and Bucharest for București. All 41 counties and Bucharest are supported; maps always show the whole country.

📍 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.

India uses Survey of India boundaries from ramSeraph / DataMeet's district collection, released 2023-12-11: 731 districts in a historical snapshot, excluding later changes. Native names are curated; bundled Noto Sans Devanagari and Noto Sans Bengali fonts use SIL OFL 1.1. See source notes for coverage and licensing details.

Romania county boundaries come from Natural Earth's public-domain 1:10m admin-1 layer. Romanian names retain their diacritics; boundaries are generalized for display.

💻 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.