Documentation API

Référence complète de l'API cadastrale

Base URL

https://api.parcelgps.com

Codes pays

Les endpoints acceptent ?country=XX. Facultatif : sans lui, l'API détecte le pays à partir de la forme de la référence, dans 21 pays. Une référence ambiguë renvoie 300 CNV_AMBIGUOUS avec les candidats ; un pays non couvert, 422 CNV_COVERAGE ; ce qui ressemble à un nom de lieu, 422 CNV_PLACE_NAME avec le point géocodé. L'Espagne péninsulaire utilise ES, mais le Pays basque et la Navarre ont leur propre cadastre (foral) et exigent leur propre code : avec ES, leurs parcelles ne sont pas trouvées.

ES · EspagnePV · Pays basqueNA · NavarrePT · PortugalFR · FranceIT · ItalieDE · AllemagneAT · AutrichePL · PolandNL · NetherlandsCZ · CzechiaFI · FinlandBE · BelgiumEE · EstoniaSI · SloveniaLT · LithuaniaLU · LuxembourgSK · SlovakiaBG · BulgariaCY · ChypreIS · IslandeLI · LiechtensteinCH · Switzerland

Référence des endpoints

MéthodeEndpointAuthDescription
GET/api/resolve?q=TEXTAPI KeyClasse n'importe quelle saisie : référence (et pays), coordonnées ou toponyme. Hors quota.
GET/api/catastro/:refcatAPI KeyConsultation de parcelle
GET/api/catastro/:refcat/polygon?country=XXAPI KeyGéométrie de la parcelle (GeoJSON)
GET/api/catastro/:refcat/solar?country=XXAPI KeyPotentiel solaire
GET/api/catastro/:refcat/agro?country=XXAPI KeyDonnées agricoles du terrain
GET/api/export/kml?refcat=X&country=XAPI KeyExporter KML/GPX/PDF/DXF
GET/api/catastro/:refcat/market?country=XXWeb et appDonnées de marché (pas via l'API)
GET/api/catastro/:refcat/score?country=XXWeb et appScore d'investissement (pas via l'API)

Fiabilité

Ce que nous servons depuis notre propre infrastructure et ce qui dépend d'un organisme public. À lire avant de passer en production.

EndpointD'où viennent les données
/catastro/:refcat (ES)Notre propre copie du cadastre (50,9 M de parcelles). Ne dépend pas du Catastro pour répondre.
/polygon · /search/address · /search/coordinatesCatastro (organisme public). Peut tomber sans préavis.
/agroSIGPAC
/solarPVGIS

Erreurs et nouvelles tentatives

Un 503 signifie qu'une source officielle ne répond pas pour le moment : réessayez avec un délai croissant et cela se rétablira. Un 429 correspond à votre quota, et réessayer ne le restaure pas — attendez la réinitialisation ou changez de forfait. Un 404 est une référence inexistante et ne doit pas être réessayé.

Page de statut

Nous publions l'état de notre API et des neuf sources cadastrales dont nous dépendons, vérifié toutes les cinq minutes et hébergé en dehors de cette API pour rester fiable pendant une panne : catastrogps.es/status.

Authentification

Toutes les requêtes API nécessitent une API key envoyée dans l'en-tête X-API-Key.

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

Obtenez votre API key gratuite sur votre tableau de bord développeur.

Codes d'erreur

StatutCodeDescription
200—OK — La requête s'est terminée correctement.
400VALIDATION_ERRORBad Request — Paramètres invalides ou référence cadastrale au format incorrect.
401UNAUTHORIZEDUnauthorized — API key invalide, expirée ou absente.
404NOT_FOUNDNot Found — Aucune parcelle trouvée pour la référence ou les coordonnées indiquées. Ne consomme pas de quota.
429KEY_AUTH_004Quota Exceeded — Vous avez atteint la limite mensuelle de votre forfait. Consultez les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset pour savoir quand elle est réinitialisée.
429RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHEDToo Many Requests — Limite de recherches gratuites par IP et par jour (offre gratuite). Avec une API key, c'est le quota mensuel du forfait qui s'applique (ci-dessus).
500INTERNAL_ERRORInternal Server Error — Erreur sur notre serveur. Si elle persiste, contactez le support.
503SERVICE_UNAVAILABLEService Unavailable — Le service cadastral externe du pays demandé est temporairement indisponible. Ces services sont gérés par des organismes publics (Catastro, DGT, Géoportail, Agenzia Entrate, ALKIS...) et échappent à notre contrôle. Réessayez dans quelques minutes.

