---
name: add_basemap_osm
kind: function
lang: py
domain: geo
version: "1.0.0"
purity: impure
signature: "def add_basemap_osm(ax: Axes, zoom: int = 9, cache_dir: str | Path | None = None) -> None"
description: "Añade un basemap OpenStreetMap Mapnik a un Axes de matplotlib usando contextily. Captura silenciosamente errores de red — nunca lanza."
tags: [geo, visualization, basemap, osm, contextily, matplotlib]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["contextily", "matplotlib"]
params:
  - name: ax
    desc: "matplotlib Axes con extensión proyectada. El CRS debe ser EPSG:3857 para coincidir con los tiles OSM."
  - name: zoom
    desc: "Nivel de zoom de los tiles (1-19). A mayor zoom, mayor resolución pero más requests."
  - name: cache_dir
    desc: "Directorio opcional para cachear tiles descargados. None usa el cache por defecto de contextily."
output: "None. Modifica el Axes in-place añadiendo el basemap como imagen de fondo."
tested: true
tests:
  - "no lanza excepción con Axes válido"
test_file_path: "python/functions/geo/tests/test_add_basemap_osm.py"
file_path: "python/functions/geo/add_basemap_osm.py"
source_repo: "internal:footprint_aurgi"
source_license: "internal-aurgi"
source_file: "ponderacion_isochronas/src/recomendador_centros.py:220"
---

## Ejemplo

```python
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from geo.add_basemap_osm import add_basemap_osm

fig, ax = plt.subplots()
ax.set_xlim(-430000, -350000)
ax.set_ylim(4500000, 4600000)
add_basemap_osm(ax, zoom=10)
fig.savefig("mapa.png")
```

## Notas

Requiere contextily. Si contextily no está instalado, retorna sin hacer nada. Errores de red (timeout, sin conexión, tile no disponible) se capturan con `except Exception: pass` para no interrumpir el pipeline de generación de reportes.