Documentación API

Referencia completa de la API catastral

Base URL

https://api.parcelgps.com

Códigos de país

Los endpoints aceptan ?country=XX. Es opcional: sin él, la API detecta el país por la forma de la referencia en 21 países. Si la referencia es ambigua responde 300 CNV_AMBIGUOUS con los candidatos; si es de un país sin cobertura, 422 CNV_COVERAGE; si parece un nombre de lugar, 422 CNV_PLACE_NAME con el punto geocodificado. La España peninsular usa ES, pero el País Vasco y Navarra tienen catastro propio (foral) y requieren su propio código: con ES sus parcelas no se encuentran.

ES · EspañaPV · País VascoNA · NavarraPT · PortugalFR · FranciaIT · ItaliaDE · AlemaniaAT · AustriaPL · PoloniaNL · Países BajosCZ · ChequiaFI · FinlandiaBE · BélgicaEE · EstoniaSI · EsloveniaLT · LituaniaLU · LuxemburgoSK · EslovaquiaBG · BulgariaCY · ChipreIS · IslandiaLI · LiechtensteinCH · Suiza

Referencia de endpoints

MétodoEndpointAuthDescripción
GET/api/resolve?q=TEXTAPI KeyClasifica cualquier texto: referencia (y país), coordenadas o topónimo. Sin cuota.
GET/api/catastro/:refcatAPI KeyConsulta de parcela
GET/api/catastro/:refcat/polygon?country=XXAPI KeyGeometría de la parcela (GeoJSON)
GET/api/catastro/:refcat/solar?country=XXAPI KeyPotencial solar
GET/api/catastro/:refcat/agro?country=XXAPI KeyDatos agrícolas del suelo
GET/api/export/kml?refcat=X&country=XAPI KeyExportar KML/GPX/PDF/DXF
GET/api/catastro/:refcat/market?country=XXWeb y appDatos de mercado (no vía API)
GET/api/catastro/:refcat/score?country=XXWeb y appScore de inversión (no vía API)

Fiabilidad

Qué servimos desde nuestra propia infraestructura y qué depende de un organismo público. Si vas a producción, esto es lo que conviene saber antes.

EndpointDe dónde salen los datos
/catastro/:refcat (ES)Copia propia del catastro (50,9 M de parcelas). No depende del Catastro para responder.
/polygon · /search/address · /search/coordinatesCatastro (organismo público). Puede fallar sin previo aviso.
/agroSIGPAC
/solarPVGIS

Errores y reintentos

Un 503 significa que una fuente oficial no responde en ese momento: reinténtalo con espera creciente y volverá solo. Un 429 es tu cuota, y reintentar no la devuelve — espera al reinicio o sube de plan. Un 404 es una referencia que no existe y no debe reintentarse.

Página de estado

Publicamos el estado de nuestra API y de las nueve fuentes catastrales de las que dependemos, comprobado cada cinco minutos y alojado fuera de esta API para que siga siendo fiable durante una caída: catastrogps.es/status.

Autenticación

Todas las peticiones a la API requieren una API key enviada en la cabecera X-API-Key.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S"

Obtiene tu API key gratuita en tu panel de desarrollador.

Códigos de error

EstadoCódigoDescripción
200—OK — La petición se ha completado correctamente.
400VALIDATION_ERRORBad Request — Parámetros inválidos o referencia catastral con formato incorrecto.
401UNAUTHORIZEDUnauthorized — API key inválida, expirada o no proporcionada.
404NOT_FOUNDNot Found — No se encontró la parcela con la referencia o coordenadas indicadas. No gasta cuota.
429KEY_AUTH_004Quota Exceeded — Has alcanzado el límite mensual de tu plan. Comprueba las cabeceras X-RateLimit-Remaining y X-RateLimit-Reset para saber cuándo se reinicia.
429RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHEDToo Many Requests — Límite de búsquedas gratuitas por IP y día (tier gratuito). Con API key se aplica la cuota mensual del plan (arriba).
500INTERNAL_ERRORInternal Server Error — Error en nuestro servidor. Si persiste, contacta con soporte.
503SERVICE_UNAVAILABLEService Unavailable — El servicio catastral externo del país consultado no está disponible temporalmente. Estos servicios los gestionan organismos públicos (Catastro, DGT, Géoportail, Agenzia Entrate, ALKIS...) y están fuera de nuestro control. Reintenta en unos minutos.

Cabeceras de rate limit

Cada respuesta incluye cabeceras que indican el estado de tu cuota:

