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 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
}
  • 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: 2929

Cał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łanieJednostki limitu
GET /v1/search/address/candidates1 za wyszukiwanie z wynikami.
GET /v1/parcels/:reference14/units1 za każdy lokal na stronie (minimum 1). Strona z 200 lokalami to 200.
GET /v1/parcels/:reference1 za lokal.
304 / 4xx / 5xxZa 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

HTTPKodCo oznacza i co zrobić
304-Nic się nie zmieniło od Twojego ETag. Użyj tego, co masz. Za darmo.
400VALIDATION_ERRORBłędne parametry (pusty adres, kod pocztowy bez 5 cyfr, kursor z innego budynku). Popraw żądanie.
401KEY_AUTH_001 / 002 / 003Brak klucza API lub klucz jest nieprawidłowy.
404NOT_FOUNDAdres lub referencja nie istnieje. Nigdy nie oznacza awarii Catastro.
429KEY_RATE_002Twój klucz przekroczył limit żądań na minutę. Odczekaj liczbę sekund z Retry-After.
429KEY_AUTH_004Limit i saldo wyczerpane (zob. X-Quota-Remaining i X-Quota-Reset): doładuj w portalu lub poczekaj na odnowienie 1. dnia miesiąca.
503SERVICE_UNAVAILABLEOficjalne ź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