---
name: nominatim_reverse_geocode
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def nominatim_reverse_geocode(lat: float, lon: float, lang: str = 'es') -> dict"
description: "Reverse geocoding usando Nominatim (OpenStreetMap). Convierte coordenadas lat/lon a una dirección estructurada con calle, ciudad, país y otros campos normalizados."
tags: [geocoding, nominatim, openstreetmap, osm, reverse-geocoding, geo, location, address]
params:
  - name: lat
    desc: "Latitud en grados decimales (rango -90 a 90)."
  - name: lon
    desc: "Longitud en grados decimales (rango -180 a 180)."
  - name: lang
    desc: "Código de idioma ISO 639-1 para la respuesta (ej: 'es', 'en', 'fr'). Por defecto 'es'."
output: "Diccionario con campos normalizados: display_name (dirección completa legible), street (calle/road), house_number, neighbourhood, city (city→town→village), state, country, postcode, lat, lon, osm_type (node/way/relation), osm_id. Campos ausentes retornan string vacío."
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["urllib.request", "urllib.parse", "json"]
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/infra/nominatim_reverse_geocode.py"
---

## Ejemplo

```python
from infra.nominatim_reverse_geocode import nominatim_reverse_geocode

addr = nominatim_reverse_geocode(40.4168, -3.7038)
# {
#   "display_name": "Puerta del Sol, Sol, Madrid, ...",
#   "street": "Puerta del Sol",
#   "house_number": "",
#   "neighbourhood": "Sol",
#   "city": "Madrid",
#   "state": "Comunidad de Madrid",
#   "country": "España",
#   "postcode": "28013",
#   "lat": 40.4168,
#   "lon": -3.7038,
#   "osm_type": "way",
#   "osm_id": 12345678
# }

# Con idioma inglés
addr_en = nominatim_reverse_geocode(48.8566, 2.3522, lang="en")
# {"city": "Paris", "country": "France", ...}
```

## Notas

- Usa `urllib.request` de stdlib — sin dependencias externas.
- El header `User-Agent: fn_registry/1.0` es obligatorio según la política de uso de Nominatim.
- Timeout de 5 segundos. Para coordenadas en zonas remotas puede necesitarse más.
- Campo `city` se resuelve con fallback: `city → town → village → ""`.
- `lat`/`lon` del resultado son los del objeto OSM encontrado, que puede diferir ligeramente de los de entrada.
- Nominatim tiene límite de 1 request/segundo por IP. Para uso intensivo, considerar un servidor propio.
- Lanza `RuntimeError` en errores HTTP o de red.