Importare un condominio

Per registrare un condominio basta il suo indirizzo. In tre chiamate ottieni il riferimento della finca, tutte le sue abitazioni, negozi, box e cantine (con uso, superficie, quota di partecipazione, scala, piano e interno) e il dettaglio di qualsiasi abitazione. Le risposte di questa guida sono reali, prese dalla produzione.

data_object Specifica OpenAPI 3.1 key Ottieni una API key

1. Dall'indirizzo alla finca

GET /v1/search/address/candidates riceve l'indirizzo in testo libero (via e numero civico, comune e, se ce l'hai, CAP) e restituisce i portoni corrispondenti, ordinati per affidabilità, ciascuno con il suo riferimento catastale di 14 caratteri. Non dipende dal Catastro: geocodifica con CartoCiudad (IGN) e completa con la nostra copia del Catastro. Accetta anche i campi separati: street, number, municipality e 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"

Risposta reale

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
}

Con un'affidabilità di 0,75 o più coincidono numero civico e comune: puoi importare senza chiedere. Al di sotto, mostra i candidati all'utente perché scelga.
Nei Paesi Baschi e in Navarra il candidato arriva con country PV o NA e il riferimento forale: il passo 2 lo accetta con country=PV o NA ed elenca le unità dalla copia del suo catasto forale, senza quota di partecipazione (i dati aperti forali non la pubblicano).

2. Tutte le unità della finca

GET /v1/parcels/:reference14/units restituisce le unità in pagine fino a 200, ordinate per riferimento. Finché truncated è true, ripeti la chiamata con cursor uguale a nextCursor. propertyUnitCount ti dice già dalla prima pagina quante sono in totale.

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"

Risposta reale

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 di 365 unità richiede due chiamate: 200 e 165. Il cursore è stabile, quindi puoi riprendere un'importazione interrotta.
Per unità: reference (20 caratteri), use, area (m²), ownershipShare (quota in %, numero a piena precisione), staircase, floor, door, anno e indirizzo.
dataSource clone significa che il dato viene dalla nostra copia del Catastro, senza dipendere dal fatto che il Catastro sia attivo; dataDate è la pubblicazione del Catastro da cui provengono le righe. Se una finca non è nella copia, si interroga il Catastro in tempo reale (dataSource catastro).

3. Il dettaglio di un'abitazione

GET /v1/parcels/:reference20 restituisce una singola abitazione con gli stessi campi dell'elenco, più coordinate, contorno e superficie della particella.

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

Risposta reale

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 e door hanno lo stesso nome dell'elenco. builtArea qui corrisponde a area nell'elenco.

Reimportare senza consumare quota

Ogni pagina di unità e ogni ricerca per indirizzo hanno un ETag. Salva l'ETag di ogni pagina e invialo in If-None-Match la volta successiva: se non è cambiato nulla, la risposta è 304 senza corpo e non consuma 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

Il flusso completo, con paginazione, tentativi ripetuti ed ETag

Ripete le risposte 429 e 503 che hanno Retry-After, solleva gli altri errori con il loro code e riutilizza le pagine che non sono cambiate.

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

Quanto costa

Chiamata	Unità di quota
GET /v1/search/address/candidates	1 per ricerca con risultati.
GET /v1/parcels/:reference14/units	1 per ogni unità della pagina (minimo 1). Una pagina da 200 costa 200.
GET /v1/parcels/:reference	1 per abitazione.
304 / 4xx / 5xx	Gratis: né un 304 né un errore consumano quota.

Esempio: un condominio di 365 unità costa 1 (indirizzo) + 200 + 165 (due pagine) = 366 unità. Reimportarlo senza modifiche costa 0.

Errori

HTTP	Codice	Cosa significa e cosa fare
304	-	Nulla è cambiato dal tuo ETag. Usa quello che avevi. Gratis.
400	VALIDATION_ERROR	Parametri non validi (indirizzo vuoto, CAP senza 5 cifre, cursore di un'altra finca). Correggi la richiesta.
401	KEY_AUTH_001 / 002 / 003	La API key manca o non è valida.
404	NOT_FOUND	L'indirizzo o il riferimento non esistono. Non si usa mai per i disservizi del Catastro.
429	KEY_RATE_002	Hai superato le richieste al minuto della tua chiave. Attendi i secondi indicati da Retry-After.
429	KEY_AUTH_004	Quota e saldo esauriti (vedi X-Quota-Remaining e X-Quota-Reset): ricarica dal portale o attendi l'azzeramento del giorno 1.
503	SERVICE_UNAVAILABLE	La fonte ufficiale (Catastro o CartoCiudad) è non disponibile o satura e la nostra copia non ha il dato. Riprova dopo 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."
}

Riferimento completo

Tutti gli endpoint, i campi e i codici sono nella specifica OpenAPI 3.1, che puoi importare in Postman, Insomnia o in un generatore di client: https://api.parcelgps.com/v1/openapi.json