Documentazione API
Riferimento completo dell'API catastale
Base URL
https://api.parcelgps.comCodici paese
Gli endpoint accettano ?country=XX. È facoltativo: senza, l'API rileva il paese dalla forma del riferimento in 21 paesi. Un riferimento ambiguo restituisce 300 CNV_AMBIGUOUS con i candidati; un paese non ancora coperto, 422 CNV_COVERAGE; qualcosa che sembra un nome di luogo, 422 CNV_PLACE_NAME con il punto geocodificato. La Spagna peninsulare usa ES, ma i Paesi Baschi e la Navarra hanno un catasto proprio (forale) e richiedono il loro codice: con ES le loro particelle non vengono trovate.
Riferimento endpoint
| Metodo | Endpoint | Auth | Descrizione |
|---|---|---|---|
| GET | /api/resolve?q=TEXT | API Key | Classifica qualsiasi testo: riferimento (e paese), coordinate o toponimo. Senza quota. |
| GET | /api/catastro/:refcat | API Key | Consultazione particella |
| GET | /api/catastro/:refcat/polygon?country=XX | API Key | Geometria della particella (GeoJSON) |
| GET | /api/catastro/:refcat/solar?country=XX | API Key | Potenziale solare |
| GET | /api/catastro/:refcat/agro?country=XX | API Key | Dati agricoli del terreno |
| GET | /api/export/kml?refcat=X&country=X | API Key | Esportare KML/GPX/PDF/DXF |
| GET | /api/catastro/:refcat/market?country=XX | Web e app | Dati di mercato (non via API) |
| GET | /api/catastro/:refcat/score?country=XX | Web e app | Score di investimento (non via API) |
Affidabilità
Cosa serviamo dalla nostra infrastruttura e cosa dipende da un ente pubblico. Vale la pena leggerlo prima di andare in produzione.
| Endpoint | Da dove arrivano i dati |
|---|---|
| /catastro/:refcat (ES) | Copia propria del catasto (50,9 M di particelle). Non dipende dal Catastro per rispondere. |
| /polygon · /search/address · /search/coordinates | Catastro (ente pubblico). Può non rispondere senza preavviso. |
| /agro | SIGPAC |
| /solar | PVGIS |
Errori e nuovi tentativi
Un 503 significa che una fonte ufficiale non risponde in questo momento: riprova con attesa crescente e si risolverà da solo. Un 429 è la tua quota, e riprovare non la restituisce — aspetta il reset o cambia piano. Un 404 è un riferimento inesistente e non va ritentato.
Pagina di stato
Pubblichiamo lo stato della nostra API e delle nove fonti catastali da cui dipendiamo, verificato ogni cinque minuti e ospitato fuori da questa API per restare affidabile durante un disservizio: catastrogps.es/status.
Autenticazione
Tutte le richieste API richiedono una API key inviata nell'intestazione X-API-Key.
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/9872023VH5797S"Ottieni la tua API key gratuita su la tua dashboard sviluppatore.
Codici di errore
| Stato | Codice | Descrizione |
|---|---|---|
| 200 | — | OK — La richiesta è stata completata correttamente. |
| 400 | VALIDATION_ERROR | Bad Request — Parametri non validi o riferimento catastale con formato errato. |
| 401 | UNAUTHORIZED | Unauthorized — API key non valida, scaduta o assente. |
| 404 | NOT_FOUND | Not Found — Nessuna particella trovata per il riferimento o le coordinate indicate. |
| 429 | KEY_AUTH_004 | Quota Exceeded — Hai raggiunto il limite mensile del tuo piano. Controlla le intestazioni X-RateLimit-Remaining e X-RateLimit-Reset per sapere quando viene azzerato. |
| 429 | RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | Too Many Requests — Limite di ricerche gratuite per IP e giorno (piano gratuito). Con API key si applica la quota mensile del piano (sopra). |
| 500 | INTERNAL_ERROR | Internal Server Error — Errore sul nostro server. Se persiste, contatta il supporto. |
| 503 | SERVICE_UNAVAILABLE | Service Unavailable — Il servizio catastale esterno del paese richiesto è temporaneamente non disponibile. Questi servizi sono gestiti da enti pubblici (Catastro, DGT, Géoportail, Agenzia Entrate, ALKIS...) e sono fuori dal nostro controllo. Riprova tra qualche minuto. |
Intestazioni di rate limit
Ogni risposta include intestazioni che indicano lo stato della tua quota:
| Intestazione | Descrizione |
|---|---|
| X-RateLimit-Limit | Limite mensile totale del tuo piano (p. es. 5000). |
| X-RateLimit-Remaining | Chiamate rimaste questo mese. |
| X-RateLimit-Reset | Data di azzeramento della quota (ISO 8601). |
| X-Quota-Tier | Nome del tier attuale (free, basic, pro, business). |
Spagna (ES)
Catasto spagnolo — Dirección General del Catastro
/api/catastro/:refcatOttenere i dati della particella per riferimento catastale (14 o 20 caratteri).
Parametri
| :refcat | string | Riferimento catastale (p. es. 9872023VH5797S0001WX) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX"Esempio di risposta
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
}Errori possibili
| Codice | HTTP | Descrizione |
|---|---|---|
| VALIDATION_ERROR | 400 | Il riferimento non ha un formato valido per il paese. |
| NOT_FOUND | 404 | Riferimento non trovato. Un ?country non supportato viene trattato come Spagna (ES) e di norma restituisce NOT_FOUND; usa ES/PT/FR/IT/DE/PV/NA. Nei catasti forali (NA, PV) il campo message aggiunge un suggerimento sul formato. |
| RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | 429 | Limite di ricerche gratuite per IP e giorno. |
| KEY_AUTH_004 | 429 | Quota mensile della API key esaurita (vedi le intestazioni X-RateLimit-*). |
| SERVICE_UNAVAILABLE | 503 | Il servizio catastale ufficiale del paese è fuori servizio o in manutenzione. Riprova. |
/api/search/coordinatesGeocodifica inversa: trovare la particella catastale a coordinate GPS.
Parametri
| latitude | number | Latitudine (WGS84) |
| longitude | number | Longitudine (WGS84) |
| country | string | Codice paese (facoltativo: rilevato dal riferimento) |
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"Esempio di risposta
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
}Errori possibili
| Codice | HTTP | Descrizione |
|---|---|---|
| VALIDATION_ERROR | 400 | Coordinate fuori dai limiti del paese indicato o rilevato, o lat/lng assenti o mal formate. |
| NOT_FOUND | 404 | Non esiste alcuna particella a quelle coordinate. |
| RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | 429 | Limite di ricerche gratuite per IP e giorno. |
| SERVICE_UNAVAILABLE | 503 | Servizio catastale temporaneamente non disponibile. |
/api/search/address/parseCercare particella catastale per indirizzo postale.
Parametri
| direccion | string | Indirizzo in testo libero (solo Spagna). Formato consigliato: «Calle, Número, Municipio» — p. es. «Calle Mallorca, 213, Barcelona». Il numero civico può anche essere unito alla via («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"Esempio di risposta
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
}Errori possibili
| Codice | HTTP | Descrizione |
|---|---|---|
| VALIDATION_ERROR | 400 | Corpo della richiesta non valido (campi mancanti o JSON mal formato). |
| NOT_FOUND | 404 | Indirizzo non trovato (via, comune o numero inesistente o senza corrispondenza catastale). La ricerca per indirizzo è disponibile solo in Spagna. |
| RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | 429 | Limite di ricerche gratuite per IP e giorno. |
Paesi Baschi (PV)
Catasti forali — Araba/Álava, Bizkaia e Gipuzkoa (WFS INSPIRE)
/api/catastro/:refcat?country=PVConsultazione di particella nei tre territori forali. Richiede country=PV: le loro particelle hanno un catasto proprio e non sono nel Catastro centrale.
Parametri
| :refcat | string | Riferimento forale. Bizkaia con punti (48.020.1611.02001); Álava e Gipuzkoa in cifre (64010007, 8594149). |
| country | string | Obbligatorio: PV. |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/48.020.1611.02001?country=PV"Esempio di risposta
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 (errato)
404{
"success": false,
"error": "Parcela no encontrado: 48.020.1611.02001",
"code": "NOT_FOUND"
}Portogallo (PT)
Catasto portoghese — Direção-Geral do Território
/api/catastro/:refcat?country=PTOttenere i dati di una particella portoghese per riferimento catastale.
Parametri
| :refcat | string | Riferimento catastale portoghese (p. es. AAA000587359). La copertura è parziale (~30 %); zone come Lisbona e Porto non sono ancora digitalizzate dalla DGT. |
| country | string | Obbligatorio: PT. |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/AAA000587359?country=PT"Esempio di risposta
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)
Catasto francese — Cadastre / Géoplateforme
/api/catastro/:refcat?country=FROttenere i dati di una particella francese per riferimento catastale.
Parametri
| :refcat | string | Riferimento catastale francese (p. es. 75104000AE0003) |
| country | string | Obbligatorio: FR. |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/75104000AE0003?country=FR"Esempio di risposta
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)
Catasto italiano — Agenzia delle Entrate
/api/catastro/:refcat?country=ITOttenere i dati di una particella italiana per riferimento catastale.
Parametri
| :refcat | string | Riferimento catastale italiano (foglio/particella, p. es. H501A048100.A) |
| country | string | Obbligatorio: IT. |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/H501A048100.A?country=IT"Esempio di risposta
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 */ ]
}
}Germania (DE)
Catasto tedesco — ALKIS (8 Bundesländer)
/api/catastro/:refcat?country=DEOttenere i dati di una particella tedesca per riferimento catastale.
Parametri
| :refcat | string | Riferimento catastale tedesco (Flurstückskennzeichen) |
| country | string | Obbligatorio: DE. |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/05495803101122?country=DE"Esempio di risposta
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)
Catasto austriaco — BEV (Katastralgemeinde / Grundstück)
/api/catastro/:refcat?country=ATConsultazione di particella in Austria. Richiede country=AT. Il riferimento è KATASTRALGEMEINDE-GRUNDSTÜCK. Copertura parziale, in espansione.
Parametri
| :refcat | string | Formato Katastralgemeinde-Grundstück (p. es. 01004-1711). |
| country | string | Obbligatorio: AT. |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/01004-1711?country=AT"Esempio di risposta
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 (errato)
400{
"success": false,
"error": "La referencia catastral debe tener al menos 14 caracteres",
"code": "VALIDATION_ERROR"
}Intelligence della particella ed esportazioni
Geometria, potenziale solare, dati agricoli ed esportazione di file (KML/GPX/PDF/DXF), disponibili con la tua API key. I dati di mercato e lo score di investimento restano sul web e nell'app (Pro) e non sono esposti via API.
/api/catastro/:refcat/polygonOttenere il poligono GeoJSON di una particella.
Parametri
| :refcat | string | Riferimento catastale |
| country | string | Codice paese (parametro query, predefinito: ES) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon"Esempio di risposta
200 OK{
"data": {
"refcat": "9872023VH5797S",
"geojson": {
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [ [ [-3.463391, 38.640317], [-3.463174, 38.640217], /* ... */ ] ]
}
}
}
}Quota mensile esaurita
429{
"success": false,
"error": "Cuota mensual agotada (5000/5000). Upgrade en https://catastrogps.es/developers",
"code": "KEY_AUTH_004"
}/api/catastro/:refcat/solarOttenere i dati del potenziale solare (PVGIS) di una particella europea.
Parametri
| :refcat | string | Riferimento catastale |
| country | string | Codice paese (parametro query, predefinito: ES) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/9872023VH5797S/solar"Esempio di risposta
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
}
}
}Particella senza dati solari
200{
"success": true,
"data": { "disponible": false, "estado": "sin_datos" }
}/api/catastro/:refcat/agroDati agricoli del terreno di una particella (SIGPAC): coltura principale, uso del suolo, pendenza, altitudine e superficie. Solo particelle rustiche — quelle urbane restituiscono "cultivo_principal": "urbano".
Parametri
| :refcat | string | Riferimento catastale |
| country | string | Codice paese (parametro query, predefinito: ES) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/catastro/23058A00700036/agro"Esempio di risposta
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
}
}
}
}Quota mensile esaurita
429{
"success": false,
"error": "Cuota mensual agotada (5000/5000). Upgrade en https://catastrogps.es/developers",
"code": "KEY_AUTH_004"
}/api/export/kml?refcat=:refcatEsportare i dati della particella in formato KML (Google Earth).
Parametri
| refcat | string | Riferimento catastale |
| country | string | Codice paese (facoltativo: rilevato dal riferimento) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kmlEsempio di risposta
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=:refcatEsportare i dati della particella in formato GPX (navigatori GPS).
Parametri
| refcat | string | Riferimento catastale |
| country | string | Codice paese (facoltativo: rilevato dal riferimento) |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpxEsempio di risposta
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>