---
name: overpass_nearby_pois
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "overpass_nearby_pois(lat: float, lon: float, radius_m: int = 500, categories: list[str] | None = None) -> list[dict]"
description: "Consulta la Overpass API (OpenStreetMap) para obtener POIs cercanos a una coordenada. Soporta 16 categorias mapeadas a tags OSM (amenity, tourism, historic, leisure, shop). Sin dependencias externas, solo stdlib."
tags: [osm, openstreetmap, overpass, poi, geolocation, nearby, geocoding, infra, http, stdlib]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["json", "urllib.error", "urllib.parse", "urllib.request"]
params:
  - name: lat
    desc: "latitud del punto central de busqueda (grados decimales, -90 a 90)"
  - name: lon
    desc: "longitud del punto central de busqueda (grados decimales, -180 a 180)"
  - name: radius_m
    desc: "radio de busqueda en metros alrededor del punto central (defecto 500)"
  - name: categories
    desc: "lista de categorias a buscar entre: restaurant, cafe, bar, museum, monument, park, library, theatre, cinema, gallery, historic, tourism, shop, hotel, pharmacy, hospital. Si es None, usa todas las categorias comunes excepto hotel, pharmacy, hospital"
output: "lista de dicts con campos id (int), lat (float), lon (float), name (str), category (str) y tags (dict con todos los tags OSM del nodo)"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/infra/overpass_nearby_pois.py"
---

## Ejemplo

```python
from infra.overpass_nearby_pois import overpass_nearby_pois

# POIs en el centro de Madrid (radio 300m)
pois = overpass_nearby_pois(40.4168, -3.7038, radius_m=300, categories=["museum", "monument"])
# [{"id": 123, "lat": 40.417, "lon": -3.704, "name": "Museo del Prado", "category": "museum", "tags": {...}}, ...]

# Todos los tipos comunes en radio 500m (defecto)
all_pois = overpass_nearby_pois(48.8566, 2.3522)

# Bares y restaurantes cerca de la Sagrada Familia
food = overpass_nearby_pois(41.4036, 2.1744, radius_m=200, categories=["restaurant", "cafe", "bar"])
```

## Mapeo de categorias a tags OSM

| Categoria   | Tag OSM              |
|-------------|----------------------|
| restaurant  | amenity=restaurant   |
| cafe        | amenity=cafe         |
| bar         | amenity=bar          |
| museum      | tourism=museum       |
| monument    | historic=monument    |
| park        | leisure=park         |
| library     | amenity=library      |
| theatre     | amenity=theatre      |
| cinema      | amenity=cinema       |
| gallery     | tourism=gallery      |
| historic    | historic=*           |
| tourism     | tourism=*            |
| shop        | shop=*               |
| hotel       | tourism=hotel        |
| pharmacy    | amenity=pharmacy     |
| hospital    | amenity=hospital     |

## Notas

Solo usa stdlib (urllib.request, urllib.parse, json). Sin dependencias externas.

La query Overpass QL usa union de nodos `(node[...]; node[...];)` con `out body` para obtener coordenadas y tags completos.

El endpoint publico `https://overpass-api.de/api/interpreter` tiene rate limits informales — para uso intensivo considerar un servidor Overpass propio o la instancia de kumi.systems.

El campo `category` refleja la primera coincidencia en el diccionario interno `_CATEGORY_TAGS`, que sigue el orden de insercion de Python 3.7+. Si un nodo tiene multiples tags relevantes (ej: un bar que tambien es restaurante), la categoria asignada sera la primera que matchee.

Timeout hardcodeado a 10 segundos tanto en la directiva Overpass QL `[timeout:10]` como en `urlopen(timeout=10)`.