Documentation API
Référence complète de l'API cadastrale
Base URL
https://api.parcelgps.comCodes 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.
Référence des endpoints
| Méthode | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/resolve?q=TEXT | API Key | Classe n'importe quelle saisie : référence (et pays), coordonnées ou toponyme. Hors quota. |
| GET | /api/catastro/:refcat | API Key | Consultation de parcelle |
| GET | /api/catastro/:refcat/polygon?country=XX | API Key | Géométrie de la parcelle (GeoJSON) |
| GET | /api/catastro/:refcat/solar?country=XX | API Key | Potentiel solaire |
| GET | /api/catastro/:refcat/agro?country=XX | API Key | Données agricoles du terrain |
| GET | /api/export/kml?refcat=X&country=X | API Key | Exporter KML/GPX/PDF/DXF |
| GET | /api/catastro/:refcat/market?country=XX | Web et app | Données de marché (pas via l'API) |
| GET | /api/catastro/:refcat/score?country=XX | Web et app | Score 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.
| Endpoint | D'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/coordinates | Catastro (organisme public). Peut tomber sans préavis. |
| /agro | SIGPAC |
| /solar | PVGIS |
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
| Statut | Code | Description |
|---|---|---|
| 200 | — | OK — La requête s'est terminée correctement. |
| 400 | VALIDATION_ERROR | Bad Request — Paramètres invalides ou référence cadastrale au format incorrect. |
| 401 | UNAUTHORIZED | Unauthorized — API key invalide, expirée ou absente. |
| 404 | NOT_FOUND | Not Found — Aucune parcelle trouvée pour la référence ou les coordonnées indiquées. Ne consomme pas de quota. |
| 429 | KEY_AUTH_004 | Quota 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. |
| 429 | RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | Too 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). |
| 500 | INTERNAL_ERROR | Internal Server Error — Erreur sur notre serveur. Si elle persiste, contactez le support. |
| 503 | SERVICE_UNAVAILABLE | Service 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ête | Description |
|---|---|
| X-RateLimit-Limit | Limite mensuelle totale de votre forfait (p. ex. 5000). |
| X-RateLimit-Remaining | Appels restants ce mois-ci. |
| X-RateLimit-Reset | Date de réinitialisation du quota (ISO 8601). |
| X-Quota-Tier | Nom de l’offre actuelle (free, basic, pro, business). |
Espagne (ES)
Cadastre espagnol — Dirección General del Catastro
/api/catastro/:refcatObtenir les données d'une parcelle par référence cadastrale (14 ou 20 caractères).
Paramètres
| :refcat | string | Ré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
| Code | HTTP | Description |
|---|---|---|
| VALIDATION_ERROR | 400 | La référence n'a pas un format valide pour le pays. |
| NOT_FOUND | 404 | Ré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_REACHED | 429 | Limite de recherches gratuites par IP et par jour. |
| KEY_AUTH_004 | 429 | Quota mensuel de l’API key épuisé (voir les en-têtes X-RateLimit-*). |
| SERVICE_UNAVAILABLE | 503 | Le service cadastral officiel du pays est en panne ou en maintenance. Réessayez. |
/api/search/coordinatesGéocodage inverse : trouver la parcelle cadastrale à des coordonnées GPS.
Paramètres
| latitude | number | Latitude (WGS84) |
| longitude | number | Longitude (WGS84) |
| country | string | Code 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
| Code | HTTP | Description |
|---|---|---|
| VALIDATION_ERROR | 400 | Coordonnées hors des limites du pays indiqué ou détecté, ou lat/lng absentes ou mal formées. |
| NOT_FOUND | 404 | Il n'y a aucune parcelle à ces coordonnées. |
| RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | 429 | Limite de recherches gratuites par IP et par jour. |
| SERVICE_UNAVAILABLE | 503 | Service cadastral temporairement indisponible. |
/api/search/address/parseRechercher une parcelle cadastrale par adresse postale.
Paramètres
| direccion | string | Adresse 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
| Code | HTTP | Description |
|---|---|---|
| VALIDATION_ERROR | 400 | Corps de requête invalide (champs manquants ou JSON mal formé). |
| NOT_FOUND | 404 | Adresse 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_REACHED | 429 | Limite de recherches gratuites par IP et par jour. |
Pays basque (PV)
Cadastres foraux — Araba/Álava, Bizkaia et Gipuzkoa (WFS INSPIRE)
/api/catastro/:refcat?country=PVConsultation 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
| :refcat | string | Référence forale. Bizkaia avec des points (48.020.1611.02001) ; Álava et Gipuzkoa en chiffres (64010007, 8594149). |
| country | string | Obligatoire : 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
/api/catastro/:refcat?country=PTObtenir les données d'une parcelle portugaise par référence cadastrale.
Paramètres
| :refcat | string | Ré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. |
| country | string | Obligatoire : 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
/api/catastro/:refcat?country=FRObtenir les données d'une parcelle française par référence cadastrale.
Paramètres
| :refcat | string | Référence cadastrale française (p. ex. 75104000AE0003) |
| country | string | Obligatoire : 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
/api/catastro/:refcat?country=ITObtenir les données d'une parcelle italienne par référence cadastrale.
Paramètres
| :refcat | string | Référence catastale italienne (foglio/particella, p. ex. H501A048100.A) |
| country | string | Obligatoire : 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)
/api/catastro/:refcat?country=DEObtenir les données d'une parcelle allemande par référence cadastrale.
Paramètres
| :refcat | string | Référence cadastrale allemande (Flurstückskennzeichen) |
| country | string | Obligatoire : 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)
/api/catastro/:refcat?country=ATConsultation de parcelle en Autriche. Nécessite country=AT. La référence est KATASTRALGEMEINDE-GRUNDSTÜCK. Couverture partielle, en cours d’extension.
Paramètres
| :refcat | string | Format Katastralgemeinde-Grundstück (p. ex. 01004-1711). |
| country | string | Obligatoire : 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.
/api/catastro/:refcat/polygonObtenir le polygone GeoJSON d'une parcelle.
Paramètres
| :refcat | string | Référence cadastrale |
| country | string | Code 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"
}/api/catastro/:refcat/solarObtenir les données de potentiel solaire (PVGIS) d'une parcelle européenne.
Paramètres
| :refcat | string | Référence cadastrale |
| country | string | Code 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" }
}/api/catastro/:refcat/agroDonné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
| :refcat | string | Référence cadastrale |
| country | string | Code 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"
}/api/export/kml?refcat=:refcatExporter les données de parcelle au format KML (Google Earth).
Paramètres
| refcat | string | Référence cadastrale |
| country | string | Code 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.kmlExemple 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>/api/export/gpx?refcat=:refcatExporter les données de parcelle au format GPX (navigateurs GPS).
Paramètres
| refcat | string | Référence cadastrale |
| country | string | Code 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.gpxExemple 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>