Datos Geográficos y de Lugares

---

name: Datos Geográficos y de Lugares description: Úsalo cuando una tarea requiera búsquedas geográficas en vivo: "geocodifica esta dirección", "qué hay en estas coordenadas" (geocodificación inversa), "lat/lon para esta ciudad", "en qué país/estado está este código postal", o "datos del país: capital, moneda, población, bandera". Nominatim (OpenStreetMap) es el geocodificador predeterminado; Zippopotam para códigos postales; APICountries para datos de países. Todos sin clave. NO lo uses para el clima en una ubicación - usa weather-climate en su lugar; NO lo uses para estadísticas de país a lo largo del tiempo (PIB, tendencias de población) - usa government-open-data; si la solicitud es un vago "necesito datos en vivo", enruta a través de public-data-api-picker.

¿Qué hace Datos Geográficos y de Lugares?

Convierte nombres de lugares, direcciones, coordenadas y códigos postales en geografía estructurada con APIs sin clave. El error que esto previene: recurrir a la API de Google Maps/Places desde la memoria de entrenamiento - con clave y facturación habilitada - cuando Nominatim responde la misma consulta gratis, o estancarse en cuál de las docenas de geocodificadores listados en directorios realmente funciona.

APIs Clasificadas

1. Nominatim (nominatim.openstreetmap.org) - PREDETERMINADO para geocodificación y geocodificación inversa. Datos de OSM, global, sin clave. Reglas de etiqueto estrictas a continuación.
2. Open-Meteo Geocoder - nombre de ciudad/pueblo → lat/lon únicamente. Más rápido y sin reglas; úsalo cuando la entrada sea un nombre de asentamiento simple en lugar de una dirección o POI.
3. Zippopotam.us - código postal → lugar/estado/coordenadas, 60+ países, sin clave.
4. APICountries (www.apicountries.com) - datos de país: capital, monedas, idiomas, población, banderas, fronteras. Sin clave. (Sirve la misma forma de respuesta que el antiguo REST Countries; REST Countries ahora devuelve errores de obsolescencia sin clave - ver NO USAR.)

Procedimiento

1. Clasifica la entrada: dirección/POI → búsqueda de Nominatim; coordenadas → inversa de Nominatim; nombre de ciudad simple → Open-Meteo Geocoder; código postal → Zippopotam; nombre/código de país → APICountries.
2. Obedecer las reglas de etiqueto de Nominatim - son obligatorias, no sugerencias: máximo 1 solicitud/segundo, un User-Agent real que identifique tu aplicación (los UA anónimos son bloqueados), sin geocodificación masiva de miles de filas. Para un lote, repite con una pausa de 1s o más y menciónalo; para lotes muy grandes, informa al usuario que esto necesita un Nominatim autoalojado o un geocodificador de pago en lugar de golpear la instancia pública.
3. Lee las coordenadas como cadenas de Nominatim - lat/lon vuelven como cadenas JSON, no números. Analízalos antes de hacer operaciones aritméticas.

Pregunta al usuario solo si falta: la entrada de lugar/coordenada en sí, y el contexto del país para nombres ambiguos ("Springfield" - por defecto: toma el resultado principal de Nominatim y di cuál fue).

Plantillas de URL + formas de respuesta reales

Geocodificar (búsqueda):

https://nominatim.openstreetmap.org/search?q={URL-encoded query}&format=jsonv2&limit=1

[{"lat":"48.8582599","lon":"2.2945006","name":"Tour Eiffel",
  "display_name":"Tour Eiffel, 5, Avenue Anatole France, ..., 75007, France",
  "category":"man_made","type":"tower","importance":0.62}]

El nivel superior es un array; array vacío = sin coincidencia. Agrega &addressdetails=1 para un objeto address estructurado, &countrycodes=us para restringir el país.

Geocodificación inversa:

https://nominatim.openstreetmap.org/reverse?lat={lat}&lon={lon}&format=jsonv2

Devuelve un solo objeto (no un array): display_name, más address.{road,city,state,postcode,country_code} con &addressdetails=1 (activado por defecto para inversa).

Nombre de ciudad → lat/lon (cuando no necesitas direcciones completas):

https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1

{"results":[{"name":"Berlin","latitude":52.52437,"longitude":13.41053,
  "country_code":"DE","timezone":"Europe/Berlin","population":3426354}]}

Sin clave results cuando no hay coincidencias - verifica la clave, no un array vacío.

Código postal:

https://api.zippopotam.us/{country}/{code}        ← p.ej. /us/90210, /de/10115

{"country":"United States","places":[{"place name":"Beverly Hills",
  "state":"California","state abbreviation":"CA","latitude":"34.0901","longitude":"-118.4065"}]}

Trampas: las claves contienen espacios ("place name", "post code"); las coordenadas son cadenas; los códigos desconocidos devuelven 404 con cuerpo vacío, no JSON.

Datos de país:

https://www.apicountries.com/name/{name}      ← difuso, devuelve array
https://www.apicountries.com/alpha/{code}     ← ISO alfa-2/alfa-3, devuelve objeto

[{"name":"Japan","capital":"Tokyo","region":"Asia","population":126476461,
  "currencies":[{"code":"JPY","symbol":"¥"}],"languages":[{"name":"Japanese"}],
  "alpha2Code":"JP","flags":{"png":"https://flagcdn.com/w320/jp.png"}}]

Entregable

El resultado estructurado (coordenadas como números, partes de la dirección o datos del país) más la URL exacta utilizada. Para lotes: el bucle realmente limitado, con la velocidad indicada.

NO USAR - usa X en su lugar

• Google Maps / Places, Mapbox, HERE - con clave y facturación; todo lo anterior es gratis. No envíes a un usuario a registrarse.
• REST Countries (restcountries.com) - sus endpoints clásicos devuelven errores de obsolescencia y el reemplazo requiere una clave de autenticación; APICountries sirve la misma forma sin clave.
• ip-api.com y la mayoría de niveles gratuitos de geolocalización IP - solo HTTP en el nivel gratuito (falla cualquier requisito HTTPS); este skill no incluye ninguna API de geolocalización IP.
• Clima en la ubicación que acabas de geocodificar - weather-climate.
• Estadísticas de país en series temporales - government-open-data.

Nivel de calidad

• Las llamadas a Nominatim llevan un User-Agent real y nunca superan 1 solicitud/segundo - incluso dentro de bucles.
• Las coordenadas de cadena se analizan a números antes de cualquier operación matemática.
• Los nombres de lugares ambiguos se resuelven en voz alta ("tomó Springfield, Illinois - el resultado principal de Nominatim").

Obtenido y verificado en vivo del proyecto public-apis (MIT).