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 OKHTTP/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: 2929Celý 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/candidates | 1 za vyhledávání s výsledky. |
| GET /v1/parcels/:reference14/units | 1 za každou jednotku na stránce (minimálně 1). Stránka s 200 jednotkami je 200. |
| GET /v1/parcels/:reference | 1 za byt. |
| 304 / 4xx / 5xx | Zdarma: 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
| HTTP | Kód | Co znamená a co dělat |
|---|---|---|
| 304 | - | Od vašeho ETagu se nic nezměnilo. Použijte, co už máte. Zdarma. |
| 400 | VALIDATION_ERROR | Chybné parametry (prázdná adresa, PSČ bez 5 číslic, kurzor z jiné budovy). Opravte požadavek. |
| 401 | KEY_AUTH_001 / 002 / 003 | API klíč chybí nebo je neplatný. |
| 404 | NOT_FOUND | Adresa nebo reference neexistuje. Nikdy se nepoužívá pro výpadky Catastra. |
| 429 | KEY_RATE_002 | Váš klíč překročil počet požadavků za minutu. Počkejte počet sekund z Retry-After. |
| 429 | KEY_AUTH_004 | Kvó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. |
| 503 | SERVICE_UNAVAILABLE | Oficiá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