Een VvE importeren

Om een VvE aan te maken heb je alleen het adres nodig. In drie aanroepen krijg je de referentie van het gebouw (finca), al zijn woningen, bedrijfsruimtes, garages en bergingen (met gebruik, oppervlakte, aandeel, trappenhuis, verdieping en deur) en de details van elke woning. Alle antwoorden in deze gids zijn echt en komen uit productie.

1. Van adres naar finca

GET /v1/search/address/candidates neemt het adres als vrije tekst (straat en huisnummer, gemeente en, als je die hebt, postcode) en geeft de passende ingangen terug, gesorteerd op betrouwbaarheid, elk met zijn kadastrale referentie van 14 tekens. Niet afhankelijk van het Catastro: geocodeert met CartoCiudad (IGN) en vult aan uit onze kopie van het Catastro. De velden kunnen ook los worden meegegeven: street, number, municipality en 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"

Echt antwoord

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
}
  • Vanaf een betrouwbaarheid van 0,75 kloppen huisnummer en gemeente: je kunt importeren zonder te vragen. Daaronder laat je de kandidaten aan de gebruiker zien om te kiezen.
  • In Baskenland en Navarra komt de kandidaat met country PV of NA en de forale referentie: stap 2 accepteert die met country=PV of NA en geeft de eenheden uit onze kopie van het betreffende forale kadaster, zonder aandeel (de forale open data publiceren dat niet).

2. Alle eenheden van de finca

GET /v1/parcels/:reference14/units geeft de eenheden in pagina's van maximaal 200, gesorteerd op referentie. Zolang truncated true is, herhaal je de aanroep met cursor gelijk aan nextCursor. propertyUnitCount vertelt je al op de eerste pagina hoeveel het er in totaal zijn.

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"

Echt antwoord

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
}
  • Een finca met 365 eenheden zijn twee aanroepen: 200 en 165. De cursor is stabiel, dus een onderbroken import kun je hervatten.
  • Per eenheid: reference (20 tekens), use, area (m²), ownershipShare (aandeel in %, als getal met volledige precisie), staircase, floor, door, bouwjaar en adres.
  • dataSource clone betekent dat het uit onze kopie van het Catastro komt, ongeacht of het Catastro bereikbaar is; dataDate is de publicatie van het Catastro waar de rijen vandaan komen. Staat een finca niet in de kopie, dan wordt het Catastro live geraadpleegd (dataSource catastro).

3. De details van een woning

GET /v1/parcels/:reference20 geeft één woning met dezelfde velden als de lijst, plus coördinaten, contour en oppervlakte van het perceel.

curl "https://api.parcelgps.com/v1/parcels/0745901TG4304N0002KH" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Echt antwoord

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 en door heten hetzelfde als in de lijst. builtArea is hier wat in de lijst area heet.

Opnieuw importeren zonder quotum te verbruiken

Elke pagina met eenheden en elke adreszoekopdracht heeft een ETag. Bewaar de ETag van elke pagina en stuur die de volgende keer mee in If-None-Match: is er niets veranderd, dan is het antwoord 304 zonder body en kost het geen quotum.

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

De volledige flow, met paginering, nieuwe pogingen en ETag

Probeert 429- en 503-antwoorden met Retry-After opnieuw, gooit de overige fouten met hun code en hergebruikt pagina's die niet zijn veranderd.

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);

Wat het kost

AanroepQuotumeenheden
GET /v1/search/address/candidates1 per zoekopdracht met resultaten.
GET /v1/parcels/:reference14/units1 per eenheid op de pagina (minimaal 1). Een pagina van 200 kost 200.
GET /v1/parcels/:reference1 per woning.
304 / 4xx / 5xxGratis: een 304 of een fout kost geen quotum.

Voorbeeld: een VvE van 365 eenheden kost 1 (adres) + 200 + 165 (twee pagina's) = 366 eenheden. Ongewijzigd opnieuw importeren kost 0.

Fouten

HTTPCodeWat het betekent en wat je moet doen
304-Er is niets veranderd sinds je ETag. Gebruik wat je al had. Gratis.
400VALIDATION_ERROROngeldige parameters (leeg adres, postcode zonder 5 cijfers, cursor van een andere finca). Corrigeer het verzoek.
401KEY_AUTH_001 / 002 / 003De API-sleutel ontbreekt of is ongeldig.
404NOT_FOUNDHet adres of de referentie bestaat niet. Wordt nooit gebruikt bij storingen van het Catastro.
429KEY_RATE_002Je hebt het aantal verzoeken per minuut van je sleutel overschreden. Wacht het aantal seconden uit Retry-After.
429KEY_AUTH_004Quotum en tegoed op (zie X-Quota-Remaining en X-Quota-Reset): waardeer op in het portaal of wacht op de reset op de 1e van de maand.
503SERVICE_UNAVAILABLEDe officiële bron (Catastro of CartoCiudad) is uitgevallen of overbelast en onze kopie heeft de gegevens niet. Probeer het opnieuw na Retry-After. Gratis.
{
  "success": false,
  "code": "NOT_FOUND",
  "message": "No building entrance (portal) with a cadastral reference matches that address. Include the street number and the municipality."
}

Volledige referentie

Alle endpoints, velden en codes staan in de OpenAPI 3.1-specificatie, die je kunt importeren in Postman, Insomnia of een clientgenerator: https://api.parcelgps.com/v1/openapi.json