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 OK
HTTP/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: 2929

Der 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

AufrufKontingenteinheiten
GET /v1/search/address/candidates1 pro Suche mit Ergebnissen.
GET /v1/parcels/:reference14/units1 pro Einheit auf der Seite (mindestens 1). Eine Seite mit 200 Einheiten kostet 200.
GET /v1/parcels/:reference1 pro Wohnung.
304 / 4xx / 5xxKostenlos: 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

HTTPCodeBedeutung und was zu tun ist
304-Seit Ihrem ETag hat sich nichts geändert. Verwenden Sie, was Sie bereits haben. Kostenlos.
400VALIDATION_ERRORFehlerhafte Parameter (leere Adresse, Postleitzahl ohne 5 Ziffern, Cursor einer anderen Finca). Korrigieren Sie die Anfrage.
401KEY_AUTH_001 / 002 / 003Der API-Schlüssel fehlt oder ist ungültig.
404NOT_FOUNDDie Adresse oder die Referenz existiert nicht. Wird nie für Ausfälle des Catastro verwendet.
429KEY_RATE_002Sie haben die Anfragen pro Minute Ihres Schlüssels überschritten. Warten Sie die Sekunden aus Retry-After ab.
429KEY_AUTH_004Kontingent 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.
503SERVICE_UNAVAILABLEDie 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