CabeceraDescripción
X-RateLimit-LimitLímite mensual total de tu plan (p. ej. 5000).
X-RateLimit-RemainingLlamadas restantes este mes.
X-RateLimit-ResetFecha de reinicio de la cuota (ISO 8601).
X-Quota-TierNombre del tier actual (free, basic, pro, business).

España (ES)

Catastro español — Dirección General del Catastro

GET/api/catastro/:refcat

Obtener datos de parcela por referencia catastral (14 o 20 caracteres).

Parámetros

:refcatstringReferencia catastral (p. ej. 9872023VH5797S0001WX)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "9872023VH5797S0001WX",
    "direccion": "CL GLORIA 51",
    "codigoPostal": "13730",
    "municipio": "SANTA CRUZ DE MUDELA",
    "provincia": "CIUDAD REAL",
    "latitud": 38.640143,
    "longitud": -3.463284,
    "googleMapsUrl": "https://www.google.com/maps?q=38.640143,-3.463284",
    "uso": "Residencial",
    "clase": "Urbano",
    "superficieConstruida": 308,
    "superficieParcela": 397,
    "anioConstruccion": 1980,
    "coefParticipacion": "100",
    "poligono": [ /* geometría de la parcela */ ],
    "availableFields": {
      "uso": true, "clase": true, "anioConstruccion": true,
      "superficieConstruida": true, "coefParticipacion": true,
      "direccion": true, "busquedaDireccion": true
    }
  },
  "searchesRemaining": 4
}

Errores posibles

CódigoHTTPDescripción
VALIDATION_ERROR400La referencia no tiene un formato válido para el país.
NOT_FOUND404Referencia no encontrada. Un ?country no soportado se trata como España (ES) y normalmente devuelve NOT_FOUND; usa ES/PT/FR/IT/DE/PV/NA. En catastros forales (NA, PV) el campo message añade una pista de formato.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Límite de búsquedas gratuitas por IP y día.
KEY_AUTH_004429Cuota mensual de la API key agotada (ver cabeceras X-RateLimit-*).
SERVICE_UNAVAILABLE503El servicio catastral oficial del país está caído o en mantenimiento. Reintentar.
POST/api/search/coordinates

Geocodificación inversa: encontrar la parcela catastral en unas coordenadas GPS.

Parámetros

latitudenumberLatitud (WGS84)
longitudenumberLongitud (WGS84)
countrystringCódigo de país (opcional: se detecta por la referencia)
curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 40.4168, "longitude": -3.7038, "country": "ES"}' \
  "https://api.parcelgps.com/api/search/coordinates"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "referenciaCatastral": "9872023VH5797S0001WX",
    "refCat14": "9872023VH5797S",
    "direccion": "CL GRAN VIA 1",
    "municipio": "MADRID",
    "tipoInmueble": "",
    "coordenadas": { "latitud": 40.4168, "longitud": -3.7038 },
    "googleMapsUrl": "https://maps.google.com/?q=40.4168,-3.7038"
  },
  "searchesRemaining": 3
}

Errores posibles

CódigoHTTPDescripción
VALIDATION_ERROR400Coordenadas fuera de los límites del país indicado o detectado, o lat/lng ausentes o mal formadas.
NOT_FOUND404No hay ninguna parcela en esas coordenadas.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Límite de búsquedas gratuitas por IP y día.
SERVICE_UNAVAILABLE503Servicio catastral no disponible temporalmente.
POST/api/search/address/parse

Buscar parcela catastral por dirección postal.

Parámetros

direccionstringDirección en texto libre (solo España). Formato recomendado: «Calle, Número, Municipio» — p. ej. «Calle Mallorca, 213, Barcelona». El número también puede ir pegado a la calle («Gran Vía 1, Madrid»).
curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direccion": "Gran Via 1, Madrid"}' \
  "https://api.parcelgps.com/api/search/address/parse"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "referenciaCatastral": "0847106VK4704F",
    "refCat14": "0847106VK4704F",
    "direccion": "CL GRAN VIA, 1, Madrid",
    "tipoVia": "CL",
    "nombreVia": "GRAN VIA",
    "numero": 1,
    "municipio": "Madrid",
    "provincia": "MADRID"
  },
  "searchesRemaining": -1
}

Errores posibles

CódigoHTTPDescripción
VALIDATION_ERROR400Cuerpo de la petición inválido (faltan campos o JSON mal formado).
NOT_FOUND404Dirección no encontrada (calle, municipio o número inexistente o sin correspondencia catastral). La búsqueda por dirección solo está disponible en España.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Límite de búsquedas gratuitas por IP y día.