En-têtes de rate limit

Chaque réponse inclut des en-têtes indiquant l'état de votre quota :

En-têteDescription
X-RateLimit-LimitLimite mensuelle totale de votre forfait (p. ex. 5000).
X-RateLimit-RemainingAppels restants ce mois-ci.
X-RateLimit-ResetDate de réinitialisation du quota (ISO 8601).
X-Quota-TierNom de l’offre actuelle (free, basic, pro, business).

Espagne (ES)

Cadastre espagnol — Dirección General del Catastro

GET/api/catastro/:refcat

Obtenir les données d'une parcelle par référence cadastrale (14 ou 20 caractères).

Paramètres

:refcatstringRéférence cadastrale (p. ex. 9872023VH5797S0001WX)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX"

Exemple de réponse

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
}

Erreurs possibles

CodeHTTPDescription
VALIDATION_ERROR400La référence n'a pas un format valide pour le pays.
NOT_FOUND404Référence introuvable. Un ?country non pris en charge est traité comme l’Espagne (ES) et renvoie normalement NOT_FOUND ; utilisez ES/PT/FR/IT/DE/PV/NA. Pour les cadastres foraux (NA, PV), le champ message ajoute une indication de format.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Limite de recherches gratuites par IP et par jour.
KEY_AUTH_004429Quota mensuel de l’API key épuisé (voir les en-têtes X-RateLimit-*).
SERVICE_UNAVAILABLE503Le service cadastral officiel du pays est en panne ou en maintenance. Réessayez.
POST/api/search/coordinates

Géocodage inverse : trouver la parcelle cadastrale à des coordonnées GPS.

Paramètres

latitudenumberLatitude (WGS84)
longitudenumberLongitude (WGS84)
countrystringCode pays (facultatif : détecté à partir de la référence)
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"

Exemple de réponse

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
}

Erreurs possibles

CodeHTTPDescription
VALIDATION_ERROR400Coordonnées hors des limites du pays indiqué ou détecté, ou lat/lng absentes ou mal formées.
NOT_FOUND404Il n'y a aucune parcelle à ces coordonnées.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Limite de recherches gratuites par IP et par jour.
SERVICE_UNAVAILABLE503Service cadastral temporairement indisponible.
POST/api/search/address/parse

Rechercher une parcelle cadastrale par adresse postale.

Paramètres

direccionstringAdresse en texte libre (Espagne uniquement). Format recommandé : «Calle, Número, Municipio» — p. ex. «Calle Mallorca, 213, Barcelona». Le numéro peut aussi être accolé à la rue («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"

Exemple de réponse

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
}

Erreurs possibles

CodeHTTPDescription
VALIDATION_ERROR400Corps de requête invalide (champs manquants ou JSON mal formé).
NOT_FOUND404Adresse introuvable (rue, commune ou numéro inexistant ou sans correspondance cadastrale). La recherche par adresse n’est disponible qu’en Espagne.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Limite de recherches gratuites par IP et par jour.

Pays basque (PV)

Cadastres foraux — Araba/Álava, Bizkaia et Gipuzkoa (WFS INSPIRE)

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

Consultation de parcelle dans les trois territoires foraux. Nécessite country=PV : leurs parcelles ont leur propre cadastre et ne figurent pas dans le Catastro central.

Paramètres

