API-Dokumentation
Vollständige Kataster-API-Referenz
Base URL
https://api.parcelgps.comCódigos de país
Los endpoints aceptan ?country=XX. La España peninsular usa ES, pero País Vasco y Navarra tienen catastro propio (foral) y requieren su propio código — con ES sus parcelas no se encuentran.
Endpoint-Referenz
| Método | Endpoint | Auth | Descripción |
|---|---|---|---|
| GET | /api/catastro/:refcat?country=XX | API Key | Parcel lookup |
| GET | /api/catastro/:refcat/polygon?country=XX | API Key | Parcel geometry (GeoJSON) |
| GET | /api/catastro/:refcat/solar?country=XX | API Key | Solar potential |
| GET | /api/catastro/:refcat/agro?country=XX | API Key | Agricultural land data |
| GET | /api/export/kml?refcat=X&country=X | API Key | Export KML/GPX/PDF/DXF |
| GET | /api/catastro/:refcat/market?country=XX | Web & app | Market data (not via API) |
| GET | /api/catastro/:refcat/score?country=XX | Web & app | Investment score (not via API) |
Zuverlässigkeit
Was wir aus eigener Infrastruktur liefern und was von einer Behörde abhängt. Vor dem Produktivbetrieb lesenswert.
| Endpoint | Woher die Daten kommen |
|---|---|
| /catastro/:refcat (ES) | Eigene Kopie des Katasters (50,9 Mio. Flurstücke). Antwortet ohne das Catastro. |
| /polygon · /search/address · /search/coordinates | Catastro (Behörde). Kann ohne Vorwarnung ausfallen. |
| /agro | SIGPAC |
| /solar | PVGIS |
Fehler und Wiederholungen
Ein 503 heißt, dass eine offizielle Quelle gerade nicht antwortet: mit wachsendem Abstand erneut versuchen, das klärt sich von selbst. Ein 429 ist Ihr Kontingent — erneutes Senden bringt es nicht zurück; auf den Reset warten oder den Tarif wechseln. Ein 404 ist eine nicht existierende Referenz und sollte nicht wiederholt werden.
Statusseite
Wir veröffentlichen den Zustand unserer API und der neun Katasterquellen, von denen wir abhängen — alle fünf Minuten geprüft und außerhalb dieser API gehostet, damit sie bei einer Störung verlässlich bleibt: catastrogps.es/status.
Authentifizierung
Alle API-Anfragen erfordern einen API-Key im X-API-Key-Header.
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/9872023VH5797S"Erhalten Sie Ihren kostenlosen API-Key auf Ihrem Entwickler-Dashboard.
Fehlercodes
| Status | Code | Beschreibung |
|---|---|---|
| 200 | — | OK — La petición se ha completado correctamente. |
| 400 | VALIDATION_ERROR | Bad Request — Parámetros inválidos o referencia catastral con formato incorrecto. |
| 401 | UNAUTHORIZED | Unauthorized — API key inválida, expirada o no proporcionada. |
| 404 | NOT_FOUND | Not Found — No se encontró la parcela con la referencia o coordenadas indicadas. |
| 429 | KEY_AUTH_004 | Quota 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. |
| 429 | RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | Too Many Requests — Límite de búsquedas gratuitas por IP / día (tier gratuito). Con API key aplica la cuota mensual del plan (arriba). |
| 500 | INTERNAL_ERROR | Internal Server Error — Error en nuestro servidor. Si persiste, contacta soporte. |
| 503 | SERVICE_UNAVAILABLE | Service Unavailable — El servicio catastral externo del país consultado no está disponible temporalmente. Estos servicios son gestionados por 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 quota:
| Header | Beschreibung |
|---|---|
| X-RateLimit-Limit | Límite mensual total de tu plan (ej: 5000). |
| X-RateLimit-Remaining | Llamadas restantes este mes. |
| X-RateLimit-Reset | Fecha de reinicio de la quota (ISO 8601). |
| X-Quota-Tier | Nombre del tier actual (free, basic, pro, business). |
Spain (ES)
Spanish Cadastre — Direccion General del Catastro
/api/catastro/:refcatFlurstückdaten per Katasterreferenz abrufen (14 oder 20 Zeichen).
Parameter
| :refcat | string | Cadastral reference (e.g. 9872023VH5797S0001WX) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX"Antwortbeispiel
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
| Code | HTTP | Beschreibung |
|---|---|---|
| VALIDATION_ERROR | 400 | La referencia no tiene un formato válido para el país. |
| NOT_FOUND | 404 | Referencia no encontrada. Un ?country no soportado se trata como España (ES) → normalmente NOT_FOUND; usa ES/PT/FR/IT/DE/PV/NA. En catastros forales (NA, PV) el message añade una pista de formato. |
| RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | 429 | Límite de búsquedas gratuitas por IP / día. |
| KEY_AUTH_004 | 429 | Cuota mensual de la API key agotada (ver cabeceras X-RateLimit-*). |
| SERVICE_UNAVAILABLE | 503 | El servicio catastral oficial del país está caído o en mantenimiento. Reintentar. |
/api/search/coordinatesUmgekehrte Geokodierung: Katasterflurstuck an GPS-Koordinaten finden.
Parameter
| latitude | number | Latitude (WGS84) |
| longitude | number | Longitude (WGS84) |
| country | string | Country code (default: ES) |
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"Antwortbeispiel
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
| Code | HTTP | Beschreibung |
|---|---|---|
| VALIDATION_ERROR | 400 | Coordenadas fuera de los límites del país indicado/detectado, o lat/lng ausentes o mal formadas. |
| NOT_FOUND | 404 | No hay ninguna parcela en esas coordenadas. |
| RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | 429 | Límite de búsquedas gratuitas por IP / día. |
| SERVICE_UNAVAILABLE | 503 | Servicio catastral no disponible temporalmente. |
/api/search/address/parseKatasterflurstuck per Postadresse suchen.
Parameter
| direccion | string | Free-text address (Spain only). Recommended format: "Calle, Número, Municipio" — e.g. "Calle Mallorca, 213, Barcelona". The house number may also be attached to the street ("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"Antwortbeispiel
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
| Code | HTTP | Beschreibung |
|---|---|---|
| VALIDATION_ERROR | 400 | Cuerpo de la petición inválido (faltan campos o JSON mal formado). |
| NOT_FOUND | 404 | Dirección no encontrada (calle/municipio/número inexistente o sin correspondencia catastral). La búsqueda por dirección está disponible solo en España. |
| RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | 429 | Límite de búsquedas gratuitas por IP / día. |
País Vasco (PV)
Cadastros forales — Araba/Álava, Bizkaia y Gipuzkoa (WFS INSPIRE)
/api/catastro/:refcat?country=PVConsulta de parcela en los tres territorios forales. Requiere country=PV: sus parcelas tienen catastro propio y no están en el Catastro central.
Parameter
| :refcat | string | Referencia foral. Bizkaia con puntos (48.020.1611.02001); Álava y Gipuzkoa en dígitos (64010007, 8594149). |
| country | string | Obligatorio: "PV". |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/48.020.1611.02001?country=PV"Antwortbeispiel
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)
Portuguese Cadastre — Direcao-Geral do Territorio
/api/catastro/:refcat?country=PTPortugiesische Flurstückdaten per Katasterreferenz abrufen.
Parameter
| :refcat | string | Portuguese cadastral reference (e.g. AAA000587359). Coverage is partial (~30%); areas like Lisbon and Porto are not yet digitized by the DGT. |
| country | string | Must be "PT" |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/AAA000587359?country=PT"Antwortbeispiel
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 */ ]
}
}France (FR)
French Cadastre — Cadastre / Geoplateforme
/api/catastro/:refcat?country=FRFranzösische Flurstückdaten per Katasterreferenz abrufen.
Parameter
| :refcat | string | French cadastral reference (e.g. 75104000AE0003) |
| country | string | Must be "FR" |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/75104000AE0003?country=FR"Antwortbeispiel
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 */ ]
}
}Italy (IT)
Italian Cadastre — Agenzia delle Entrate
/api/catastro/:refcat?country=ITItalienische Flurstückdaten per Katasterreferenz abrufen.
Parameter
| :refcat | string | Italian cadastral reference (foglio/particella, e.g. H501A048100.A) |
| country | string | Must be "IT" |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/H501A048100.A?country=IT"Antwortbeispiel
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 */ ]
}
}Germany (DE)
German Cadastre — ALKIS (8 Bundesländer)
/api/catastro/:refcat?country=DEDeutsche Flurstückdaten per Katasterreferenz abrufen.
Parameter
| :refcat | string | German cadastral reference (Flurstückskennzeichen) |
| country | string | Must be "DE" |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/05495803101122?country=DE"Antwortbeispiel
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)
Österreichisches Kataster — BEV (Katastralgemeinde / Grundstück)
/api/catastro/:refcat?country=ATConsulta de parcela en Austria. Requiere country=AT. La referencia es KATASTRALGEMEINDE-GRUNDSTÜCK. Cobertura parcial, en expansión.
Parameter
| :refcat | string | Formato Katastralgemeinde-Grundstück (p. ej. 01004-1711). |
| country | string | Obligatorio: "AT". |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/01004-1711?country=AT"Antwortbeispiel
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"
}Parcel intelligence & exports
Geometry, solar potential, agricultural data and file exports (KML/GPX/PDF/DXF), available with your API key. Market data and the investment score stay in the web app and app (Pro) and are not exposed via the API.
/api/catastro/:refcat/polygonGeoJSON-Polygon eines Flurstucks abrufen.
Parameter
| :refcat | string | Cadastral reference |
| country | string | Country code (query param, default: ES) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon"Antwortbeispiel
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"
}/api/catastro/:refcat/solarSolarpotenzial-Daten (PVGIS) eines europäischen Flurstucks abrufen.
Parameter
| :refcat | string | Cadastral reference |
| country | string | Country code (query param, default: ES) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/9872023VH5797S/solar"Antwortbeispiel
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" }
}/api/catastro/:refcat/agroAgricultural land data for a parcel (SIGPAC): main crop, land use, slope, altitude and area. Rural parcels only — urban parcels return "cultivo_principal": "urbano".
Parameter
| :refcat | string | Cadastral reference |
| country | string | Country code (query param, default: ES) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/23058A00700036/agro"Antwortbeispiel
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"
}/api/export/kml?refcat=:refcatFlurstückdaten im KML-Format exportieren (Google Earth).
Parameter
| refcat | string | Cadastral reference |
| country | string | Country code (default: ES) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kmlAntwortbeispiel
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>/api/export/gpx?refcat=:refcatFlurstückdaten im GPX-Format exportieren (GPS-Navigationsgerate).
Parameter
| refcat | string | Cadastral reference |
| country | string | Country code (default: ES) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpxAntwortbeispiel
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>