Importar una comunidad de propietarios

Al dar de alta una comunidad basta con su dirección. En tres llamadas obtienes la referencia de la finca, todas sus viviendas, locales, garajes y trasteros (con uso, superficie, coeficiente de participación, escalera, planta y puerta) y el detalle de cualquier vivienda. Las respuestas de esta guía son reales, sacadas de producción.

data_object Especificación OpenAPI 3.1 key Conseguir una API key

1. De la dirección a la finca

GET /api/search/address/candidates recibe la dirección en texto libre (calle y número, municipio y, si lo tienes, código postal) y devuelve los portales que encajan, ordenados por confianza, cada uno con su referencia catastral de 14 caracteres. No depende del Catastro: geocodifica con CartoCiudad (IGN) y completa con nuestra copia del Catastro. También acepta los campos por separado: street, number, municipality y postcode.

curl -G "https://api.parcelgps.com/api/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"

Respuesta real

200 OK

{
  "success": true,
  "data": {
    "consulta": {
      "texto": "Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas",
      "calle": "Avenida José Rodríguez de la Borbolla Camoyán",
      "numero": 10,
      "municipio": "Dos Hermanas"
    },
    "candidatos": [
      {
        "refCatastral": "0745901TG4304N",
        "pais": "ES",
        "direccion": "AVENIDA JOSE RGUEZ BORBOLLA CAMOY 10",
        "numero": 10,
        "codigoPostal": "41704",
        "municipio": "Dos Hermanas",
        "provincia": "Sevilla",
        "latitud": 37.31947088654626,
        "longitud": -5.926788955974699,
        "confianza": 0.93,
        "coincideNumero": true,
        "coincideMunicipio": true,
        "enCopia": true,
        "direccionCatastro": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
        "uso": "Residencial",
        "viviendas": 346,
        "anioConstruccion": 2023
      },
      {
        "refCatastral": "0747201TG4304N",
        "pais": "ES",
        "direccion": "BULEVAR JOSE RODRIGUEZ DE LA BORBOLLA CAMOYAN 11",
        "numero": 11,
        "confianza": 0.55,
        "coincideNumero": false,
        "coincideMunicipio": true,
        "enCopia": true
      }
    ],
    "attribution": "CartoCiudad (Instituto Geográfico Nacional) y Dirección General del Catastro"
  }
}

Con confianza de 0,75 o más coinciden el número y el municipio: puedes importar sin preguntar. Por debajo, enseña los candidatos al usuario para que elija.
En el País Vasco y Navarra el candidato llega con pais PV o NA y la referencia foral: el paso 2 la acepta con country=PV o NA y lista las unidades desde la copia de su catastro foral, sin coeficiente de participación (los datos abiertos forales no lo publican).

2. Todas las unidades de la finca

GET /api/catastro//units devuelve las unidades en páginas de hasta 200, ordenadas por referencia. Mientras truncated sea true, repite la llamada con cursor igual a nextCursor. totalUnidadesFinca te dice desde la primera página cuántas hay en total.

curl -i "https://api.parcelgps.com/api/catastro/0745901TG4304N/units" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

curl -i "https://api.parcelgps.com/api/catastro/0745901TG4304N/units?cursor=0745901TG4304N0201MZ" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Respuesta real

200 OK

HTTP/2 200
etag: "5ab6bd3d95f85dddba81818bcb0cb65e"
cache-control: private, max-age=21600
x-quota-remaining: 2893