País Vasco (PV)

Catastros forales — Araba/Álava, Bizkaia y Gipuzkoa (WFS INSPIRE)

GET/api/catastro/:refcat?country=PV

Consulta de parcela en los tres territorios forales. Requiere country=PV: sus parcelas tienen catastro propio y no están en el Catastro central.

Parámetros

:refcatstringReferencia foral. Bizkaia con puntos (48.020.1611.02001); Álava y Gipuzkoa en dígitos (64010007, 8594149).
countrystringObligatorio: PV.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/48.020.1611.02001?country=PV"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "48.020.1611.02001",
    "pais": "PV",
    "municipio": "Bizkaia",
    "provincia": "Bizkaia",
    "latitud": 43.263633,
    "longitud": -2.935856,
    "superficieParcela": 3061,
    "googleMapsUrl": "https://www.google.com/maps?q=43.263633,-2.935856",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Con country=ES (incorrecto)

404
{
  "success": false,
  "error": "Parcela no encontrado: 48.020.1611.02001",
  "code": "NOT_FOUND"
}

Portugal (PT)

Catastro portugués — Direção-Geral do Território

GET/api/catastro/:refcat?country=PT

Obtener datos de parcela portuguesa por referencia cadastral.

Parámetros

:refcatstringReferencia cadastral portuguesa (p. ej. AAA000587359). La cobertura es parcial (~30 %); zonas como Lisboa y Oporto aún no están digitalizadas por la DGT.
countrystringObligatorio: PT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/AAA000587359?country=PT"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "AAA000587359",
    "pais": "PT",
    "municipio": "TAVIRA, Tavira (Santa Maria e Santiago)",
    "latitud": 37.127156,
    "longitud": -7.648066,
    "superficieParcela": 49,
    "googleMapsUrl": "https://www.google.com/maps?q=37.127156,-7.648066",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Francia (FR)

Catastro francés — Cadastre / Géoplateforme

GET/api/catastro/:refcat?country=FR

Obtener datos de parcela francesa por referencia cadastrale.

Parámetros

:refcatstringReferencia cadastrale francesa (p. ej. 75104000AE0003)
countrystringObligatorio: FR.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/75104000AE0003?country=FR"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "75104000AE0003",
    "pais": "FR",
    "municipio": "Paris",
    "provincia": "75",
    "latitud": 48.856347,
    "longitud": 2.352415,
    "superficieParcela": 15168,
    "googleMapsUrl": "https://www.google.com/maps?q=48.856347,2.352415",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Italia (IT)

Catastro italiano — Agenzia delle Entrate

GET/api/catastro/:refcat?country=IT

Obtener datos de parcela italiana por referencia catastale.

Parámetros

:refcatstringReferencia catastale italiana (foglio/particella, p. ej. H501A048100.A)
countrystringObligatorio: IT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/H501A048100.A?country=IT"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "H501A048100.A",
    "pais": "IT",
    "municipio": "H501",
    "provincia": "H501",
    "latitud": 41.902698,
    "longitud": 12.496247,
    "superficieParcela": 1059,
    "googleMapsUrl": "https://www.google.com/maps?q=41.902698,12.496247",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Alemania (DE)

Catastro alemán — ALKIS (8 Bundesländer)

GET/api/catastro/:refcat?country=DE

Obtener datos de parcela alemana por referencia catastral.

Parámetros

:refcatstringReferencia catastral alemana (Flurstückskennzeichen)
countrystringObligatorio: DE.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/05495803101122?country=DE"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "05495803101122",
    "pais": "DE",
    "latitud": 50.937566,
    "longitud": 6.960140,
    "superficieParcela": 54,
    "googleMapsUrl": "https://www.google.com/maps?q=50.937566,6.960140",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Austria (AT)

Catastro austriaco — BEV (Katastralgemeinde / Grundstück)

GET/api/catastro/:refcat?country=AT

Consulta de parcela en Austria. Requiere country=AT. La referencia es KATASTRALGEMEINDE-GRUNDSTÜCK. Cobertura parcial, en expansión.

Parámetros

:refcatstringFormato Katastralgemeinde-Grundstück (p. ej. 01004-1711).
countrystringObligatorio: AT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/01004-1711?country=AT"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "01004-1711",
    "pais": "AT",
    "municipio": "Innere Stadt",
    "provincia": "Wien",
    "latitud": 48.208478,
    "longitud": 16.372810,
    "uso": "Gebäude, Straßenverkehrsanlagen",
    "superficieParcela": 10641,
    "googleMapsUrl": "https://www.google.com/maps?q=48.208478,16.372810",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Con country=ES (incorrecto)

