Import společenství vlastníků

K zaevidování společenství vlastníků stačí jeho adresa. Ve třech voláních získáte referenci budovy (finca), všechny její byty, obchodní prostory, garáže a sklepy (s účelem užívání, plochou, podílem, schodištěm, podlažím a dveřmi) a detail libovolného bytu. Každá odpověď v tomto návodu je skutečná, převzatá z produkce.

1. Od adresy k budově

GET /v1/search/address/candidates přijímá adresu jako volný text (ulice a číslo, obec a případně PSČ) a vrací odpovídající vchody budov seřazené podle spolehlivosti, každý se 14znakovou katastrální referencí. Nezávisí na Catastru: geokóduje pomocí CartoCiudad (IGN) a doplňuje údaje z naší kopie Catastra. Přijímá také jednotlivá pole: street, number, municipality a 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"

Skutečná odpověď

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
}
  • Při spolehlivosti 0,75 a vyšší se shoduje číslo i obec: importujte bez ptaní. Pod touto hodnotou ukažte kandidáty uživateli.
  • V Baskicku a Navarře má kandidát country PV nebo NA a forální referenci: krok 2 ji přijme s country=PV nebo NA a vypíše jednotky z naší kopie příslušného forálního katastru, bez podílu (forální otevřená data ho nezveřejňují).

2. Všechny jednotky budovy

GET /v1/parcels/:reference14/units vrací jednotky po stránkách nejvýše 200, seřazené podle reference. Dokud je truncated true, volejte znovu s cursor rovným nextCursor. propertyUnitCount vám už na první stránce řekne, kolik jich je celkem.

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"

Skutečná odpověď

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
}
  • Budova s 365 jednotkami jsou dvě volání: 200 a 165. Kurzor je stabilní, takže přerušený import lze obnovit.
  • Pro každou jednotku: reference (20 znaků), use, area (m²), ownershipShare (podíl v %, číslo v plné přesnosti), staircase, floor, door, rok a adresa.
  • dataSource clone znamená, že údaje pocházejí z naší kopie Catastra, ať Catastro funguje, nebo ne; dataDate je publikace Catastra, ze které řádky pocházejí. Budova, která v kopii chybí, se načte živě z Catastra (dataSource catastro).

3. Detail jednoho bytu

GET /v1/parcels/:reference20 vrací jeden byt se stejnými poli jako seznam a navíc souřadnice, obrys a plochu parcely.

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

Skutečná odpověď

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 a door se jmenují stejně jako v seznamu. builtArea je zde area ze seznamu.

Opakovaný import bez spotřeby kvóty

Každá stránka jednotek a každé vyhledání adresy nese ETag. Uložte si ETag každé stránky a příště ho pošlete v If-None-Match: pokud se nic nezměnilo, odpověď je 304 bez těla a nespotřebuje kvótu.

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

Celý postup se stránkováním, opakováním a ETagem

Opakuje odpovědi 429 a 503 s hlavičkou Retry-After, ostatní chyby vyhodí s jejich kódem a znovu použije stránky, které se nezměnily.

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

Kolik to stojí

VoláníJednotky kvóty
GET /v1/search/address/candidates1 za vyhledávání s výsledky.
GET /v1/parcels/:reference14/units1 za každou jednotku na stránce (minimálně 1). Stránka s 200 jednotkami je 200.
GET /v1/parcels/:reference1 za byt.
304 / 4xx / 5xxZdarma: odpověď 304 ani chyba kvótu nespotřebují.

Příklad: společenství s 365 jednotkami stojí 1 (adresa) + 200 + 165 (dvě stránky) = 366 jednotek. Opakovaný import beze změn stojí 0.

Chyby

HTTPKódCo znamená a co dělat
304-Od vašeho ETagu se nic nezměnilo. Použijte, co už máte. Zdarma.
400VALIDATION_ERRORChybné parametry (prázdná adresa, PSČ bez 5 číslic, kurzor z jiné budovy). Opravte požadavek.
401KEY_AUTH_001 / 002 / 003API klíč chybí nebo je neplatný.
404NOT_FOUNDAdresa nebo reference neexistuje. Nikdy se nepoužívá pro výpadky Catastra.
429KEY_RATE_002Váš klíč překročil počet požadavků za minutu. Počkejte počet sekund z Retry-After.
429KEY_AUTH_004Kvóta i zůstatek jsou vyčerpané (viz X-Quota-Remaining a X-Quota-Reset): dobijte si je v portálu nebo počkejte na obnovení 1. dne v měsíci.
503SERVICE_UNAVAILABLEOficiální zdroj (Catastro nebo CartoCiudad) nefunguje nebo je přetížený a naše kopie údaje nemá. Zkuste to znovu po uplynutí Retry-After. Zdarma.
{
  "success": false,
  "code": "NOT_FOUND",
  "message": "No building entrance (portal) with a cadastral reference matches that address. Include the street number and the municipality."
}

Kompletní reference

Všechny endpointy, pole a kódy najdete ve specifikaci OpenAPI 3.1, kterou můžete importovat do Postmanu, Insomnie nebo generátoru klientů: https://api.parcelgps.com/v1/openapi.json