Import wspólnoty mieszkaniowej
Aby zarejestrować wspólnotę mieszkaniową, wystarczy jej adres. W trzech wywołaniach otrzymujesz referencję budynku (finca), wszystkie jego mieszkania, lokale użytkowe, garaże i komórki (z przeznaczeniem, powierzchnią, udziałem, klatką, piętrem i drzwiami) oraz szczegóły dowolnego lokalu. Każda odpowiedź w tym przewodniku jest prawdziwa, pobrana z produkcji.
1. Od adresu do budynku
GET /v1/search/address/candidates przyjmuje adres jako wolny tekst (ulica i numer, gmina oraz, jeśli go masz, kod pocztowy) i zwraca pasujące wejścia do budynków uszeregowane według pewności, każde z 14-znakową referencją katastralną. Nie zależy od Catastro: geokoduje przez CartoCiudad (IGN) i uzupełnia dane z naszej kopii Catastro. Przyjmuje też pola osobno: 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"Prawdziwa odpowiedź
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
}- Przy pewności 0,75 lub wyższej numer i gmina się zgadzają: importuj bez pytania. Poniżej tej wartości pokaż kandydatów użytkownikowi.
- W Kraju Basków i Nawarze kandydat ma country PV lub NA i referencję foralną: krok 2 przyjmuje ją z country=PV lub NA i zwraca lokale z naszej kopii tamtejszego katastru foralnego, bez udziału (otwarte dane foralne go nie publikują).
2. Wszystkie lokale budynku
GET /v1/parcels/:reference14/units zwraca lokale na stronach po maksymalnie 200, posortowane według referencji. Dopóki truncated ma wartość true, powtarzaj wywołanie z cursor równym nextCursor. propertyUnitCount już na pierwszej stronie mówi, ile jest ich łącznie.
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"Prawdziwa odpowiedź
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
}- Budynek z 365 lokalami to dwa wywołania: 200 i 165. Kursor jest stabilny, więc przerwany import można wznowić.
- Dla każdego lokalu: reference (20 znaków), use, area (m²), ownershipShare (udział w %, liczba z pełną precyzją), staircase, floor, door, rok i adres.
- dataSource clone oznacza, że dane pochodzą z naszej kopii Catastro, niezależnie od tego, czy Catastro działa; dataDate to publikacja Catastro, z której pochodzą wiersze. Budynek, którego nie ma w kopii, jest odczytywany na żywo z Catastro (dataSource catastro).
3. Szczegóły jednego lokalu
GET /v1/parcels/:reference20 zwraca jeden lokal z tymi samymi polami co lista, a dodatkowo współrzędne, obrys i powierzchnię działki.
curl "https://api.parcelgps.com/v1/parcels/0745901TG4304N0002KH" \
-H "X-API-Key: $CATASTROGPS_API_KEY"Prawdziwa odpowiedź
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 nazywają się tak samo jak na liście. builtArea to tutaj area z listy.
Ponowny import bez zużywania limitu
Każda strona lokali i każde wyszukiwanie adresu ma ETag. Zapisz ETag każdej strony i wyślij go następnym razem w If-None-Match: jeśli nic się nie zmieniło, odpowiedź to 304 bez treści i nie zużywa limitu.
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: 2929Cały proces, z paginacją, ponowieniami i ETag
Ponawia odpowiedzi 429 i 503 z nagłówkiem Retry-After, pozostałe błędy zgłasza z ich kodem i ponownie używa stron, które się nie zmieniły.
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);Ile to kosztuje
| Wywołanie | Jednostki limitu |
|---|---|
| GET /v1/search/address/candidates | 1 za wyszukiwanie z wynikami. |
| GET /v1/parcels/:reference14/units | 1 za każdy lokal na stronie (minimum 1). Strona z 200 lokalami to 200. |
| GET /v1/parcels/:reference | 1 za lokal. |
| 304 / 4xx / 5xx | Za darmo: ani 304, ani błąd nie zużywają limitu. |
Przykład: wspólnota z 365 lokalami kosztuje 1 (adres) + 200 + 165 (dwie strony) = 366 jednostek. Ponowny import bez zmian kosztuje 0.
Błędy
| HTTP | Kod | Co oznacza i co zrobić |
|---|---|---|
| 304 | - | Nic się nie zmieniło od Twojego ETag. Użyj tego, co masz. Za darmo. |
| 400 | VALIDATION_ERROR | Błędne parametry (pusty adres, kod pocztowy bez 5 cyfr, kursor z innego budynku). Popraw żądanie. |
| 401 | KEY_AUTH_001 / 002 / 003 | Brak klucza API lub klucz jest nieprawidłowy. |
| 404 | NOT_FOUND | Adres lub referencja nie istnieje. Nigdy nie oznacza awarii Catastro. |
| 429 | KEY_RATE_002 | Twój klucz przekroczył limit żądań na minutę. Odczekaj liczbę sekund z Retry-After. |
| 429 | KEY_AUTH_004 | Limit i saldo wyczerpane (zob. X-Quota-Remaining i X-Quota-Reset): doładuj w portalu lub poczekaj na odnowienie 1. dnia miesiąca. |
| 503 | SERVICE_UNAVAILABLE | Oficjalne źródło (Catastro lub CartoCiudad) nie działa lub jest przeciążone, a nasza kopia nie ma tych danych. Ponów po czasie z Retry-After. Za darmo. |
{
"success": false,
"code": "NOT_FOUND",
"message": "No building entrance (portal) with a cadastral reference matches that address. Include the street number and the municipality."
}Pełna dokumentacja
Wszystkie endpointy, pola i kody są w specyfikacji OpenAPI 3.1, którą zaimportujesz do Postmana, Insomnii lub generatora klientów: https://api.parcelgps.com/v1/openapi.json