{
  "success": true,
  "data": {
    "refCatastral": "0745901TG4304N",
    "direccion": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
    "codigoPostal": "41704",
    "municipio": "DOS HERMANAS",
    "provincia": "Sevilla",
    "usoGeneral": "Residencial",
    "superficieTotal": 32789,
    "anioConstruccion": 2023,
    "totalUnidades": 200,
    "totalUnidadesFinca": 365,
    "unidades": [
      {
        "refCatastral": "0745901TG4304N0002KH",
        "escalera": "",
        "planta": "01",
        "puerta": "B",
        "uso": "Residencial",
        "superficie": 155,
        "descripcion": "Planta 01, Pta. B - Residencial",
        "participacion": 0.279543,
        "anio": 2023,
        "direccion": "AV JOSE RGUEZ BORBOLLA CAMOY 10 Pl:01 Pt:B"
      },
      {
        "refCatastral": "0745901TG4304N0003LJ",
        "escalera": "",
        "planta": "01",
        "puerta": "C",
        "uso": "Residencial",
        "superficie": 163,
        "descripcion": "Planta 01, Pta. C - Residencial",
        "participacion": 0.293879,
        "anio": 2023,
        "direccion": "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"
  },
  "searchesRemaining": -1
}

Una finca de 365 unidades son dos llamadas: 200 y 165. El cursor es estable, así que puedes reanudar una importación cortada.
Por unidad: refCatastral (20 caracteres), uso, superficie (m²), participacion (coeficiente en %, número con toda la precisión), escalera, planta, puerta, año y dirección.
dataSource clone significa que sale de nuestra copia del Catastro, sin depender de que el Catastro esté en pie; dataDate es la publicación del Catastro de la que vienen las filas. Si una finca no está en la copia se consulta al Catastro en vivo (dataSource catastro).

3. El detalle de una vivienda

GET /api/catastro/ devuelve una vivienda concreta con los mismos campos que el listado, además de coordenadas, contorno y superficie de la parcela.

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

Respuesta real

200 OK

{
  "success": true,
  "data": {
    "dataSource": "local_clone",
    "refCatastral": "0745901TG4304N0002KH",
    "pais": "ES",
    "direccion": "AV JOSE RGUEZ BORBOLLA CAMOY 10 Pl:01 Pt:B",
    "codigoPostal": "41704",
    "municipio": "DOS HERMANAS",
    "provincia": "Sevilla",
    "latitud": 37.3194709,
    "longitud": -5.926789,
    "uso": "Residencial",
    "clase": "Urbano",
    "superficieConstruida": 155,
    "superficieParcela": 7320,
    "anioConstruccion": 2023,
    "coefParticipacion": "0.28",
    "participacion": 0.279543,
    "planta": "01",
    "puerta": "B"
  }
}

participacion, escalera, planta y puerta se llaman igual que en el listado. superficieConstruida aquí es superficie en el listado. coefParticipacion (texto redondeado a 2 decimales) se mantiene por compatibilidad.

Reimportar sin gastar cuota

Cada página de unidades y cada búsqueda de dirección llevan ETag. Guarda el ETag de cada página y mándalo en If-None-Match la próxima vez: si nada ha cambiado, la respuesta es 304 sin cuerpo y no gasta cuota.

curl -i "https://api.parcelgps.com/api/catastro/0745901TG4304N/units" \
  -H "X-API-Key: $CATASTROGPS_API_KEY" \
  -H 'If-None-Match: "5ab6bd3d95f85dddba81818bcb0cb65e"'

HTTP/2 304
x-quota-remaining: 2929

El flujo completo, con paginación, reintentos y ETag

Reintenta los 429 y 503 que traen Retry-After, lanza el resto de errores con su code y reutiliza las páginas que no han cambiado.

const BASE = "https://api.parcelgps.com";
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.error}`);
    return { data: body.data, etag: res.headers.get("ETag") };
  }
  throw new Error("retries exhausted");
}

export async function findFinca(address) {
  const { data } = await call("/api/search/address/candidates?q=" + encodeURIComponent(address));
  const best = data.candidatos[0];
  if (best.confianza < 0.75) throw new Error("Ambiguous address: ask the user to pick a candidate");
  return best.refCatastral;
}

export async function importUnits(refcat14, pages = new Map()) {
  const units = [];
  let cursor = "";
  for (;;) {
    const cached = pages.get(cursor);
    const query = cursor ? "?cursor=" + cursor : "";
    const { data, etag } = await call(`/api/catastro/${refcat14}/units${query}`, cached?.etag);
    const page = data ?? cached.data;
    pages.set(cursor, { etag, data: page });
    units.push(...page.unidades);
    if (!page.truncated) return { units, pages };
    cursor = page.nextCursor;
  }
}

const refcat14 = await findFinca("Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas");
const { units, pages } = await importUnits(refcat14);
console.log(refcat14, units.length);

Cuánto cuesta

Llamada	Unidades de cuota
GET /api/search/address/candidates	1 por búsqueda con resultados.
GET /api/catastro/:refcat14/units	1 por cada unidad de la página (mínimo 1). Una página de 200 son 200.
GET /api/catastro/:refcat	1 por vivienda.
304 / 4xx / 5xx	Gratis: ni un 304 ni un error gastan cuota.

Ejemplo: una comunidad de 365 unidades cuesta 1 (dirección) + 200 + 165 (dos páginas) = 366 unidades. Reimportarla sin cambios cuesta 0.

Errores

HTTP	Código	Qué significa y qué hacer
304	-	Nada ha cambiado desde tu ETag. Usa lo que tenías. Gratis.
400	VALIDATION_ERROR	Parámetros mal formados (dirección vacía, código postal sin 5 dígitos, cursor que no es de esa finca). Corrige la petición.
401	KEY_AUTH_001 / 002 / 003	Falta la API key o no es válida.
404	NOT_FOUND	La dirección o la referencia no existen. Nunca se usa para caídas del Catastro.
429	KEY_RATE_002	Has superado las peticiones por minuto de tu clave. Espera los segundos de Retry-After.
429	KEY_AUTH_004	Cuota y saldo agotados (mira X-Quota-Remaining y X-Quota-Reset): recarga en el portal o espera al reinicio del día 1.
503	SERVICE_UNAVAILABLE	La fuente oficial (Catastro o CartoCiudad) está caída o saturada y nuestra copia no tiene el dato. Reintenta tras Retry-After. Gratis.

{
  "success": false,
  "code": "NOT_FOUND",
  "error": "No building entrance (portal) with a cadastral reference matches that address. Include the street number and the municipality."
}

Referencia completa

Todos los endpoints, campos y códigos están en la especificación OpenAPI 3.1, que puedes importar en Postman, Insomnia o un generador de clientes: https://api.parcelgps.com/api/openapi.json