Load one state, province or region

Aner Plot now provides 4,838 independently optional subdivision and source unit packs, covering 225 ISO country/territory parents, plus separately identified Kosovo source units. Every one of the existing 249 geographic units has an explicit availability record. The full catalogue has 5,243 selectable map layers in 5,192 optional packs, including the existing country outlines and teaching maps. Use the matching subdivision map enabled native development runtime and notebook integration; these APIs await a public binary release.

The unit of loading is the selected pack. Importing aner.plot opens no boundary file. Creating a Colorado chart reads only region.usa.co; it does not read the USA overview, county/place pack, neighboring states, a continent or the world. Region packs contain one region feature and its provenance. The small compiled registry contains identities and pinned hashes, while boundary coordinates remain outside the executable.

Boulder with one Colorado pack

Copy the matching optional data file to the computer, then install it locally:

aner maps list
aner maps install /media/maps/region.usa.co.anermap

import aner.plot
import aner.geo

plot.map("region.usa.co", keys: List("US-CO"), values: List(12.0))
    .add_points(positions: List(geo.position(longitude: -105.2705, latitude: 40.0150)),
        values: List(18.0), labels: List("Boulder"))
    .point_labels("all")
    .projection("lambert_azimuthal_equal_area")
    .size(width: 900, height: 600)
    .title("Boulder in Colorado: one independently loaded state")
    .caption("Synthetic indices; illustrative Boulder position. Natural Earth 2022 state outline, not a city or street map.")
    .show()

The point has an explicitly supplied latitude and longitude; Aner performs no geocoding. Both values are synthetic teaching indices. The outline is generalized Natural Earth display geometry. A locally centered Lambert azimuthal equal area projection supplies useful regional context without turning the source into a survey or measurement dataset.

For an actual Boulder municipal outline use the existing, separately optional usa.co county/place pack and usa.co.places, with Census place key 0807850. Zooming into a state outline adds no city, road or parcel geometry.

Choose a region by its exact catalogue key

Download the complete region CSV or region and coverage JSON. The inventory supplies each region's name, parent, pack ID, exact join key, source level and code scheme. It contains no boundary coordinates. Look up the desired name first; use the returned ID and key unchanged.

import aner.plot
plot.map("region.chl.rm", keys: List("CL-RM"), values: List(16.0))
    .projection("lambert_azimuthal_equal_area")
    .title("One selected Chilean region").show()

region.chl.rm uses the worldwide single region source and revision. The earlier chile.region.rm retains the existing continental teaching layer geometry. Both load one selected feature, and neither requires chile or country.chl. Do not substitute one archive for the other: their registered IDs, simplification and hashes differ.

Valid, unique source ISO 3166 to 2 codes produce convenient IDs such as region.usa.co. Missing, malformed or duplicated source codes use an explicit provider key instead. For example, Natural Earth assigns AU-NSW to two separate features: mainland New South Wales and Lord Howe Island. The exact keys are region.aus.ne.aus.2654 / AUS-2654 and region.aus.ne.aus.2659 / AUS-2659. No new ISO code is invented, and the two source geometries are not silently merged. These display sources are not a complete or current legal ISO subdivision register.

The same analysis in Aner and notebooks

Use the complete source, the VS Code notebook or the Jupyter notebook. The same seven chart building cells cover Colorado/Boulder, Chile, Argentina, Japan, South Africa, Australia and Scotland. Each cell works independently after the imports. Running every cell intentionally constructs all seven charts and retains their output scenes.

Notebook pan, zoom and label controls use the same offline renderer. Supported SVG and HTML exports retain only the selected geometry; an exported HTML file can be viewed offline without a kernel or installed packs. Rerunning the Aner source still requires its matching pack. Source attribution is retained beside the user caption in SVG, notebook scenes and HTML.

A chart owns the geometry it explicitly loaded. Immutable focus, extent, theme and style changes share that geometry. A chart made from a whole country subdivision layer already retains that country's features: calling .focus(...) changes the viewport. Use a single region pack when the program should materialize only that region. There is no automatic parent or neighboring pack load, online tile request or map service credential.

Coverage has an explicit meaning

The index checks all 249 ISO geographic units and distinguishes:

Some geographic units are themselves French overseas regions. Their shapes appear in France's 18 region layer; the separately indexed GUF, GLP, MTQ, MYT and REU country/area entries are not relabeled as their own internal regions. City states and undivided territories are not given artificial state maps. Antarctica is not divided into claimant regions.

Natural Earth's pinned worldwide states/provinces source contributes 4,536 retained features; 302 supplementary features fill or clarify regional coverage. 60 source placeholders or unnamed/nonregional units are excluded explicitly. The total includes 359 separately described alternative source units. Natural Earth country levels are not uniform: departments, council areas, historical districts and statistical units can occur in its source. source_subdivision in the index means that original level, rather than a guarantee of today's legal ADM1 inventory.

The supplementary layers include France's 18 regions, the UK's 4 constituent countries, Taiwan's 22 counties/municipalities, Niue's 14 village areas, Tuvalu's 8 island councils, the Faroes' 29 municipalities, Puerto Rico's 78 municipios, Guam's 19 municipalities, Palestine's 16 governorates and Kiribati's 24 source island/local units. Palestine governorates and Kiribati local units come from the provider's ADM2 level because its ADM1 layer contains macroterritories or geographic archipelagos. Those source hierarchy choices are disclosed rather than silently called states.

Jersey's 12 parishes, the Bailiwick of Guernsey's three jurisdictions plus ten lower level Guernsey parishes, the Isle of Man's 21 local authority areas, six Cayman districts and three Tokelau atoll/village areas use a dated OpenStreetMap snapshot. British Virgin Islands packs represent five source island groups; Macao packs represent seven historical parishes and the Cotai statistical zone. Svalbard and Jan Mayen are two geographic territory components from Natural Earth admin 0 map units. These distinctions stay visible in pack metadata and the index.

France's Natural Earth departments, UK council areas and Taiwan source subdivisions remain explicitly described alternatives beside the supplementary first order layers. Collections ending in -alternative select those source units; they do not claim another current first order hierarchy. Source vintages range from 2017/2021/2022 snapshots through Census 2025 and explicitly dated 2026 retrievals. Use an authoritative current local dataset for legal, electoral or cadastral decisions.

Prepare only the optional files needed offline

In a source checkout, package one chosen region:

python3 tools/package_maps.py --pack region.usa.co --output build/map-packs
python3 tools/package_maps.py --pack region.chl.rm --output build/map-packs

Collections are authoring/distribution conveniences. regions-chl prepares the independent Chile files, while regions-all prepares all 4,838 files. These are never runtime dependencies of a single pack, and the existing plot teaching collection remains at 23 packs. A user may copy and install just one selected archive from any collection. Geometry is kept out of the executable and no pack is downloaded automatically.

The source authoring tools use hash pinned local inputs and make no network requests. Original source hashes and derived normalization hashes are kept separately in supplementary source metadata. The coverage policy records every excluded placeholder and every country's status. Shared edge simplification happens during authoring, before individual regions are split into independent files.

Optional archives and selected output retain source notices and license links. Full offline source terms are supplied for CC BY 4.0, ODbL 1.0, Etalab Open Licence 2.0 and the Faroese Environment Agency. Natural Earth and U.S. Census data remain public domain. OpenStreetMap derived data retain ODbL attribution and redistribution terms; other optional maps do not acquire those data as dependencies.

See the country outline catalogue, plotting guide and third party notices for source details and the existing map API.