Eine Eigentümergemeinschaft importieren
Um eine Eigentümergemeinschaft anzulegen, genügt ihre Adresse. In drei Aufrufen erhalten Sie die Referenz der Finca, alle Wohnungen, Gewerbeeinheiten, Garagen und Abstellräume (mit Nutzung, Fläche, Miteigentumsanteil, Treppenhaus, Stockwerk und Tür) und die Details jeder einzelnen Wohnung. Alle Antworten in dieser Anleitung sind echt und stammen aus der Produktion.
1. Von der Adresse zur Finca
GET /v1/search/address/candidates nimmt die Adresse als Freitext entgegen (Straße und Hausnummer, Gemeinde und, falls vorhanden, Postleitzahl) und liefert die passenden Hauseingänge, nach Konfidenz sortiert, jeweils mit ihrer 14-stelligen Katasterreferenz. Unabhängig vom Catastro: Die Geokodierung erfolgt mit CartoCiudad (IGN) und wird aus unserer Kopie des Catastro ergänzt. Die Felder lassen sich auch einzeln übergeben: street, number, municipality und postcode.
curl -G "https://api.parcelgps.com/v1/search/address/candidates" \
--data-urlencode "q=Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas" \
--data-urlencode "limit=3" \
-H "X-API-Key: $CATASTROGPS_API_KEY"Echte Antwort
200 OK{
"success": true,
"data": {
"query": {
"text": "Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas",
"street": "Avenida José Rodríguez de la Borbolla Camoyán",
"number": 10,
"municipality": "Dos Hermanas"
},
"candidates": [
{
"reference": "0745901TG4304N",
"country": "ES",
"address": "AVENIDA JOSE RGUEZ BORBOLLA CAMOY 10",
"number": 10,
"postalCode": "41704",
"municipality": "Dos Hermanas",
"region": "Sevilla",
"latitude": 37.31947088654626,
"longitude": -5.926788955974699,
"confidence": 0.93,
"numberMatches": true,
"municipalityMatches": true,
"inOwnCopy": true,
"cadastreAddress": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
"use": "Residencial",
"dwellings": 346,
"yearBuilt": 2023
},
{
"reference": "0747201TG4304N",
"country": "ES",
"address": "BULEVAR JOSE RODRIGUEZ DE LA BORBOLLA CAMOYAN 11",
"number": 11,
"confidence": 0.55,
"numberMatches": false,
"municipalityMatches": true,
"inOwnCopy": true
}
],
"attribution": "CartoCiudad (Instituto Geográfico Nacional) y Dirección General del Catastro"
},
"remainingSearches": 2894
}- Ab einer Konfidenz von 0,75 stimmen Hausnummer und Gemeinde überein: Sie können ohne Rückfrage importieren. Darunter zeigen Sie dem Nutzer die Kandidaten zur Auswahl.
- Im Baskenland und in Navarra kommt der Kandidat mit country PV oder NA und der foralen Referenz: Schritt 2 akzeptiert sie mit country=PV oder NA und listet die Einheiten aus unserer Kopie des jeweiligen foralen Katasters, ohne Miteigentumsanteil (die foralen Open Data veröffentlichen ihn nicht).
2. Alle Einheiten der Finca
GET /v1/parcels/:reference14/units liefert die Einheiten in Seiten zu höchstens 200, nach Referenz sortiert. Solange truncated true ist, wiederholen Sie den Aufruf mit cursor gleich nextCursor. propertyUnitCount nennt Ihnen schon auf der ersten Seite die Gesamtzahl.
curl -i "https://api.parcelgps.com/v1/parcels/0745901TG4304N/units" \
-H "X-API-Key: $CATASTROGPS_API_KEY"
curl -i "https://api.parcelgps.com/v1/parcels/0745901TG4304N/units?cursor=0745901TG4304N0201MZ" \
-H "X-API-Key: $CATASTROGPS_API_KEY"Echte Antwort
200 OKHTTP/2 200
etag: "5ab6bd3d95f85dddba81818bcb0cb65e"
cache-control: private, max-age=21600
x-quota-remaining: 2893
{
"success": true,
"data": {
"reference": "0745901TG4304N",
"address": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
"postalCode": "41704",
"municipality": "DOS HERMANAS",
"region": "Sevilla",
"mainUse": "Residencial",
"totalArea": 32789,
"yearBuilt": 2023,
"unitCount": 200,
"propertyUnitCount": 365,
"units": [
{
"reference": "0745901TG4304N0002KH",
"staircase": "",
"floor": "01",
"door": "B",
"use": "Residencial",
"area": 155,
"description": "Planta 01, Pta. B - Residencial",
"ownershipShare": 0.279543,
"yearBuilt": 2023,
"address": "AV JOSE RGUEZ BORBOLLA CAMOY 10 Pl:01 Pt:B"
},
{
"reference": "0745901TG4304N0003LJ",
"staircase": "",
"floor": "01",
"door": "C",
"use": "Residencial",
"area": 163,
"description": "Planta 01, Pta. C - Residencial",
"ownershipShare": 0.293879,
"yearBuilt": 2023,
"address": "AV JOSE RGUEZ BORBOLLA CAMOY 10 Pl:01 Pt:C"
}
],
"truncated": true,
"nextCursor": "0745901TG4304N0201MZ",
"dataSource": "clone",
"dataDate": "2026-01-23",
"attribution": "Dirección General del Catastro"
},
"remainingSearches": 2893
}- Eine Finca mit 365 Einheiten sind zwei Aufrufe: 200 und 165. Der Cursor ist stabil, sodass Sie einen abgebrochenen Import fortsetzen können.
- Pro Einheit: reference (20 Zeichen), use, area (m²), ownershipShare (Anteil in %, als Zahl mit voller Genauigkeit), staircase, floor, door, Baujahr und Adresse.
- dataSource clone bedeutet, dass die Daten aus unserer Kopie des Catastro stammen, unabhängig davon, ob das Catastro erreichbar ist; dataDate ist die Catastro-Veröffentlichung, aus der die Zeilen stammen. Ist eine Finca nicht in der Kopie, wird das Catastro live abgefragt (dataSource catastro).
3. Die Details einer Wohnung
GET /v1/parcels/:reference20 liefert eine bestimmte Wohnung mit denselben Feldern wie die Liste, dazu Koordinaten, Umriss und Fläche des Flurstücks.
curl "https://api.parcelgps.com/v1/parcels/0745901TG4304N0002KH" \
-H "X-API-Key: $CATASTROGPS_API_KEY"Echte Antwort
200 OK{
"success": true,
"data": {
"reference": "0745901TG4304N0002KH",
"country": "ES",
"address": "AV JOSE RGUEZ BORBOLLA CAMOY 10 Pl:01 Pt:B",
"postalCode": "41704",
"municipality": "DOS HERMANAS",
"region": "Sevilla",
"latitude": 37.3194709,
"longitude": -5.926789,
"use": "Residencial",
"landClass": "Urbano",
"builtArea": 155,
"parcelArea": 7320,
"yearBuilt": 2023,
"ownershipShare": 0.279543,
"floor": "01",
"door": "B",
"fromOwnCopy": true
},
"remainingSearches": 2892
}- ownershipShare, staircase, floor und door heißen genauso wie in der Liste. builtArea entspricht hier area in der Liste.
Erneut importieren, ohne Kontingent zu verbrauchen
Jede Einheitenseite und jede Adresssuche liefert ein ETag. Speichern Sie das ETag jeder Seite und senden Sie es beim nächsten Mal in If-None-Match: Hat sich nichts geändert, lautet die Antwort 304 ohne Body und verbraucht kein Kontingent.
curl -i "https://api.parcelgps.com/v1/parcels/0745901TG4304N/units" \
-H "X-API-Key: $CATASTROGPS_API_KEY" \
-H 'If-None-Match: "5ab6bd3d95f85dddba81818bcb0cb65e"'
HTTP/2 304
x-quota-remaining: 2929Der komplette Ablauf, mit Paginierung, Wiederholungen und ETag
Wiederholt 429- und 503-Antworten mit Retry-After, wirft die übrigen Fehler mit ihrem code und verwendet unveränderte Seiten wieder.
const BASE = "https://api.parcelgps.com/v1";
const KEY = process.env.CATASTROGPS_API_KEY;
async function call(path, etag) {
for (let attempt = 0; attempt < 5; attempt++) {
const headers = { "X-API-Key": KEY };
if (etag) headers["If-None-Match"] = etag;
const res = await fetch(BASE + path, { headers });
if (res.status === 304) return { data: null, etag };
const retryAfter = res.headers.get("Retry-After");
if ((res.status === 429 || res.status === 503) && retryAfter) {
await new Promise((resolve) => setTimeout(resolve, Number(retryAfter) * 1000));
continue;
}
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.code}: ${body.message}`);
return { data: body.data, etag: res.headers.get("ETag") };
}
throw new Error("retries exhausted");
}
export async function findBuilding(address) {
const { data } = await call("/search/address/candidates?q=" + encodeURIComponent(address));
const best = data.candidates[0];
if (best.confidence < 0.75) throw new Error("Ambiguous address: ask the user to pick a candidate");
return best.reference;
}
export async function importUnits(reference14, pages = new Map()) {
const units = [];
let cursor = "";
for (;;) {
const cached = pages.get(cursor);
const query = cursor ? "?cursor=" + cursor : "";
const { data, etag } = await call(`/parcels/${reference14}/units${query}`, cached?.etag);
const page = data ?? cached.data;
pages.set(cursor, { etag, data: page });
units.push(...page.units);
if (!page.truncated) return { units, pages };
cursor = page.nextCursor;
}
}
const reference14 = await findBuilding("Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas");
const { units, pages } = await importUnits(reference14);
console.log(reference14, units.length);Was es kostet
| Aufruf | Kontingenteinheiten |
|---|---|
| GET /v1/search/address/candidates | 1 pro Suche mit Ergebnissen. |
| GET /v1/parcels/:reference14/units | 1 pro Einheit auf der Seite (mindestens 1). Eine Seite mit 200 Einheiten kostet 200. |
| GET /v1/parcels/:reference | 1 pro Wohnung. |
| 304 / 4xx / 5xx | Kostenlos: Weder ein 304 noch ein Fehler verbraucht Kontingent. |
Beispiel: Eine Gemeinschaft mit 365 Einheiten kostet 1 (Adresse) + 200 + 165 (zwei Seiten) = 366 Einheiten. Ein erneuter Import ohne Änderungen kostet 0.
Fehler
| HTTP | Code | Bedeutung und was zu tun ist |
|---|---|---|
| 304 | - | Seit Ihrem ETag hat sich nichts geändert. Verwenden Sie, was Sie bereits haben. Kostenlos. |
| 400 | VALIDATION_ERROR | Fehlerhafte Parameter (leere Adresse, Postleitzahl ohne 5 Ziffern, Cursor einer anderen Finca). Korrigieren Sie die Anfrage. |
| 401 | KEY_AUTH_001 / 002 / 003 | Der API-Schlüssel fehlt oder ist ungültig. |
| 404 | NOT_FOUND | Die Adresse oder die Referenz existiert nicht. Wird nie für Ausfälle des Catastro verwendet. |
| 429 | KEY_RATE_002 | Sie haben die Anfragen pro Minute Ihres Schlüssels überschritten. Warten Sie die Sekunden aus Retry-After ab. |
| 429 | KEY_AUTH_004 | Kontingent und Guthaben aufgebraucht (siehe X-Quota-Remaining und X-Quota-Reset): Laden Sie im Portal auf oder warten Sie auf das Zurücksetzen am 1. des Monats. |
| 503 | SERVICE_UNAVAILABLE | Die amtliche Quelle (Catastro oder CartoCiudad) ist ausgefallen oder überlastet, und unsere Kopie hat die Daten nicht. Nach Retry-After erneut versuchen. Kostenlos. |
{
"success": false,
"code": "NOT_FOUND",
"message": "No building entrance (portal) with a cadastral reference matches that address. Include the street number and the municipality."
}Vollständige Referenz
Alle Endpunkte, Felder und Codes stehen in der OpenAPI-3.1-Spezifikation, die Sie in Postman, Insomnia oder einen Client-Generator importieren können: https://api.parcelgps.com/v1/openapi.json