Location

location abstrae la jerarquía geográfica completa: país → región → provincia → municipio. Es el punto de entrada recomendado para cualquier flujo que dependa de normativa territorial.

Base URL: /api/v1/location

Estructura del geo_id

El identificador geográfico es semántico y lleva prefijo de país:

ES              → País (España)
ES-AN           → Comunidad autónoma (Andalucía)
ES-41           → Provincia (Sevilla)
ES-41091        → Municipio (Mairena del Aljarafe)

Este esquema permite expandir a otros territorios sin cambiar la API:
PT-110300 (Lisboa), CL-13101 (Santiago de Chile).

---

GET /api/v1/location/search

GET Buscar ubicaciones

Busca en texto libre cualquier entidad geográfica: municipio, provincia, comunidad o país. Es el punto de entrada para developers que no conocen el geo_id de antemano. Insensible a acentos y mayúsculas. Devuelve hasta 50 resultados.

Parámetros de query

Parámetro	Tipo	Requerido	Descripción
q	string	Sí	Texto libre. Acepta nombres parciales, con o sin tildes
level	string	No	Filtra por nivel: country | region | province | municipality
ancestor_id	string	No	Restringe la búsqueda dentro de una geografía padre (ej. ES-41 para buscar solo en Sevilla)

Cabeceras

Cabecera	Requerida	Descripción
Authorization	Sí	Bearer sk-normatia-xxxxx

Ejemplo de request

GET /api/v1/location/search?q=villanueva&ancestor_id=ES-41
Authorization: Bearer sk-normatia-xxxxx

Respuesta 200

{
  "results": [
    {
      "geo_id": "ES-41102",
      "name": "Villanueva del Ariscal",
      "level": "municipality"
    },
    {
      "geo_id": "ES-41903",
      "name": "Villanueva del Río y Minas",
      "level": "municipality"
    }
  ]
}

Campos de respuesta

Campo	Tipo	Descripción
results	array	Lista de coincidencias ordenadas por relevancia
results[].geo_id	string	Identificador semántico único
results[].name	string	Nombre original de la entidad geográfica
results[].level	string	country | region | province | municipality

Note

Si hay múltiples resultados, el developer presentará las opciones al usuario para que elija. Si no hay resultados, devuelve array vacío — nunca lanza error en búsquedas de texto libre.

---

GET /api/v1/location/{geo_id}

GET Detalle de ubicación

Devuelve el contexto técnico completo de una localización y las normativas que le aplican, resolviendo la herencia territorial (un municipio hereda las normativas de su provincia, comunidad autónoma y país).

Este es el endpoint más importante del flujo: alimenta tanto la interfaz de usuario como el contexto que se pasa al RAG en /verify.

Parámetros de ruta

Parámetro	Tipo	Descripción
geo_id	string	ID semántico de cualquier nivel geográfico. Ej: ES-41091

Cabeceras

Cabecera	Requerida	Descripción
Authorization	Sí	Bearer sk-normatia-xxxxx

Ejemplo de request

GET /api/v1/location/ES-41091
Authorization: Bearer sk-normatia-xxxxx

Respuesta 200

{
  "geo_id": "ES-41091",
  "name": "Mairena del Aljarafe",
  "level": "municipality",
  "ancestors": [
    { "geo_id": "ES-41", "name": "Sevilla",   "level": "province" },
    { "geo_id": "ES-AN", "name": "Andalucía", "level": "region"   },
    { "geo_id": "ES",    "name": "España",    "level": "country"  }
  ],
  "tech_data": {
    "climate_zone": "B4",
    "altitude_m": 114,
    "seismic_zone": "A",
    "radon_zone": 1,
    "population": 45823
  },
  "applicable_codes": [
    {
      "slug": "cte-db-he",
      "title": "CTE DB-HE — Ahorro de Energía",
      "normative_scope": "national",
      "match_reason": "España"
    },
    {
      "slug": "pgou-mairena",
      "title": "PGOU Mairena del Aljarafe",
      "normative_scope": "municipal",
      "match_reason": "Mairena del Aljarafe"
    }
  ]
}

Campos de respuesta

Campo	Tipo	Descripción
geo_id	string	Identificador semántico
name	string	Nombre de la localización
level	string	Nivel geográfico
ancestors	object[]	Cadena jerárquica completa, de más cercana a más amplia
ancestors[].geo_id	string	ID del nivel ancestral
ancestors[].name	string	Nombre del nivel
ancestors[].level	string	Nivel geográfico
tech_data	object | null	Datos técnicos del territorio. Solo presente en municipios
tech_data.climate_zone	string	Zona climática (ej. B4)
tech_data.altitude_m	integer	Altitud en metros
tech_data.seismic_zone	string	Zona sísmica
tech_data.radon_zone	integer	Zona de radón (1–3)
tech_data.population	integer	Población del municipio
applicable_codes	object[]	Normativas aplicables, resolviendo la jerarquía territorial
applicable_codes[].slug	string	Slug de la normativa
applicable_codes[].title	string	Título completo
applicable_codes[].normative_scope	string	Ámbito de la normativa
applicable_codes[].match_reason	string	Nivel geográfico que origina la aplicación

Errores

Status	Código	Condición
404	not_found	El geo_id no existe
403	country_mismatch	El geo_id pertenece a un país distinto al de la key