---

name: mapping-geocoding description: "Use when plotting GeoPandas data, building interactive maps, classifying choropleths, adding tile context, or geocoding and reverse-geocoding addresses." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

Mapping and Geocoding

Use this sub-skill when the task turns GeoPandas data into static/interactive maps or uses geocoding providers to convert between addresses and coordinates.

Read First

• Visualization and geocoding reference: API notes for .plot(), .explore(), choropleths, classification, tiles, geocode, and reverse_geocode.
• Workflows: recipes for static maps, interactive maps, optional-dependency checks, no-network geocoding tests, and safe provider usage.
• Troubleshooting: missing matplotlib/folium/mapclassify/geopy, display issues, CRS/tile problems, provider errors, rate limits, and API-key boundaries.
• check_mapping_optional_deps.py: reports optional visualization/geocoding modules.
• mock_geocode_smoke.py: validates GeoPandas geocoding result handling without calling a real provider.

Route Here When

• The user asks for GeoDataFrame.plot, GeoSeries.plot, choropleth maps, legends, colormaps, classification schemes, or matplotlib axes handling.
• The task mentions GeoDataFrame.explore, folium, interactive HTML maps, tiles, mapclassify, basemaps, or xyzservices providers.
• The task uses geopandas.tools.geocode, reverse_geocode, geopy providers, provider kwargs, timeouts, rate limits, or address-to-point conversion.
• The problem is an optional mapping/geocoding dependency error or a network/provider boundary.

Route Elsewhere

• Use ../core-data-model/SKILL.md for CRS assignment/reprojection and geometry-column repairs before plotting.
• Use ../spatial-operations/SKILL.md for clipping, joins, dissolves, simplification, or metric preprocessing before map output.
• Use ../io-formats/SKILL.md for saving map input/output vector data.
• Use ../validation-testing/SKILL.md for assertions around map/geocode outputs.

Default Operating Rules

1. Check optional dependencies before planning a map output. Static plots require matplotlib; interactive explore() workflows commonly need folium/branca/mapclassify and sometimes tile-provider packages.
2. Reproject to an appropriate display CRS when tiles or metric styling require it, but preserve original analysis data when needed.
3. Downsample or simplify large geometries before interactive maps if performance matters.
4. Treat geocoding as a network/service workflow. Specify provider, timeout, API key/credentials policy, rate limits, and terms of service.
5. Do not call real geocoding providers in tests or smoke scripts. Use mocked provider behavior for validation.
6. Keep map output expectations explicit: matplotlib Axes, folium map object, HTML file, or serialized vector data.

Minimal Checks

python scripts/check_mapping_optional_deps.py --json
python scripts/mock_geocode_smoke.py --json

The mock geocode smoke returns success without network if geopy is available; if it is missing, it reports a skipped optional workflow unless --require-geopy is used.

Handoff

• Prepare and validate input layers with core-data-model and spatial-operations before plotting.
• Use io-formats for input/output data files.
• Use validation-testing to compare expected geocoded GeoDataFrames or geometry outputs.