:refcatstringRéférence forale. Bizkaia avec des points (48.020.1611.02001) ; Álava et Gipuzkoa en chiffres (64010007, 8594149).
countrystringObligatoire : PV.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/48.020.1611.02001?country=PV"

Exemple de réponse

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 */ ]
  }
}

Avec country=ES (incorrect)

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

Portugal (PT)

Cadastre portugais — Direção-Geral do Território

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

Obtenir les données d'une parcelle portugaise par référence cadastrale.

Paramètres

:refcatstringRéférence cadastrale portugaise (p. ex. AAA000587359). La couverture est partielle (~30 %) ; des zones comme Lisbonne et Porto ne sont pas encore numérisées par la DGT.
countrystringObligatoire : PT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/AAA000587359?country=PT"

Exemple de réponse

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)

Cadastre français — Cadastre / Géoplateforme

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

Obtenir les données d'une parcelle française par référence cadastrale.

Paramètres

:refcatstringRéférence cadastrale française (p. ex. 75104000AE0003)
countrystringObligatoire : FR.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/75104000AE0003?country=FR"

Exemple de réponse

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 */ ]
  }
}

Italie (IT)

Cadastre italien — Agenzia delle Entrate

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

Obtenir les données d'une parcelle italienne par référence cadastrale.

Paramètres

:refcatstringRéférence catastale italienne (foglio/particella, p. ex. H501A048100.A)
countrystringObligatoire : IT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/H501A048100.A?country=IT"

Exemple de réponse

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 */ ]
  }
}

Allemagne (DE)

Cadastre allemand — ALKIS (8 Bundesländer)

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

Obtenir les données d'une parcelle allemande par référence cadastrale.

Paramètres

:refcatstringRéférence cadastrale allemande (Flurstückskennzeichen)
countrystringObligatoire : DE.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/05495803101122?country=DE"

Exemple de réponse

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 */ ]
  }
}

Autriche (AT)

Cadastre autrichien — BEV (Katastralgemeinde / Grundstück)

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

Consultation de parcelle en Autriche. Nécessite country=AT. La référence est KATASTRALGEMEINDE-GRUNDSTÜCK. Couverture partielle, en cours d’extension.

Paramètres

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

Exemple de réponse

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 */ ]
  }
}

Avec country=ES (incorrect)

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

Intelligence de parcelle et exports

Géométrie, potentiel solaire, données agricoles et exports de fichiers (KML/GPX/PDF/DXF), disponibles avec votre API key. Les données de marché et le score d'investissement restent sur le web et dans l'app (Pro) et ne sont pas exposés via l'API.

GET/api/catastro/:refcat/polygon

Obtenir le polygone GeoJSON d'une parcelle.

Paramètres

:refcatstringRéférence cadastrale
countrystringCode pays (paramètre de requête, par défaut : ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon"

Exemple de réponse

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

Quota mensuel épuisé

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

Obtenir les données de potentiel solaire (PVGIS) d'une parcelle européenne.

Paramètres

:refcatstringRéférence cadastrale
countrystringCode pays (paramètre de requête, par défaut : ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar"

Exemple de réponse

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

Parcelle sans données solaires

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

Données agricoles du terrain d’une parcelle (SIGPAC) : culture principale, usage du sol, pente, altitude et surface. Parcelles rurales uniquement — les parcelles urbaines renvoient "cultivo_principal": "urbano".

Paramètres

:refcatstringRéférence cadastrale
countrystringCode pays (paramètre de requête, par défaut : ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/23058A00700036/agro"

Exemple de réponse

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 mensuel épuisé

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

Exporter les données de parcelle au format KML (Google Earth).

Paramètres

refcatstringRéférence cadastrale
countrystringCode pays (facultatif : détecté à partir de la référence)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kml

Exemple de réponse

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

Exporter les données de parcelle au format GPX (navigateurs GPS).

Paramètres

refcatstringRéférence cadastrale
countrystringCode pays (facultatif : détecté à partir de la référence)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpx

Exemple de réponse

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>