400
{
  "success": false,
  "error": "La referencia catastral debe tener al menos 14 caracteres",
  "code": "VALIDATION_ERROR"
}

Inteligencia de parcela y exportaciones

Geometría, potencial solar, datos agrícolas y exportación de ficheros (KML/GPX/PDF/DXF), disponibles con tu API key. Los datos de mercado y el score de inversión se quedan en la web y en la app (Pro) y no se exponen por API.

GET/api/catastro/:refcat/polygon

Obtener el polígono GeoJSON de una parcela.

Parámetros

:refcatstringReferencia catastral
countrystringCódigo de país (parámetro de query, por defecto: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon"

Ejemplo de respuesta

200 OK
{
  "data": {
    "refcat": "9872023VH5797S",
    "geojson": {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [ [ [-3.463391, 38.640317], [-3.463174, 38.640217], /* ... */ ] ]
      }
    }
  }
}

Cuota mensual agotada

429
{
  "success": false,
  "error": "Cuota mensual agotada (5000/5000). Upgrade en https://catastrogps.es/developers",
  "code": "KEY_AUTH_004"
}
GET/api/catastro/:refcat/solar

Obtener datos de potencial solar (PVGIS) de una parcela europea.

Parámetros

:refcatstringReferencia catastral
countrystringCódigo de país (parámetro de query, por defecto: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "kwh_year": 23749.9,
    "kw_instalables": 17.86,
    "ahorro_anual_eur": 3562.49,
    "amortizacion_anos": 5,
    "co2_evitado_kg": 5533.73,
    "irradiacion_media": 1807.08,
    "nota_solar": 5,
    "orientacion_optima": "Sur",
    "angulo_inclinacion": 34,
    "costo_instalacion_eur": 17865,
    "disponible": true,
    "estado": "ok",
    "fuente": "PVGIS (JRC)",
    "economics": {
      "autoconsumo_kwh_ano": 5000,
      "excedentes_kwh_ano": 18749.9,
      "ingreso_neto_anual_eur": 1473.18,
      "payback_anos": 12.13,
      "tir_pct": 6.56,
      "retorno_total_25_anos_eur": 18964.5
    }
  }
}

Parcela sin datos solares

200
{
  "success": true,
  "data": { "disponible": false, "estado": "sin_datos" }
}
GET/api/catastro/:refcat/agro

Datos agrícolas del suelo de una parcela (SIGPAC): cultivo principal, uso del suelo, pendiente, altitud y superficie. Solo parcelas rústicas — las urbanas devuelven "cultivo_principal": "urbano".

Parámetros

:refcatstringReferencia catastral
countrystringCódigo de país (parámetro de query, por defecto: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/23058A00700036/agro"

Ejemplo de respuesta

200 OK
{
  "success": true,
  "data": {
    "agro": {
      "cultivo_principal": "olivar",
      "uso_suelo": "Asociación olivar - viñedo",
      "superficie_ha": 10.6045,
      "coef_regadio": 1,
      "ndvi": {
        "valor_medio": 0.18,
        "salud_cultivo": "bajo",
        "ultima_actualizacion": "2026-06-18T00:00:00Z"
      },
      "precios_mercado": {
        "precio_kg": 8.5,
        "tendencia": "+12.5% vs periodo anterior"
      },
      "recinto": {
        "provincia": 23,
        "municipio": 58,
        "poligono": 7,
        "parcela": 36,
        "recinto": 1,
        "altitud": 559,
        "pendiente_media": 12.3
      }
    }
  }
}

Cuota mensual agotada

429
{
  "success": false,
  "error": "Cuota mensual agotada (5000/5000). Upgrade en https://catastrogps.es/developers",
  "code": "KEY_AUTH_004"
}
GET/api/export/kml?refcat=:refcat

Exportar datos de parcela en formato KML (Google Earth).

Parámetros

refcatstringReferencia catastral
countrystringCódigo de país (opcional: se detecta por la referencia)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kml

Ejemplo de respuesta

200 OK
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <name>9872023VH5797S</name>
      ...
    </Placemark>
  </Document>
</kml>
GET/api/export/gpx?refcat=:refcat

Exportar datos de parcela en formato GPX (navegadores GPS).

Parámetros

refcatstringReferencia catastral
countrystringCódigo de país (opcional: se detecta por la referencia)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpx

Ejemplo de respuesta

200 OK
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1">
  <wpt lat="40.4168" lon="-3.7038">
    <name>9872023VH5797S</name>
  </wpt>
</gpx>