Importar una comunitat de propietaris

Per donar d'alta una comunitat n'hi ha prou amb la seva adreça. En tres crides obtens la referència de la finca, tots els seus habitatges, locals, garatges i trasters (amb ús, superfície, coeficient de participació, escala, planta i porta) i el detall de qualsevol habitatge. Les respostes d'aquesta guia són reals, tretes de producció.

data_object Especificació OpenAPI 3.1 key Aconseguir una API key

1. De l'adreça a la finca

GET /v1/search/address/candidates rep l'adreça en text lliure (carrer i número, municipi i, si el tens, codi postal) i retorna els portals que hi encaixen, ordenats per confiança, cadascun amb la seva referència cadastral de 14 caràcters. No depèn del Catastro: geocodifica amb CartoCiudad (IGN) i completa amb la nostra còpia del Catastro. També accepta els camps per separat: street, number, municipality i 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"

Resposta real

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
}

Amb una confiança de 0,75 o més coincideixen el número i el municipi: pots importar sense preguntar. Per sota, mostra els candidats a l'usuari perquè triï.
Al País Basc i a Navarra el candidat arriba amb country PV o NA i la referència foral: el pas 2 l'accepta amb country=PV o NA i llista les unitats des de la còpia del seu cadastre foral, sense coeficient de participació (les dades obertes forals no el publiquen).

2. Totes les unitats de la finca

GET /v1/parcels/:reference14/units retorna les unitats en pàgines de fins a 200, ordenades per referència. Mentre truncated sigui true, repeteix la crida amb cursor igual a nextCursor. propertyUnitCount et diu des de la primera pàgina quantes n'hi ha en total.

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"

Resposta real

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
}

Una finca de 365 unitats són dues crides: 200 i 165. El cursor és estable, així que pots reprendre una importació interrompuda.
Per unitat: reference (20 caràcters), use, area (m²), ownershipShare (coeficient en %, número amb tota la precisió), staircase, floor, door, any i adreça.
dataSource clone vol dir que surt de la nostra còpia del Catastro, sense dependre que el Catastro estigui en marxa; dataDate és la publicació del Catastro d'on vénen les files. Si una finca no és a la còpia, es consulta el Catastro en directe (dataSource catastro).

3. El detall d'un habitatge

GET /v1/parcels/:reference20 retorna un habitatge concret amb els mateixos camps que el llistat, a més de les coordenades, el contorn i la superfície de la parcel·la.

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

Resposta real

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 i door es diuen igual que al llistat. builtArea aquí és area al llistat.

Reimportar sense gastar quota

Cada pàgina d'unitats i cada cerca d'adreça porten ETag. Desa l'ETag de cada pàgina i envia'l a If-None-Match la propera vegada: si no ha canviat res, la resposta és 304 sense cos i no gasta quota.

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

El flux complet, amb paginació, reintents i ETag

Reintenta els 429 i 503 que porten Retry-After, llança la resta d'errors amb el seu code i reutilitza les pàgines que no han canviat.

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

Quant costa

Crida	Unitats de quota
GET /v1/search/address/candidates	1 per cerca amb resultats.
GET /v1/parcels/:reference14/units	1 per cada unitat de la pàgina (mínim 1). Una pàgina de 200 són 200.
GET /v1/parcels/:reference	1 per habitatge.
304 / 4xx / 5xx	Gratis: ni un 304 ni un error gasten quota.

Exemple: una comunitat de 365 unitats costa 1 (adreça) + 200 + 165 (dues pàgines) = 366 unitats. Reimportar-la sense canvis costa 0.

Errors

HTTP	Codi	Què vol dir i què cal fer
304	-	No ha canviat res des del teu ETag. Fes servir el que tenies. Gratis.
400	VALIDATION_ERROR	Paràmetres mal formats (adreça buida, codi postal sense 5 dígits, cursor que no és d'aquesta finca). Corregeix la petició.
401	KEY_AUTH_001 / 002 / 003	Falta l'API key o no és vàlida.
404	NOT_FOUND	L'adreça o la referència no existeixen. Mai no s'usa per a caigudes del Catastro.
429	KEY_RATE_002	Has superat les peticions per minut de la teva clau. Espera els segons de Retry-After.
429	KEY_AUTH_004	Quota i saldo esgotats (mira X-Quota-Remaining i X-Quota-Reset): recarrega al portal o espera el reinici del dia 1.
503	SERVICE_UNAVAILABLE	La font oficial (Catastro o CartoCiudad) està caiguda o saturada i la nostra còpia no té la dada. Reintenta-ho després de 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."
}

Referència completa

Tots els endpoints, camps i codis són a l'especificació OpenAPI 3.1, que pots importar a Postman, Insomnia o un generador de clients: https://api.parcelgps.com/v1/openapi.json