---
name: nominatim_reverse_geocode
kind: function
lang: kt
domain: infra
version: "1.0.0"
purity: impure
signature: "fun nominatimReverseGeocode(lat: Double, lon: Double, lang: String = \"es\"): GeocodedLocation"
description: "Reverse geocoding usando Nominatim (OpenStreetMap). Convierte coordenadas lat/lon a una dirección estructurada (calle, ciudad, país, etc.) para Android/Kotlin sin dependencias externas."
tags: [geocoding, nominatim, openstreetmap, location, address, infra, android, kotlin]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports:
  - "org.json.JSONObject"
  - "java.net.HttpURLConnection"
  - "java.net.URL"
tested: false
tests: []
test_file_path: ""
file_path: "kotlin/functions/infra/nominatim_reverse_geocode.kt"
params:
  - name: lat
    desc: "Latitud en grados decimales (-90.0 a 90.0)."
  - name: lon
    desc: "Longitud en grados decimales (-180.0 a 180.0)."
  - name: lang
    desc: "Código de idioma ISO 639-1 para la respuesta de Nominatim. Por defecto \"es\" (español)."
output: "GeocodedLocation con los campos normalizados: displayName, street, houseNumber, neighbourhood, city, state, country, postcode, lat, lon, osmType, osmId."
---

## Ejemplo

```kotlin
val loc = nominatimReverseGeocode(40.4168, -3.7038)
println(loc.city)        // "Madrid"
println(loc.street)      // "Calle Mayor"
println(loc.country)     // "España"
println(loc.displayName) // cadena completa de Nominatim
```

## Comportamiento

- Realiza GET a `https://nominatim.openstreetmap.org/reverse?format=jsonv2&lat=...&lon=...&accept-language=...&zoom=18`.
- Cabecera `User-Agent: fn_registry/1.0` obligatoria por política de uso de Nominatim.
- Timeout de 5 segundos tanto para conexión como para lectura.
- Usa solo `java.net.HttpURLConnection` y `org.json.JSONObject` — disponibles en el Android SDK sin dependencias externas.
- Resolución de `city`: prueba `address.city` → `address.town` → `address.village` → `""`.
- Resolución de `neighbourhood`: prueba `address.neighbourhood` → `address.suburb` → `""`.
- Lanza `RuntimeException` si el HTTP status no es 200 o si falla la lectura de la respuesta.

## Notas

Función paralela a `nominatim_reverse_geocode_py_infra` pero adaptada para Android/Kotlin.
No llamar desde el hilo principal de Android — usar `Dispatchers.IO` o un `ExecutorService`.
El campo `zoom=18` maximiza el detalle de la dirección (nivel de número de portal).