Documentazione API

Riferimento completo dell'API catastale

Base URL

https://api.parcelgps.com

Codici 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.

ES · SpagnaPV · Paesi BaschiNA · NavarraPT · PortogalloFR · FranciaIT · ItaliaDE · GermaniaAT · AustriaPL · PolandNL · NetherlandsCZ · CzechiaFI · FinlandBE · BelgiumEE · EstoniaSI · SloveniaLT · LithuaniaLU · LuxembourgSK · SlovakiaBG · BulgariaCY · countries.CYIS · countries.ISLI · countries.LICH · Switzerland

Riferimento endpoint

MetodoEndpointAuthDescrizione
GET/api/resolve?q=TEXTAPI KeyClassifica qualsiasi testo: riferimento (e paese), coordinate o toponimo. Senza quota.
GET/api/catastro/:refcatAPI KeyConsultazione particella
GET/api/catastro/:refcat/polygon?country=XXAPI KeyGeometria della particella (GeoJSON)
GET/api/catastro/:refcat/solar?country=XXAPI KeyPotenziale solare
GET/api/catastro/:refcat/agro?country=XXAPI KeyDati agricoli del terreno
GET/api/export/kml?refcat=X&country=XAPI KeyEsportare KML/GPX/PDF/DXF
GET/api/catastro/:refcat/market?country=XXWeb e appDati di mercato (non via API)
GET/api/catastro/:refcat/score?country=XXWeb e appScore 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.

EndpointDa 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/coordinatesCatastro (ente pubblico). Può non rispondere senza preavviso.
/agroSIGPAC
/solarPVGIS

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

StatoCodiceDescrizione
200OK — La richiesta è stata completata correttamente.
400VALIDATION_ERRORBad Request — Parametri non validi o riferimento catastale con formato errato.
401UNAUTHORIZEDUnauthorized — API key non valida, scaduta o assente.
404NOT_FOUNDNot Found — Nessuna particella trovata per il riferimento o le coordinate indicate.
429KEY_AUTH_004Quota Exceeded — Hai raggiunto il limite mensile del tuo piano. Controlla le intestazioni X-RateLimit-Remaining e X-RateLimit-Reset per sapere quando viene azzerato.
429RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHEDToo Many Requests — Limite di ricerche gratuite per IP e giorno (piano gratuito). Con API key si applica la quota mensile del piano (sopra).
500INTERNAL_ERRORInternal Server Error — Errore sul nostro server. Se persiste, contatta il supporto.
503SERVICE_UNAVAILABLEService 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:

IntestazioneDescrizione
X-RateLimit-LimitLimite mensile totale del tuo piano (p. es. 5000).
X-RateLimit-RemainingChiamate rimaste questo mese.
X-RateLimit-ResetData di azzeramento della quota (ISO 8601).
X-Quota-TierNome del tier attuale (free, basic, pro, business).

Spagna (ES)

Catasto spagnolo — Dirección General del Catastro

GET/api/catastro/:refcat

Ottenere i dati della particella per riferimento catastale (14 o 20 caratteri).

Parametri

:refcatstringRiferimento 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

CodiceHTTPDescrizione
VALIDATION_ERROR400Il riferimento non ha un formato valido per il paese.
NOT_FOUND404Riferimento 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_REACHED429Limite di ricerche gratuite per IP e giorno.
KEY_AUTH_004429Quota mensile della API key esaurita (vedi le intestazioni X-RateLimit-*).
SERVICE_UNAVAILABLE503Il servizio catastale ufficiale del paese è fuori servizio o in manutenzione. Riprova.
POST/api/search/coordinates

Geocodifica inversa: trovare la particella catastale a coordinate GPS.

Parametri

latitudenumberLatitudine (WGS84)
longitudenumberLongitudine (WGS84)
countrystringCodice 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

CodiceHTTPDescrizione
VALIDATION_ERROR400Coordinate fuori dai limiti del paese indicato o rilevato, o lat/lng assenti o mal formate.
NOT_FOUND404Non esiste alcuna particella a quelle coordinate.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Limite di ricerche gratuite per IP e giorno.
SERVICE_UNAVAILABLE503Servizio catastale temporaneamente non disponibile.
POST/api/search/address/parse

Cercare particella catastale per indirizzo postale.

Parametri

direccionstringIndirizzo 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

CodiceHTTPDescrizione
VALIDATION_ERROR400Corpo della richiesta non valido (campi mancanti o JSON mal formato).
NOT_FOUND404Indirizzo non trovato (via, comune o numero inesistente o senza corrispondenza catastale). La ricerca per indirizzo è disponibile solo in Spagna.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Limite di ricerche gratuite per IP e giorno.

Paesi Baschi (PV)

Catasti forali — Araba/Álava, Bizkaia e Gipuzkoa (WFS INSPIRE)

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

Consultazione di particella nei tre territori forali. Richiede country=PV: le loro particelle hanno un catasto proprio e non sono nel Catastro centrale.

Parametri

:refcatstringRiferimento forale. Bizkaia con punti (48.020.1611.02001); Álava e Gipuzkoa in cifre (64010007, 8594149).
countrystringObbligatorio: 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

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

Ottenere i dati di una particella portoghese per riferimento catastale.

Parametri

:refcatstringRiferimento catastale portoghese (p. es. AAA000587359). La copertura è parziale (~30 %); zone come Lisbona e Porto non sono ancora digitalizzate dalla DGT.
countrystringObbligatorio: 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

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

Ottenere i dati di una particella francese per riferimento catastale.

Parametri

:refcatstringRiferimento catastale francese (p. es. 75104000AE0003)
countrystringObbligatorio: 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

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

Ottenere i dati di una particella italiana per riferimento catastale.

Parametri

:refcatstringRiferimento catastale italiano (foglio/particella, p. es. H501A048100.A)
countrystringObbligatorio: 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)

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

Ottenere i dati di una particella tedesca per riferimento catastale.

Parametri

:refcatstringRiferimento catastale tedesco (Flurstückskennzeichen)
countrystringObbligatorio: 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)

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

Consultazione di particella in Austria. Richiede country=AT. Il riferimento è KATASTRALGEMEINDE-GRUNDSTÜCK. Copertura parziale, in espansione.

Parametri

:refcatstringFormato Katastralgemeinde-Grundstück (p. es. 01004-1711).
countrystringObbligatorio: 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.

GET/api/catastro/:refcat/polygon

Ottenere il poligono GeoJSON di una particella.

Parametri

:refcatstringRiferimento catastale
countrystringCodice 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"
}
GET/api/catastro/:refcat/solar

Ottenere i dati del potenziale solare (PVGIS) di una particella europea.

Parametri

:refcatstringRiferimento catastale
countrystringCodice 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" }
}
GET/api/catastro/:refcat/agro

Dati 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

:refcatstringRiferimento catastale
countrystringCodice 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"
}
GET/api/export/kml?refcat=:refcat

Esportare i dati della particella in formato KML (Google Earth).

Parametri

refcatstringRiferimento catastale
countrystringCodice paese (facoltativo: rilevato dal riferimento)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kml

Esempio 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>
GET/api/export/gpx?refcat=:refcat

Esportare i dati della particella in formato GPX (navigatori GPS).

Parametri

refcatstringRiferimento catastale
countrystringCodice paese (facoltativo: rilevato dal riferimento)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpx

Esempio 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>