Dokumentacja API

Pełna dokumentacja API katastralnego

Bazowy URL

https://api.parcelgps.com

OpenAPI 3.1 specification

Every endpoint on this page in machine-readable form, for Postman, Insomnia or client generators:

https://api.parcelgps.com/api/openapi.json

Units pages and address searches carry an ETag: with If-None-Match the answer is 304 with no body and costs no quota.

apartmentGuide: import a homeowners' association in 3 calls

Kody krajów

Endpointy przyjmują ?country=XX. Parametr jest opcjonalny: bez niego API rozpoznaje kraj po formacie referencji spośród 21 krajów. Niejednoznaczna referencja zwraca 300 CNV_AMBIGUOUS z kandydatami; kraj, którego jeszcze nie obsługujemy — 422 CNV_COVERAGE; coś, co wygląda na nazwę miejscowości — 422 CNV_PLACE_NAME z geokodowanym punktem. Hiszpania kontynentalna używa ES, ale Kraj Basków i Nawarra mają własne (foralne) katastry i wymagają własnego kodu: z ES ich działki nie zostaną znalezione.

ES · HiszpaniaPV · Kraj BaskówNA · NawarraPT · PortugaliaFR · FrancjaIT · WłochyDE · NiemcyAT · AustriaPL · PolskaNL · HolandiaCZ · CzechyFI · FinlandiaBE · BelgiaEE · EstoniaSI · SłoweniaLT · LitwaLU · LuksemburgSK · SłowacjaBG · BułgariaCY · CyprIS · IslandiaLI · LiechtensteinCH · Szwajcaria

Opis endpointów

MetodaEndpointAutoryzacjaOpis
GET/api/resolve?q=TEXTAPI KeyKlasyfikuje dowolne dane wejściowe: referencję (i kraj), współrzędne lub nazwę miejscowości. Nie jest wliczane do limitu.
GET/api/search/address/candidates?q=TEXT&country=XXAPI KeyAdres → działka z kandydatami według pewności: Hiszpania i 25 innych krajów europejskich
GET/api/catastro/:refcatAPI KeyWyszukiwanie działki
GET/api/catastro/:refcat14/unitsAPI KeyWszystkie lokale nieruchomości (mieszkania, lokale, garaże) — Hiszpania
GET/api/catastro/:refcat/polygon?country=XXAPI KeyGeometria działki (GeoJSON)
GET/api/catastro/:refcat/terrain?country=XXAPI KeyRzeźba terenu (wysokość, nachylenie, ekspozycja) oraz Natura 2000 / obszary chronione działki
GET/api/catastro/:refcat/ground-motion?country=XXAPI KeyRuch gruntu (osiadanie lub wypiętrzanie w mm/rok, 2020-2024) z pomiarów satelitarnych
GET/api/catastro/:refcat/solar?country=XXAPI KeyPotencjał fotowoltaiczny
GET/api/catastro/:refcat/agro?country=XXAPI KeyDane gruntów rolnych
GET/api/export/kml?refcat=X&country=XAPI KeyEksport KML/GPX/PDF/DXF
GET/api/catastro/:refcat/market?country=XXWeb i aplikacjaDane rynkowe (niedostępne przez API)
GET/api/catastro/:refcat/score?country=XXWeb i aplikacjaOcena inwestycyjna (niedostępna przez API)

Niezawodność

Co serwujemy z własnej infrastruktury, a co zależy od instytucji publicznej. Warto to przeczytać przed wdrożeniem produkcyjnym.

EndpointSkąd pochodzą dane
/catastro/:refcat (ES)Nasza własna kopia katastru (50,9 mln działek). Odpowiedź nie zależy od Catastro.
/polygon · /search/address · /search/coordinatesCatastro (instytucja publiczna). Może przestać działać bez uprzedzenia.
/agroSIGPAC
/solarPVGIS

Błędy i ponawianie

Kod 503 oznacza, że oficjalne źródło w tej chwili nie odpowiada: ponawiaj z opóźnieniem (backoff), a problem sam ustąpi. Kod 429 to Twój limit i ponawianie go nie przywróci — poczekaj na reset albo przejdź na wyższy plan. Kod 404 to referencja, która nie istnieje, i nie należy jej ponawiać.

Strona statusu

Publikujemy stan naszego API oraz dziewięciu źródeł katastralnych, od których zależymy. Sprawdzamy go co pięć minut, a strona jest hostowana poza tym API, więc pozostaje wiarygodna podczas awarii: catastrogps.es/status.

Uwierzytelnianie

Każde żądanie do API wymaga klucza API przesłanego w nagłówku X-API-Key.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S"

Bezpłatny klucz API pobierzesz w panelu dewelopera.

Kody błędów

StatusKodOpis
200—OK — Żądanie zakończyło się powodzeniem.
400VALIDATION_ERRORBad Request — Nieprawidłowe parametry lub referencja katastralna w złym formacie.
401UNAUTHORIZEDUnauthorized — Nieprawidłowy, wygasły lub brakujący klucz API.
404NOT_FOUNDNot Found — Nie znaleziono działki dla podanej referencji lub współrzędnych. Nie zużywa limitu.
429KEY_AUTH_004Quota Exceeded — Wyczerpano miesięczny limit Twojego planu. Nagłówki X-Quota-Remaining i X-Quota-Reset pokazują, ile zostało i kiedy limit się odnowi.
429RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHEDToo Many Requests — KEY_RATE_002: przekroczono minutowy limit chwilowy Twojego klucza (Free 10, Developer 60, Startup 120, Growth 300). RATE_LIMIT_EXCEEDED: zbyt wiele żądań z tego samego IP. Oba zwracają X-RateLimit-* i Retry-After. DAILY_LIMIT_REACHED: dzienny limit darmowych wyszukiwań bez klucza API.
500INTERNAL_ERRORInternal Server Error — Błąd po naszej stronie. Jeśli się powtarza, skontaktuj się z pomocą techniczną.
503SERVICE_UNAVAILABLEService Unavailable — Zewnętrzna usługa katastralna danego kraju jest chwilowo niedostępna. Usługi te prowadzą instytucje publiczne (Catastro, DGT, Géoportail, Agenzia Entrate, ALKIS...) i nie mamy na nie wpływu. Spróbuj ponownie za kilka minut.

Nagłówki limitu miesięcznego i rate limit

Są dwie rodziny nagłówków i mierzą różne rzeczy. X-Quota-* to miesięczny limit Twojego planu: ten, który kończy się błędem KEY_AUTH_004.

NagłówekOpis
X-Quota-LimitWywołania w miesiącu zawarte w planie (np. 5000).
X-Quota-RemainingPozostałe wywołania w tym miesiącu.
X-Quota-ResetData odnowienia limitu miesięcznego (ISO 8601, UTC).
X-Quota-TierNazwa bieżącego planu (free, basic, pro, business).

X-RateLimit-* to minutowy limit chwilowy Twojego klucza, zależny od planu: Free 10, Developer 60, Startup 120 i Growth 300 żądań co 60 sekund. Nie ma nic wspólnego z miesięcznym limitem.

NagłówekOpis
X-RateLimit-LimitDozwolone żądania na minutę z Twoim kluczem (zależnie od planu).
X-RateLimit-RemainingPozostałe żądania w bieżącej minucie.
X-RateLimit-ResetSekundy do odnowienia jednominutowego okna.

Przewodniki według zastosowania

Cztery rzeczywiste zadania wykonane za pomocą wywołań API. Każdy krok zawiera wywołanie w cURL, z SDK dla JavaScript i z SDK dla Pythona oraz rzeczywistą odpowiedź zwróconą przez środowisko produkcyjne.

Sprawdzenie nieruchomości przed zakupem

Od adresu z ogłoszenia do tego, co podaje kataster i co widać z satelity: jaka to finca, co się w niej znajduje, czy leży na obszarze chronionym i czy grunt się przemieszcza. Każdy krok korzysta z innej działki, aby pokazać przypadek z danymi; w Twoim procesie od początku do końca jest to ta sama referencja.

Kraje: ES

1. Od adresu do finca

Adres w postaci dowolnego tekstu zwraca kandydatów uszeregowanych według pewności (od 0 do 1) z 14-znakową referencją, przeznaczeniem, liczbą mieszkań i rokiem budowy. Od 0,75 wzwyż zgadzają się numer i gmina. Kosztuje 1 jednostkę tylko wtedy, gdy są kandydaci.

curl -G "https://api.parcelgps.com/api/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"

Rzeczywista odpowiedź

{
  "success": true,
  "data": {
    "consulta": {
      "texto": "Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas",
      "calle": "Avenida José Rodríguez de la Borbolla Camoyán",
      "numero": 10,
      "municipio": "Dos Hermanas"
    },
    "candidatos": [
      {
        "refCatastral": "0745901TG4304N",
        "pais": "ES",
        "direccion": "AVENIDA JOSE RGUEZ BORBOLLA CAMOY 10",
        "numero": 10,
        "codigoPostal": "41704",
        "municipio": "Dos Hermanas",
        "provincia": "Sevilla",
        "latitud": 37.31947088654626,
        "longitud": -5.926788955974699,
        "confianza": 0.93,
        "coincideNumero": true,
        "coincideMunicipio": true,
        "enCopia": true,
        "direccionCatastro": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
        "uso": "Residencial",
        "viviendas": 346,
        "anioConstruccion": 2023
      },
      {
        "refCatastral": "0747201TG4304N",
        "pais": "ES",
        "direccion": "BULEVAR JOSE RODRIGUEZ DE LA BORBOLLA CAMOYAN 11",
        "numero": 11,
        "confianza": 0.55,
        "coincideNumero": false,
        "coincideMunicipio": true,
        "enCopia": true
      }
    ],
    "attribution": "CartoCiudad (Instituto Geográfico Nacional) y Dirección General del Catastro"
  }
}

2. Co jest w środku: mieszkania, lokale użytkowe i pomieszczenia przynależne

Na podstawie 14-znakowej referencji otrzymujesz wszystkie jednostki finca z przeznaczeniem, powierzchnią, piętrem, oznaczeniem drzwi i współczynnikiem udziału. Pozwala to sprawdzić, czy powierzchnia i przeznaczenie podane w ogłoszeniu zgadzają się z katastrem. Kosztuje 1 jednostkę za każdą zwróconą jednostkę.

curl "https://api.parcelgps.com/api/catastro/0745901TG4304N/units" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Rzeczywista odpowiedź

HTTP/2 200
etag: "5ab6bd3d95f85dddba81818bcb0cb65e"
cache-control: private, max-age=21600
x-quota-remaining: 2893

{
  "success": true,
  "data": {
    "refCatastral": "0745901TG4304N",
    "direccion": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
    "codigoPostal": "41704",
    "municipio": "DOS HERMANAS",
    "provincia": "Sevilla",
    "usoGeneral": "Residencial",
    "superficieTotal": 32789,
    "anioConstruccion": 2023,
    "totalUnidades": 200,
    "totalUnidadesFinca": 365,
    "unidades": [
      {
        "refCatastral": "0745901TG4304N0002KH",
        "escalera": "",
        "planta": "01",
        "puerta": "B",
        "uso": "Residencial",
        "superficie": 155,
        "descripcion": "Planta 01, Pta. B - Residencial",
        "participacion": 0.279543,
        "anio": 2023,
        "direccion": "AV JOSE RGUEZ BORBOLLA CAMOY 10 Pl:01 Pt:B"
      },
      {
        "refCatastral": "0745901TG4304N0003LJ",
        "escalera": "",
        "planta": "01",
        "puerta": "C",
        "uso": "Residencial",
        "superficie": 163,
        "descripcion": "Planta 01, Pta. C - Residencial",
        "participacion": 0.293879,
        "anio": 2023,
        "direccion": "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"
  },
  "searchesRemaining": -1
}

3. Obszary chronione: Natura 2000 i parki

Przed zakupem gruntu rolnego warto wiedzieć, czy leży on na obszarze chronionym: ogranicza to, co można na nim zbudować lub posadzić. /terrain nakłada obrys działki na obszary Natura 2000 i krajowe obszary chronione (CDDA) i podaje, jaka część działki znajduje się w ich granicach. Rzeczywisty przykład: działka położona w całości w Parku Narodowym Monfragüe.

curl "https://api.parcelgps.com/api/catastro/10194A00110004/terrain?country=ES" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Rzeczywista odpowiedź, skrócona

{
  "success": true,
  "data": {
    "refcat": "10194A00110004",
    "country": "ES",
    "protected_areas": {
      "status": "ok",
      "intersects": true,
      "inside": true,
      "max_overlap_pct": 100,
      "natura2000": [
        {
          "code": "ES0000014",
          "name": "Monfragüe y las Dehesas del Entorno",
          "type": "SPA",
          "country": "ES",
          "overlap_pct": 100
        },
        {
          "code": "ES4320077",
          "name": "Monfragüe",
          "type": "SCI",
          "country": "ES",
          "overlap_pct": 100
        }
      ],
      "national": [
        {
          "code": "4820",
          "name": "Monfragüe",
          "designation": "National Park",
          "country": "ES",
          "overlap_pct": 100
        }
      ],
      "method": "parcel",
      "sources": [
        {
          "name": "Natura 2000",
          "license": "CC BY 4.0",
          "edition": "end 2024"
        },
        {
          "name": "Nationally designated areas (CDDA)",
          "license": "CC BY 4.0",
          "edition": "2025"
        }
      ]
    }
  }
}

4. Czy grunt osiada

/ground-motion podaje prędkość pionowego ruchu gruntu na działce, mierzoną przez radar Sentinel-1 (Copernicus EGMS, 2020-2024). Rzeczywisty przykład: działka w Murcji, która osiada o 40,9 mm rocznie, klasa severe_subsidence. Gdy satelita nie ma na działce punktów odbijających sygnał (otwarte pola, las, woda), zwraca status no_data zamiast zgadywać.

curl "https://api.parcelgps.com/api/catastro/30024A16000286/ground-motion?country=ES" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Rzeczywista odpowiedź

{
  "success": true,
  "data": {
    "refcat": "30024A16000286",
    "country": "ES",
    "status": "ok",
    "period": { "from": "2020-01", "to": "2024-12", "label": "2020-2024" },
    "ground_motion": {
      "class": "severe_subsidence",
      "worst_class": "severe_subsidence",
      "vertical": {
        "mean_mm_year": -40.9, "max_subsidence_mm_year": -40.9, "max_uplift_mm_year": 0,
        "std_mm_year": 0.1, "acceleration_mm_year2": -0.7, "rmse_mm": 2.3
      },
      "east_west": { "mean_mm_year": -5.1, "std_mm_year": 0.1 },
      "yearly_displacement": [
        { "year": 2020, "mm": -17.9 }, { "year": 2021, "mm": -57.2 }, { "year": 2022, "mm": -95.8 },
        { "year": 2023, "mm": -141.8 }, { "year": 2024, "mm": -179.8 }
      ],
      "cells_with_data": 1, "cells_considered": 1, "coverage_pct": 100,
      "basis": "parcel", "cell_size_m": 100
    },
    "source": {
      "name": "European Ground Motion Service (EGMS) L3 Ortho",
      "license": "Copernicus data policy (Regulation (EU) No 1159/2013): free, commercial use allowed with attribution",
      "attribution": "Contains modified Copernicus Land Monitoring Service information, European Ground Motion Service 2020-2024 (© European Union, Copernicus Land Monitoring Service, EEA)",
      "resolution": "100 m"
    },
    "calculated_at": "2026-10-01T06:14:34Z",
    "provenance": "1"
  }
}

Portfel zarządcy nieruchomości

Zaimportuj każdą finca, którą zarządzasz, wraz z jej jednostkami i sprawdzaj je ponownie co miesiąc, nie płacąc dwa razy za to, co się nie zmieniło.

Kraje: ES

1. Pierwszy import

Przejdź w pętli przez listę 14-znakowych referencji. Każda strona zawiera do 200 jednostek i nextCursor; SDK same obsługują kursor. Zapisz ETag każdej strony razem z finca. Pozostałą część limitu znajdziesz w nagłówku X-Quota-Remaining i w polu lastQuota w SDK.

curl -i "https://api.parcelgps.com/api/catastro/0745901TG4304N/units" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

curl -i "https://api.parcelgps.com/api/catastro/0745901TG4304N/units?cursor=0745901TG4304N0201MZ" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Rzeczywista odpowiedź

HTTP/2 200
etag: "5ab6bd3d95f85dddba81818bcb0cb65e"
cache-control: private, max-age=21600
x-quota-remaining: 2893

{
  "success": true,
  "data": {
    "refCatastral": "0745901TG4304N",
    "direccion": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
    "codigoPostal": "41704",
    "municipio": "DOS HERMANAS",
    "provincia": "Sevilla",
    "usoGeneral": "Residencial",
    "superficieTotal": 32789,
    "anioConstruccion": 2023,
    "totalUnidades": 200,
    "totalUnidadesFinca": 365,
    "unidades": [
      {
        "refCatastral": "0745901TG4304N0002KH",
        "escalera": "",
        "planta": "01",
        "puerta": "B",
        "uso": "Residencial",
        "superficie": 155,
        "descripcion": "Planta 01, Pta. B - Residencial",
        "participacion": 0.279543,
        "anio": 2023,
        "direccion": "AV JOSE RGUEZ BORBOLLA CAMOY 10 Pl:01 Pt:B"
      },
      {
        "refCatastral": "0745901TG4304N0003LJ",
        "escalera": "",
        "planta": "01",
        "puerta": "C",
        "uso": "Residencial",
        "superficie": 163,
        "descripcion": "Planta 01, Pta. C - Residencial",
        "participacion": 0.293879,
        "anio": 2023,
        "direccion": "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"
  },
  "searchesRemaining": -1
}

2. Comiesięczna kontrola z ETag

Powtórz wywołanie z If-None-Match i zapisanym ETag. Jeśli finca się nie zmieniła, odpowiedź to 304 Not Modified i nic nie kosztuje. W SDK wystarczy przekazać poprzedni wynik: changed informuje, czy coś się zmieniło. Przestrzegaj limitu na minutę w swoim planie (Free 10, Developer 60, Startup 120, Growth 300): SDK same ponawiają żądanie po odpowiedzi 429.

curl -i "https://api.parcelgps.com/api/catastro/0745901TG4304N/units" \
  -H "X-API-Key: $CATASTROGPS_API_KEY" \
  -H 'If-None-Match: "5ab6bd3d95f85dddba81818bcb0cb65e"'

HTTP/2 304
x-quota-remaining: 2929
Pełny przewodnik po imporcie wspólnoty mieszkaniowej

Potencjał solarny działki

Szacowana produkcja z PVGIS, oszczędności, okres zwrotu, a w przypadku paneli na gruncie rzeczywiste nachylenie i orientacja terenu. /solar obejmuje Hiszpanię (z Krajem Basków i Nawarrą), Portugalię, Francję, Włochy i Niemcy; poza nimi odpowiada 422 CNV_COVERAGE.

Kraje: ESPVNAPTFRITDE

1. Produkcja i ekonomika instalacji

Odpowiedź zawiera moc możliwą do zainstalowania w kWp, kWh rocznie, oszczędności, okres zwrotu, uniknięte CO2 oraz blok economics z autokonsumpcją, nadwyżkami, dochodem netto, okresem zwrotu i IRR. Gdy brak danych solarnych, odpowiada disponible false i nic nie kosztuje.

curl "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Rzeczywista odpowiedź

{
  "success": true,
  "data": {
    "kwh_year": 23749.9,
    "kw_instalables": 17.86,
    "ahorro_anual_eur": 3562.49,
    "amortizacion_anos": 5,
    "co2_evitado_kg": 5533.73,
    "irradiacion_media": 1807.08,
    "nota_solar": 5,
    "orientacion_optima": "Sur",
    "angulo_inclinacion": 34,
    "costo_instalacion_eur": 17865,
    "disponible": true,
    "estado": "ok",
    "fuente": "PVGIS (JRC)",
    "economics": {
      "autoconsumo_kwh_ano": 5000,
      "excedentes_kwh_ano": 18749.9,
      "ingreso_neto_anual_eur": 1473.18,
      "payback_anos": 12.13,
      "tir_pct": 6.56,
      "retorno_total_25_anos_eur": 18964.5
    }
  }
}

2. Nachylenie i orientacja terenu

W przypadku instalacji na gruncie /terrain podaje średnie i maksymalne nachylenie wraz z jego klasą oraz dominującą orientację w obrębie rzeczywistego obrysu (Copernicus DEM GLO-30, 30 m). Rzeczywisty przykład: bardzo stromy stok o ekspozycji północnej, słaby kandydat na panele naziemne.

curl "https://api.parcelgps.com/api/catastro/10194A00110004/terrain?country=ES" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Rzeczywista odpowiedź, skrócona

{
  "success": true,
  "data": {
    "refcat": "10194A00110004",
    "country": "ES",
    "relief": {
      "status": "ok",
      "elevation_m": {
        "mean": 365.8,
        "min": 212.3,
        "max": 506.6
      },
      "slope": {
        "mean_pct": 36.5,
        "mean_deg": 20,
        "max_pct": 71.6,
        "class": "very_steep",
        "max_class": "very_steep",
        "share_over_10_pct": 98.4,
        "classes_pct": {
          "flat": 0.2,
          "gentle": 1.4,
          "moderate": 6.8,
          "steep": 20,
          "very_steep": 71.7
        }
      },
      "aspect": {
        "dominant": "N",
        "dominant_share_pct": 75.3,
        "mean_deg": 0,
        "flat_share_pct": 0.2,
        "sectors_pct": {
          "N": 75.3,
          "NE": 10.6,
          "E": 0.6,
          "SE": 0.1,
          "S": 0,
          "SW": 1,
          "W": 1.4,
          "NW": 10.8
        }
      },
      "sample": {
        "method": "parcel",
        "cells": 1448,
        "resolution_m": 31
      },
      "source": {
        "name": "Copernicus DEM GLO-30",
        "license": "Copernicus DEM licence (free, commercial use allowed)",
        "attribution": "© DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved"
      }
    }
  }
}

Ryzyko działki dla ubezpieczyciela

Trzy sygnały dla każdej działki z otwartych źródeł europejskich: osiadanie gruntu (EGMS), rzeźba terenu i obszary chronione (Copernicus DEM, EEA) oraz klimat (ERA5-Land). Działa w całym zasięgu EGMS (EEA-39) wszędzie tam, gdzie mamy obrys; poza Hiszpanią, Portugalią, Francją, Włochami i Niemcami przekaż również lat i lng.

Kraje: EEA-39

1. Osiadanie i przyspieszenie

class i worst_class podsumowują ruch (stable, slow_subsidence, notable_subsidence, severe_subsidence i ich odpowiedniki dla wypiętrzania). vertical zawiera średnią, najszybsze osiadanie, przyspieszenie oraz skumulowane przemieszczenie w każdym roku. Każda odpowiedź zawiera atrybucję Copernicus, którą trzeba wyświetlić.

curl "https://api.parcelgps.com/api/catastro/30024A16000286/ground-motion?country=ES" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Rzeczywista odpowiedź

{
  "success": true,
  "data": {
    "refcat": "30024A16000286",
    "country": "ES",
    "status": "ok",
    "period": { "from": "2020-01", "to": "2024-12", "label": "2020-2024" },
    "ground_motion": {
      "class": "severe_subsidence",
      "worst_class": "severe_subsidence",
      "vertical": {
        "mean_mm_year": -40.9, "max_subsidence_mm_year": -40.9, "max_uplift_mm_year": 0,
        "std_mm_year": 0.1, "acceleration_mm_year2": -0.7, "rmse_mm": 2.3
      },
      "east_west": { "mean_mm_year": -5.1, "std_mm_year": 0.1 },
      "yearly_displacement": [
        { "year": 2020, "mm": -17.9 }, { "year": 2021, "mm": -57.2 }, { "year": 2022, "mm": -95.8 },
        { "year": 2023, "mm": -141.8 }, { "year": 2024, "mm": -179.8 }
      ],
      "cells_with_data": 1, "cells_considered": 1, "coverage_pct": 100,
      "basis": "parcel", "cell_size_m": 100
    },
    "source": {
      "name": "European Ground Motion Service (EGMS) L3 Ortho",
      "license": "Copernicus data policy (Regulation (EU) No 1159/2013): free, commercial use allowed with attribution",
      "attribution": "Contains modified Copernicus Land Monitoring Service information, European Ground Motion Service 2020-2024 (© European Union, Copernicus Land Monitoring Service, EEA)",
      "resolution": "100 m"
    },
    "calculated_at": "2026-10-01T06:14:34Z",
    "provenance": "1"
  }
}

2. Rzeźba terenu, obszary chronione i klimat

To samo wywołanie /terrain zwraca rzeźbę terenu, obszary chronione i blok climate z normami klimatycznymi ERA5-Land: średnią temperaturę, roczną sumę opadów, liczbę dni z przymrozkiem i dni powyżej 35 stopni w okresie referencyjnym w porównaniu z ostatnimi latami. Siatka ERA5-Land jest w trakcie ładowania: do czasu jego zakończenia climate odpowiada status unavailable, a pozostała część odpowiedzi przychodzi jak zwykle. Przykład korzysta z belgijskiej referencji, która zawiera ukośnik i jest kodowana jako %2F.

curl "https://api.parcelgps.com/api/catastro/21802B1307%2F00B000/terrain?country=BE&lat=50.848139&lng=4.353613" \
  -H "X-API-Key: $CATASTROGPS_API_KEY"

Blok climate w trakcie ładowania siatki ERA5-Land

"climate": {
  "status": "unavailable",
  "source": {
    "name": "ERA5-Land",
    "provider": "Copernicus Climate Change Service (C3S) / ECMWF",
    "license": "CC BY 4.0",
    "attribution": "Contains modified Copernicus Climate Change Service information; …",
    "url": "https://cds.climate.copernicus.eu/datasets/reanalysis-era5-land-monthly-means",
    "resolution": "0.1° (~9 km)"
  }
}

SDK i MCP

Oficjalne biblioteki klienckie dla JavaScript/TypeScript i Pythona oraz serwer MCP, dzięki któremu asystent AI może wyszukiwać działki z użyciem Twojego klucza. Wszystkie trzy odczytują klucz ze zmiennej środowiskowej CATASTROGPS_API_KEY.

JavaScript i TypeScript (npm)

npm install catastrogps
import { CatastroGPS } from 'catastrogps'

const client = new CatastroGPS({ apiKey: process.env.CATASTROGPS_API_KEY })

const parcel = await client.parcels.get('9872023VH5797S0001WX')
const inWarsaw = await client.parcels.atPoint({ lat: 52.2297, lng: 21.0122 })
const terrain = await client.request('GET', '/api/catastro/10194A00110004/terrain', { query: { country: 'ES' } })
console.log(parcel.municipio, inWarsaw.referenciaCatastral, terrain.relief.slope.class, client.lastQuota)

Python (PyPI)

pip install catastrogps
from catastrogps import CatastroGPS

client = CatastroGPS()

parcel = client.parcels.get("9872023VH5797S0001WX")
in_warsaw = client.parcels.at_point(52.2297, 21.0122)
terrain = client.request("GET", "/api/catastro/10194A00110004/terrain", query={"country": "ES"})
print(parcel["municipio"], in_warsaw["referenciaCatastral"], terrain["relief"]["slope"]["class"], client.last_quota)

W przypadku endpointu bez własnej metody w SDK, takiego jak /terrain lub /ground-motion, użyj client.request: podpisuje wywołanie, ponawia żądania po odpowiedziach 429 i 5xx oraz aktualizuje limit tak jak każda inna metoda.

Podłączenie serwera MCP do asystenta

Serwer catastro-gps-mcp (npm) udostępnia API jako narzędzia dla Claude, Cursor, VS Code i dowolnego klienta MCP. Każde wywołanie narzędzia to jedno wywołanie API wliczane do Twojego limitu.

Claude Desktop: dodaj to do claude_desktop_config.json i uruchom aplikację ponownie.

{
  "mcpServers": {
    "catastro-gps": {
      "command": "npx",
      "args": ["-y", "catastro-gps-mcp"],
      "env": { "CATASTROGPS_API_KEY": "pk_live_your_key_here" }
    }
  }
}

Claude Code: jedno polecenie w terminalu.

claude mcp add catastro-gps --env CATASTROGPS_API_KEY=pk_live_your_key_here -- npx -y catastro-gps-mcp

Cursor, Windsurf, VS Code i inni klienci MCP: to samo polecenie z CATASTROGPS_API_KEY w środowisku.

npx -y catastro-gps-mcp

Narzędzia

get_parcelsearch_addressget_boundariesget_solar_potentialget_terrainget_agricultureget_market_dataget_investment_scoreget_value_historycompare_parcels

Spróbuj zapytać

  • Find the cadastral parcel at Calle Mallorca 213, Barcelona, and give me its area and outline.
  • What is the parcel at 52.2297, 21.0122? What is its area?
  • Look up the Polish parcel 146510_8.0502.1/3 and tell me its area.

Hiszpania (ES)

Kataster Hiszpanii — Dirección General del Catastro

GET/api/search/address/candidates

Geocodes a Spanish address with CartoCiudad (IGN) and returns the matching building entrances ranked by confidence, with their 14-character reference and, when they are in our copy, use, dwellings and year. Does not depend on the Catastro. Costs 1 quota unit.

Parametry

qstringFree-text address: street and number, municipality (and postcode if you have it).
street / number / municipality / postcode / limitstringOptional: street, number, municipality, postcode (override what is read from q) and limit (1-10, default 5).
curl -G "https://api.parcelgps.com/api/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"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "consulta": {
      "texto": "Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas",
      "calle": "Avenida José Rodríguez de la Borbolla Camoyán",
      "numero": 10,
      "municipio": "Dos Hermanas"
    },
    "candidatos": [
      {
        "refCatastral": "0745901TG4304N",
        "pais": "ES",
        "direccion": "AVENIDA JOSE RGUEZ BORBOLLA CAMOY 10",
        "numero": 10,
        "codigoPostal": "41704",
        "municipio": "Dos Hermanas",
        "provincia": "Sevilla",
        "latitud": 37.31947088654626,
        "longitud": -5.926788955974699,
        "confianza": 0.93,
        "coincideNumero": true,
        "coincideMunicipio": true,
        "enCopia": true,
        "direccionCatastro": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
        "uso": "Residencial",
        "viviendas": 346,
        "anioConstruccion": 2023
      },
      {
        "refCatastral": "0747201TG4304N",
        "pais": "ES",
        "direccion": "BULEVAR JOSE RODRIGUEZ DE LA BORBOLLA CAMOYAN 11",
        "numero": 11,
        "confianza": 0.55,
        "coincideNumero": false,
        "coincideMunicipio": true,
        "enCopia": true
      }
    ],
    "attribution": "CartoCiudad (Instituto Geográfico Nacional) y Dirección General del Catastro"
  }
}

Możliwe błędy

KodHTTPOpis
VALIDATION_ERROR400Referencja nie ma prawidłowego formatu dla danego kraju.
NOT_FOUND404No building entrance with a cadastral reference matches the address.
KEY_AUTH_004429Wyczerpany miesięczny limit klucza API (zob. nagłówki X-Quota-*).
SERVICE_UNAVAILABLE503CartoCiudad is not answering. Retry after Retry-After.
GET/api/catastro/:refcat

Pobierz dane działki według referencji katastralnej (14 lub 20 znaków).

Parametry

:refcatstringReferencja katastralna (np. 9872023VH5797S0001WX)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "9872023VH5797S0001WX",
    "direccion": "CL GLORIA 51",
    "codigoPostal": "13730",
    "municipio": "SANTA CRUZ DE MUDELA",
    "provincia": "CIUDAD REAL",
    "latitud": 38.640143,
    "longitud": -3.463284,
    "googleMapsUrl": "https://www.google.com/maps?q=38.640143,-3.463284",
    "uso": "Residencial",
    "clase": "Urbano",
    "superficieConstruida": 308,
    "superficieParcela": 397,
    "anioConstruccion": 1980,
    "coefParticipacion": "100",
    "poligono": [ /* geometría de la parcela */ ],
    "availableFields": {
      "uso": true, "clase": true, "anioConstruccion": true,
      "superficieConstruida": true, "coefParticipacion": true,
      "direccion": true, "busquedaDireccion": true
    }
  },
  "searchesRemaining": 4
}

Możliwe błędy

KodHTTPOpis
VALIDATION_ERROR400Referencja nie ma prawidłowego formatu dla danego kraju.
NOT_FOUND404Nie znaleziono referencji. Nieobsługiwany ?country jest traktowany jako Hiszpania (ES) i zwykle zwraca NOT_FOUND; używaj ES/PT/FR/IT/DE/PV/NA. Dla katastrów foralnych (NA, PV) pole message zawiera wskazówkę dotyczącą formatu.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429KEY_RATE_002: minutowy limit chwilowy Twojego klucza. RATE_LIMIT_EXCEEDED: zbyt wiele żądań z tego samego IP. DAILY_LIMIT_REACHED: dzienny limit darmowych wyszukiwań bez klucza API.
KEY_AUTH_004429Wyczerpany miesięczny limit klucza API (zob. nagłówki X-Quota-*).
SERVICE_UNAVAILABLE503Oficjalna usługa katastralna danego kraju nie działa lub jest w trakcie prac konserwacyjnych. Spróbuj ponownie.
GET/api/catastro/:refcat14/units

Wszystkie lokale hiszpańskiej nieruchomości na podstawie 14-znakowego numeru, w jednym wywołaniu (do 200 na stronę, z kursorem). Każdy lokal zawiera przeznaczenie, powierzchnię, udział, rok oraz klatkę/piętro/drzwi. Kosztuje 1 jednostkę limitu za każdy zwrócony lokal (minimum 1). Wymaga klucza API lub zalogowanej sesji. Źródło: Dirección General del Catastro.

Parametry

:refcat14string14-znakowy numer katastralny nieruchomości (np. 0745901TG4304N)
cursorstringOpcjonalnie. nextCursor poprzedniej strony, gdy truncated ma wartość true.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/0745901TG4304N/units"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "0745901TG4304N",
    "direccion": "AV JOSE RGUEZ BORBOLLA CAMOY 10",
    "codigoPostal": "41704",
    "municipio": "DOS HERMANAS",
    "provincia": "Sevilla",
    "usoGeneral": "Residencial",
    "superficieTotal": 32789,
    "anioConstruccion": 2023,
    "totalUnidades": 200,
    "totalUnidadesFinca": 365,
    "truncated": true,
    "nextCursor": "0745901TG4304N0201MZ",
    "dataSource": "clone",
    "dataDate": "2026-08-19",
    "attribution": "Dirección General del Catastro",
    "unidades": [
      {
        "refCatastral": "0745901TG4304N0002KH",
        "planta": "01",
        "puerta": "B",
        "uso": "Residencial",
        "superficie": 155,
        "participacion": 0.279543,
        "anio": 2023,
        "descripcion": "Planta 01, Pta. B - Residencial"
      }
    ]
  }
}

Możliwe błędy

KodHTTPOpis
VALIDATION_ERROR400Kursor nie jest 20-znakowym numerem tej nieruchomości.
UNAUTHORIZED / UNT_001401Brak klucza API organizacji i brak zalogowanej sesji.
NOT_FOUND404Nieruchomości nie ma ani w naszej kopii Catastro, ani w Catastro.
CNV_COVERAGE422The finca is in the Basque Country or Navarra: their foral cadastre is not served per finca.
KEY_AUTH_004429Wyczerpany miesięczny limit klucza API (zob. nagłówki X-Quota-*).
SERVICE_UNAVAILABLE503Oficjalna usługa katastralna danego kraju nie działa lub jest w trakcie prac konserwacyjnych. Spróbuj ponownie.
GET/api/catastro/:refcat/terrain

Rzeźba terenu liczona na poligonie działki z Copernicus DEM GLO-30 (30 m): średnia, minimalna i maksymalna wysokość, średnie i maksymalne nachylenie z klasą i rozkładem, udział powierzchni o nachyleniu > 10 % oraz dominująca ekspozycja. Do tego przecięcie z siecią Natura 2000 (EEA, end 2024) i krajowymi formami ochrony (CDDA 2025): nazwa, kod, typ (SPA = OSO, SCI = SOO) i udział działki w każdym obszarze. Każdy blok podaje źródło i licencję. status = ok, no_data (brak pokrycia) lub unavailable (chwilowy błąd, ponów). Ta sama działka, ta sama jednostka limitu co odczyt.

Parametry

:refcatstringReferencja katastralna
countrystringOpcjonalnie. ES, PV, NA, PT, FR, IT, DE; ustalany z referencji, gdy go brak.
lat, lngnumberTylko dla pozostałych krajów z własną geometrią: przybliżone położenie działki do odnalezienia jej obrysu.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/10194A00110004/terrain?country=ES"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refcat": "10194A00110004",
    "country": "ES",
    "relief": {
      "status": "ok",
      "elevation_m": { "mean": 365.8, "min": 212.3, "max": 506.6 },
      "slope": {
        "mean_pct": 36.5, "mean_deg": 20, "max_pct": 71.6,
        "class": "very_steep", "max_class": "very_steep", "share_over_10_pct": 98.4,
        "classes_pct": { "flat": 0.2, "gentle": 1.4, "moderate": 6.8, "steep": 20, "very_steep": 71.7 }
      },
      "aspect": {
        "dominant": "N", "dominant_share_pct": 75.3, "mean_deg": 0, "flat_share_pct": 0.2,
        "sectors_pct": { "N": 75.3, "NE": 10.6, "E": 0.6, "SE": 0.1, "S": 0, "SW": 1, "W": 1.4, "NW": 10.8 }
      },
      "sample": { "method": "parcel", "cells": 1448, "resolution_m": 31 },
      "source": { "name": "Copernicus DEM GLO-30", "license": "Copernicus DEM licence (free, commercial use allowed)", "attribution": "© DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved" }
    },
    "protected_areas": {
      "status": "ok",
      "intersects": true,
      "inside": true,
      "max_overlap_pct": 100,
      "natura2000": [
        { "code": "ES0000014", "name": "Monfragüe y las Dehesas del Entorno", "type": "SPA", "country": "ES", "overlap_pct": 100 },
        { "code": "ES4320077", "name": "Monfragüe", "type": "SCI", "country": "ES", "overlap_pct": 100 }
      ],
      "national": [
        { "code": "4820", "name": "Monfragüe", "designation": "National Park", "country": "ES", "overlap_pct": 100 }
      ],
      "method": "parcel",
      "sources": [
        { "name": "Natura 2000", "license": "CC BY 4.0", "edition": "end 2024" },
        { "name": "Nationally designated areas (CDDA)", "license": "CC BY 4.0", "edition": "2025" }
      ]
    },
    "calculated_at": "2026-09-30T19:45:02Z",
    "provenance": "3"
  }
}

Możliwe błędy

KodHTTPOpis
UNAUTHORIZED401Brak klucza API organizacji i brak zalogowanej sesji.
NOT_FOUND404Działka nie istnieje lub poza siedmioma głównymi krajami nie ma obrysu w tym miejscu.
KEY_AUTH_004429Wyczerpany miesięczny limit klucza API (zob. nagłówki X-Quota-*).
TRN_040503Oficjalna usługa katastralna danego kraju nie działa lub jest w trakcie prac konserwacyjnych. Spróbuj ponownie.
GET/api/catastro/:refcat/ground-motion

Prędkość pionowa i wschód-zachód gruntu na poligonie działki z European Ground Motion Service programu Copernicus (EGMS L3 Ortho, radar Sentinel-1, siatka 100 m, 2020-2024): średnia, najsilniejsze osiadanie, najsilniejsze wypiętrzanie, klasa, komórki z danymi i średnie przemieszczenie w każdym roku. Bez reflektorów (pole, las, woda) odpowiedź to status = no_data z reason = no_reflectors zamiast szacunku. Cały zasięg EGMS (EEA-39). Zawiera źródło, licencję i wymagane oznaczenie autorstwa. Ta sama działka, ta sama jednostka limitu co wyszukiwanie.

Parametry

:refcatstringReferencja katastralna
countrystringOpcjonalnie. ES, PV, NA, PT, FR, IT, DE; ustalany z referencji, gdy go brak.
lat, lngnumberTylko dla pozostałych krajów z własną geometrią: przybliżone położenie działki do odnalezienia jej obrysu.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/30024A16000286/ground-motion?country=ES"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refcat": "30024A16000286",
    "country": "ES",
    "status": "ok",
    "period": { "from": "2020-01", "to": "2024-12", "label": "2020-2024" },
    "ground_motion": {
      "class": "severe_subsidence",
      "worst_class": "severe_subsidence",
      "vertical": {
        "mean_mm_year": -40.9, "max_subsidence_mm_year": -40.9, "max_uplift_mm_year": 0,
        "std_mm_year": 0.1, "acceleration_mm_year2": -0.7, "rmse_mm": 2.3
      },
      "east_west": { "mean_mm_year": -5.1, "std_mm_year": 0.1 },
      "yearly_displacement": [
        { "year": 2020, "mm": -17.9 }, { "year": 2021, "mm": -57.2 }, { "year": 2022, "mm": -95.8 },
        { "year": 2023, "mm": -141.8 }, { "year": 2024, "mm": -179.8 }
      ],
      "cells_with_data": 1, "cells_considered": 1, "coverage_pct": 100,
      "basis": "parcel", "cell_size_m": 100
    },
    "source": {
      "name": "European Ground Motion Service (EGMS) L3 Ortho",
      "license": "Copernicus data policy (Regulation (EU) No 1159/2013): free, commercial use allowed with attribution",
      "attribution": "Contains modified Copernicus Land Monitoring Service information, European Ground Motion Service 2020-2024 (© European Union, Copernicus Land Monitoring Service, EEA)",
      "resolution": "100 m"
    },
    "calculated_at": "2026-10-01T06:14:34Z",
    "provenance": "1"
  }
}

Możliwe błędy

KodHTTPOpis
UNAUTHORIZED401Brak klucza API organizacji i brak zalogowanej sesji.
NOT_FOUND404Działka nie istnieje lub poza siedmioma głównymi krajami nie ma obrysu w tym miejscu.
KEY_AUTH_004429Wyczerpany miesięczny limit klucza API (zob. nagłówki X-Quota-*).
GMV_040503Oficjalna usługa katastralna danego kraju nie działa lub jest w trakcie prac konserwacyjnych. Spróbuj ponownie.
POST/api/search/coordinates

Geokodowanie odwrotne: znajdź działkę katastralną pod podanymi współrzędnymi GPS.

Parametry

latitudenumberSzerokość geograficzna (WGS84)
longitudenumberDługość geograficzna (WGS84)
countrystringKod kraju (opcjonalny: rozpoznawany na podstawie referencji)
curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 40.4168, "longitude": -3.7038, "country": "ES"}' \
  "https://api.parcelgps.com/api/search/coordinates"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "referenciaCatastral": "9872023VH5797S0001WX",
    "refCat14": "9872023VH5797S",
    "direccion": "CL GRAN VIA 1",
    "municipio": "MADRID",
    "tipoInmueble": "",
    "coordenadas": { "latitud": 40.4168, "longitud": -3.7038 },
    "googleMapsUrl": "https://maps.google.com/?q=40.4168,-3.7038"
  },
  "searchesRemaining": 3
}

Możliwe błędy

KodHTTPOpis
VALIDATION_ERROR400Współrzędne poza granicami podanego lub rozpoznanego kraju albo brakujące lub błędne lat/lng.
NOT_FOUND404Pod tymi współrzędnymi nie ma działki.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429KEY_RATE_002: minutowy limit chwilowy Twojego klucza. RATE_LIMIT_EXCEEDED: zbyt wiele żądań z tego samego IP. DAILY_LIMIT_REACHED: dzienny limit darmowych wyszukiwań bez klucza API.
SERVICE_UNAVAILABLE503Usługa katastralna chwilowo niedostępna.
POST/api/search/address/parse

Wyszukaj działkę katastralną według adresu pocztowego.

Parametry

direccionstringAdres w dowolnej formie (tylko Hiszpania). Zalecany format: «Ulica, Numer, Gmina» — np. «Calle Mallorca, 213, Barcelona». Numer domu może też być dołączony do ulicy («Gran Vía 1, Madrid»).
curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direccion": "Gran Via 1, Madrid"}' \
  "https://api.parcelgps.com/api/search/address/parse"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "referenciaCatastral": "0847106VK4704F",
    "refCat14": "0847106VK4704F",
    "direccion": "CL GRAN VIA, 1, Madrid",
    "tipoVia": "CL",
    "nombreVia": "GRAN VIA",
    "numero": 1,
    "municipio": "Madrid",
    "provincia": "MADRID"
  },
  "searchesRemaining": -1
}

Możliwe błędy

KodHTTPOpis
VALIDATION_ERROR400Nieprawidłowa treść żądania (brakujące pola lub błędny JSON).
NOT_FOUND404Nie znaleziono adresu (ulica, gmina lub numer nie istnieje albo nie ma odpowiednika w katastrze). Wyszukiwanie po adresie jest dostępne tylko w Hiszpanii.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429KEY_RATE_002: minutowy limit chwilowy Twojego klucza. RATE_LIMIT_EXCEEDED: zbyt wiele żądań z tego samego IP. DAILY_LIMIT_REACHED: dzienny limit darmowych wyszukiwań bez klucza API.

Kraj Basków (PV)

Katastry foralne — Araba/Álava, Bizkaia i Gipuzkoa (INSPIRE WFS)

GET/api/catastro/:refcat?country=PV

Wyszukiwanie działek na trzech terytoriach foralnych. Wymaga country=PV: ich działki mają własny kataster i nie ma ich w centralnym Catastro.

Parametry

:refcatstringReferencja foralna. Bizkaia z kropkami (48.020.1611.02001); Álava i Gipuzkoa cyframi (64010007, 8594149).
countrystringWymagane: PV.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/48.020.1611.02001?country=PV"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "48.020.1611.02001",
    "pais": "PV",
    "municipio": "Bizkaia",
    "provincia": "Bizkaia",
    "latitud": 43.263633,
    "longitud": -2.935856,
    "superficieParcela": 3061,
    "googleMapsUrl": "https://www.google.com/maps?q=43.263633,-2.935856",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Z country=ES (nieprawidłowo)

404
{
  "success": false,
  "error": "Parcela no encontrado: 48.020.1611.02001",
  "code": "NOT_FOUND"
}

Portugalia (PT)

Kataster Portugalii — Direção-Geral do Território

GET/api/catastro/:refcat?country=PT

Pobierz dane działki w Portugalii według referencji katastralnej.

Parametry

:refcatstringPortugalska referencja katastralna (np. AAA000587359). Zasięg częściowy (~30%); obszary takie jak Lizbona i Porto nie zostały jeszcze zdigitalizowane przez DGT.
countrystringWymagane: PT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/AAA000587359?country=PT"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "AAA000587359",
    "pais": "PT",
    "municipio": "TAVIRA, Tavira (Santa Maria e Santiago)",
    "latitud": 37.127156,
    "longitud": -7.648066,
    "superficieParcela": 49,
    "googleMapsUrl": "https://www.google.com/maps?q=37.127156,-7.648066",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Francja (FR)

Kataster Francji — Cadastre / Géoplateforme

GET/api/search/address/candidates?country=FR

Zamienia francuski adres na działkę katastralną (14-znakowy IDU) pod nim: geokodowanie przez Base Adresse Nationale i zapytanie do oficjalnego katastru w tym punkcie. Kandydaci uporządkowani według pewności (od 0 do 1). Kosztuje 1 jednostkę limitu tylko, gdy zwraca kandydatów.

Parametry

qstringFree-text address: street and number, municipality (and postcode if you have it).
countrystringWymagane: FR.
street / number / municipality / postcode / limitstringOptional: street, number, municipality, postcode (override what is read from q) and limit (1-10, default 5).
curl -G -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/search/address/candidates" \
  --data-urlencode "q=8 boulevard du Port, Amiens" -d country=FR

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "consulta": { "texto": "8 boulevard du Port, Amiens", "calle": "boulevard du Port", "numero": 8, "municipio": "Amiens" },
    "candidatos": [
      {
        "refCatastral": "80021000VA0065",
        "pais": "FR",
        "direccion": "8 Boulevard du Port 80000 Amiens",
        "numero": 8,
        "codigoPostal": "80000",
        "municipio": "Amiens",
        "provincia": "Somme",
        "latitud": 49.897442,
        "longitud": 2.290084,
        "confianza": 0.99,
        "coincideNumero": true,
        "coincideMunicipio": true,
        "enCopia": false
      }
    ],
    "attribution": "Base Adresse Nationale (data.gouv.fr); Plan cadastral (DGFiP, Géoplateforme IGN)"
  }
}

Możliwe błędy

KodHTTPOpis
VALIDATION_ERROR400Referencja nie ma prawidłowego formatu dla danego kraju.
NOT_FOUND404No building entrance with a cadastral reference matches the address.
CNV_COVERAGE422Kraj nie ma wyszukiwania po adresie (SE, HR lub kraj bez pokrycia)
KEY_AUTH_004429Wyczerpany miesięczny limit klucza API (zob. nagłówki X-Quota-*).
SERVICE_UNAVAILABLE503CartoCiudad is not answering. Retry after Retry-After.
GET/api/catastro/:refcat?country=FR

Pobierz dane działki we Francji według referencji katastralnej.

Parametry

:refcatstringFrancuska referencja katastralna (np. 75104000AE0003)
countrystringWymagane: FR.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/75104000AE0003?country=FR"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "75104000AE0003",
    "pais": "FR",
    "municipio": "Paris",
    "provincia": "75",
    "latitud": 48.856347,
    "longitud": 2.352415,
    "superficieParcela": 15168,
    "googleMapsUrl": "https://www.google.com/maps?q=48.856347,2.352415",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Włochy (IT)

Kataster Włoch — Agenzia delle Entrate

GET/api/search/address/candidates?country=IT

Zamienia włoski adres na działkę (particella) pod nim: geokodowanie przez OpenStreetMap (Photon, z Nominatim jako zapasowym) i zapytanie do Agenzia delle Entrate w tym punkcie. Nigdy nie zwraca ulic ani wód (STRADA, ACQUA): gdy punkt wypada na ulicy, bierze najbliższą działkę. Kosztuje 1 jednostkę limitu tylko, gdy zwraca kandydatów.

Parametry

qstringFree-text address: street and number, municipality (and postcode if you have it).
countrystringWymagane: IT.
street / number / municipality / postcode / limitstringOptional: street, number, municipality, postcode (override what is read from q) and limit (1-10, default 5).
curl -G -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/search/address/candidates" \
  --data-urlencode "q=Via Toledo 256, Napoli" -d country=IT

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "consulta": { "texto": "Via Toledo 256, Napoli", "calle": "Via Toledo", "numero": 256, "municipio": "Napoli" },
    "candidatos": [
      {
        "refCatastral": "F839_019800.166",
        "pais": "IT",
        "direccion": "Via Toledo 256, 80132 Napoli",
        "numero": 256,
        "codigoPostal": "80132",
        "municipio": "Napoli",
        "provincia": "Napoli",
        "latitud": 40.8386034,
        "longitud": 14.248223,
        "confianza": 1,
        "coincideNumero": true,
        "coincideMunicipio": true,
        "enCopia": false
      }
    ],
    "attribution": "OpenStreetMap contributors (ODbL); Agenzia delle Entrate, cartografia catastale (CC BY 4.0)"
  }
}

Możliwe błędy

KodHTTPOpis
VALIDATION_ERROR400Referencja nie ma prawidłowego formatu dla danego kraju.
NOT_FOUND404No building entrance with a cadastral reference matches the address.
CNV_COVERAGE422Kraj nie ma wyszukiwania po adresie (SE, HR lub kraj bez pokrycia)
KEY_AUTH_004429Wyczerpany miesięczny limit klucza API (zob. nagłówki X-Quota-*).
SERVICE_UNAVAILABLE503CartoCiudad is not answering. Retry after Retry-After.
GET/api/catastro/:refcat?country=IT

Pobierz dane działki we Włoszech według referencji katastralnej.

Parametry

:refcatstringWłoska referencja katastralna (foglio/particella, np. H501A048100.A)
countrystringWymagane: IT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/H501A048100.A?country=IT"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "H501A048100.A",
    "pais": "IT",
    "municipio": "H501",
    "provincia": "H501",
    "latitud": 41.902698,
    "longitud": 12.496247,
    "superficieParcela": 1059,
    "googleMapsUrl": "https://www.google.com/maps?q=41.902698,12.496247",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Niemcy (DE)

Kataster Niemiec — ALKIS (8 krajów związkowych)

GET/api/catastro/:refcat?country=DE

Pobierz dane działki w Niemczech według referencji katastralnej.

Parametry

:refcatstringNiemiecka referencja katastralna (Flurstückskennzeichen)
countrystringWymagane: DE.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/05495803101122?country=DE"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "05495803101122",
    "pais": "DE",
    "latitud": 50.937566,
    "longitud": 6.960140,
    "superficieParcela": 54,
    "googleMapsUrl": "https://www.google.com/maps?q=50.937566,6.960140",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Austria (AT)

Kataster Austrii — BEV (Katastralgemeinde / Grundstück)

GET/api/catastro/:refcat?country=AT

Wyszukiwanie działek w Austrii. Wymaga country=AT. Referencja ma format KATASTRALGEMEINDE-GRUNDSTÜCK. Zasięg częściowy, rozszerzany.

Parametry

:refcatstringFormat Katastralgemeinde-Grundstück (np. 01004-1711).
countrystringWymagane: AT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/01004-1711?country=AT"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "01004-1711",
    "pais": "AT",
    "municipio": "Innere Stadt",
    "provincia": "Wien",
    "latitud": 48.208478,
    "longitud": 16.372810,
    "uso": "Gebäude, Straßenverkehrsanlagen",
    "superficieParcela": 10641,
    "googleMapsUrl": "https://www.google.com/maps?q=48.208478,16.372810",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Z country=ES (nieprawidłowo)

400
{
  "success": false,
  "error": "La referencia catastral debe tener al menos 14 caracteres",
  "code": "VALIDATION_ERROR"
}

Reszta Europy (adres)

Wyszukiwanie po adresie działa tak samo w 26 krajach: w Holandii, Szwajcarii, Polsce, Czechach, Estonii, Danii i Flandrii z urzędowym rejestrem adresów, w pozostałych z OpenStreetMap. Działka zawsze pochodzi z urzędowego katastru danego kraju. Szwecja i Chorwacja go nie mają.

GET/api/search/address/candidates?country=NL

Zamienia europejski adres na działkę ewidencyjną pod nim: geokoduje urzędowym rejestrem adresów (PDOK w Holandii) lub OpenStreetMap i odpytuje w tym punkcie urzędowy kataster kraju. Kandydaci według pewności (od 0 do 1). Kosztuje 1 jednostkę limitu tylko wtedy, gdy zwraca kandydatów.

Parametry

qstringFree-text address: street and number, municipality (and postcode if you have it).
countrystringWymagane: NL.
street / number / municipality / postcode / limitstringOptional: street, number, municipality, postcode (override what is read from q) and limit (1-10, default 5).
curl -G -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/search/address/candidates" \
  --data-urlencode "q=Damrak 1, 1012 LG Amsterdam" -d country=NL

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "consulta": { "texto": "Damrak 1, 1012 LG Amsterdam", "calle": "Damrak", "numero": 1, "municipio": "Amsterdam", "codigoPostal": "1012 LG" },
    "candidatos": [
      {
        "refCatastral": "ASD04-F-3937",
        "pais": "NL",
        "direccion": "Damrak 1, 1012LG Amsterdam",
        "numero": 1,
        "codigoPostal": "1012LG",
        "municipio": "Amsterdam",
        "provincia": "Noord-Holland",
        "latitud": 52.37714446,
        "longitud": 4.89803846,
        "confianza": 1,
        "coincideNumero": true,
        "coincideMunicipio": true,
        "enCopia": false
      }
    ],
    "attribution": "PDOK Locatieserver (Kadaster, BAG); Kadaster, Basisregistratie Kadaster (PDOK, CC BY 4.0)"
  }
}

Możliwe błędy

KodHTTPOpis
VALIDATION_ERROR400Referencja nie ma prawidłowego formatu dla danego kraju.
NOT_FOUND404No building entrance with a cadastral reference matches the address.
CNV_COVERAGE422Kraj nie ma wyszukiwania po adresie (SE, HR lub kraj bez pokrycia)
KEY_AUTH_004429Wyczerpany miesięczny limit klucza API (zob. nagłówki X-Quota-*).
SERVICE_UNAVAILABLE503CartoCiudad is not answering. Retry after Retry-After.

Analityka działek i eksport

Geometria, potencjał fotowoltaiczny, dane rolne i eksport plików (KML/GPX/PDF/DXF), dostępne z Twoim kluczem API. Dane rynkowe i ocena inwestycyjna pozostają w wersji webowej i aplikacji mobilnej (Pro) i nie są udostępniane przez API.

GET/api/catastro/:refcat/polygon

Pobierz poligon GeoJSON działki.

Parametry

:refcatstringReferencja katastralna
countrystringKod kraju (parametr zapytania, domyślnie: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon"

Przykładowa odpowiedź

200 OK
{
  "data": {
    "refcat": "9872023VH5797S",
    "geojson": {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [ [ [-3.463391, 38.640317], [-3.463174, 38.640217], /* ... */ ] ]
      }
    }
  }
}

Wyczerpany limit miesięczny

429
{
  "success": false,
  "error": "Cuota mensual agotada (5000/5000). Upgrade en https://catastrogps.es/developers",
  "code": "KEY_AUTH_004"
}
GET/api/catastro/:refcat/solar

Pobierz dane o potencjale fotowoltaicznym (PVGIS) dla dowolnej działki w Europie.

Parametry

:refcatstringReferencja katastralna
countrystringKod kraju (parametr zapytania, domyślnie: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "kwh_year": 23749.9,
    "kw_instalables": 17.86,
    "ahorro_anual_eur": 3562.49,
    "amortizacion_anos": 5,
    "co2_evitado_kg": 5533.73,
    "irradiacion_media": 1807.08,
    "nota_solar": 5,
    "orientacion_optima": "Sur",
    "angulo_inclinacion": 34,
    "costo_instalacion_eur": 17865,
    "disponible": true,
    "estado": "ok",
    "fuente": "PVGIS (JRC)",
    "economics": {
      "autoconsumo_kwh_ano": 5000,
      "excedentes_kwh_ano": 18749.9,
      "ingreso_neto_anual_eur": 1473.18,
      "payback_anos": 12.13,
      "tir_pct": 6.56,
      "retorno_total_25_anos_eur": 18964.5
    }
  }
}

Działka bez danych fotowoltaicznych

200
{
  "success": true,
  "data": { "disponible": false, "estado": "sin_datos" }
}
GET/api/catastro/:refcat/agro

Dane gruntów rolnych działki (SIGPAC): główna uprawa, użytkowanie gruntu, nachylenie, wysokość n.p.m. i powierzchnia. Tylko działki rolne — działki miejskie zwracają "cultivo_principal": "urbano".

Parametry

:refcatstringReferencja katastralna
countrystringKod kraju (parametr zapytania, domyślnie: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/23058A00700036/agro"

Przykładowa odpowiedź

200 OK
{
  "success": true,
  "data": {
    "agro": {
      "cultivo_principal": "olivar",
      "uso_suelo": "Asociación olivar - viñedo",
      "superficie_ha": 10.6045,
      "coef_regadio": 1,
      "ndvi": {
        "valor_medio": 0.18,
        "salud_cultivo": "bajo",
        "ultima_actualizacion": "2026-06-18T00:00:00Z"
      },
      "precios_mercado": {
        "precio_kg": 8.5,
        "tendencia": "+12.5% vs periodo anterior"
      },
      "recinto": {
        "provincia": 23,
        "municipio": 58,
        "poligono": 7,
        "parcela": 36,
        "recinto": 1,
        "altitud": 559,
        "pendiente_media": 12.3
      }
    }
  }
}

Wyczerpany limit miesięczny

429
{
  "success": false,
  "error": "Cuota mensual agotada (5000/5000). Upgrade en https://catastrogps.es/developers",
  "code": "KEY_AUTH_004"
}
GET/api/export/kml?refcat=:refcat

Eksportuj dane działki w formacie KML (Google Earth).

Parametry

refcatstringReferencja katastralna
countrystringKod kraju (opcjonalny: rozpoznawany na podstawie referencji)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kml

Przykładowa odpowiedź

200 OK
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <name>9872023VH5797S</name>
      ...
    </Placemark>
  </Document>
</kml>
GET/api/export/gpx?refcat=:refcat

Eksportuj dane działki w formacie GPX (nawigacje GPS).

Parametry

refcatstringReferencja katastralna
countrystringKod kraju (opcjonalny: rozpoznawany na podstawie referencji)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpx

Przykładowa odpowiedź

200 OK
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1">
  <wpt lat="40.4168" lon="-3.7038">
    <name>9872023VH5797S</name>
  </wpt>
</gpx>

Dziennik zmian

Co trafiło do API w tym tygodniu, z numerem zmiany w repozytorium. Odpowiedzi pozostają zgodne wstecz: żadne istniejące pole nie zmienia nazwy.

  • Wyszukiwanie działki po adresie w 26 krajach europejskich z /api/search/address/candidates?country=XX: oficjalny rejestr adresów tam, gdzie istnieje (Holandia, Szwajcaria, Polska, Czechy, Estonia, Dania, Flandria), a w pozostałych krajach OpenStreetMap, maksymalnie 10 sekund na punkt. Zmiany: #93, #94
  • Nowy endpoint /api/catastro/:refcat/ground-motion: prędkość ruchu gruntu w pionie i w kierunku wschód-zachód z Copernicus EGMS 2020-2024 w całym jego zasięgu, w tym ponownie opublikowane kafle Holandii, Belgii i Pirenejów. Zmiany: #80, #91
  • Blok climate w /terrain z normami klimatycznymi ERA5-Land. Siatka jest w trakcie ładowania: do czasu jego zakończenia odpowiada status unavailable. Zmiany: #78
  • Poza Hiszpanią: availableFields informuje, co zawiera każda odpowiedź, puste odpowiedzi nic nie kosztują, /solar /agro /score odpowiadają 422 CNV_COVERAGE tam, gdzie nie ma danych, niejednoznaczne ciągi cyfr odpowiadają 300 CNV_AMBIGUOUS, referencja wraca w całości, a Belgia zwraca szerokość i długość geograficzną we właściwej kolejności. Zmiany: #76
  • Z kluczem API teksty błędów są w języku angielskim; pole code się nie zmienia. Zmiany: #77
  • Wyszukiwanie działki po adresie we Francji (Base Adresse Nationale) i we Włoszech; Niemcy i Austria według współrzędnych, z powierzchnią i obrysem; Cypr w mniej niż sekundę; /terrain i /ground-motion znajdują obrys w pozostałej części Europy. Zmiany: #83, #84, #85, #86
  • POST /api/search/coordinates kieruje zapytania dla każdego kraju tak samo jak GET. Zmiany: #79
  • /terrain i /ground-motion dekodują referencje z ukośnikiem (Belgia, Czechy, Polska): pole refcat nie wraca już jako %2F. Zmiany: #95

  • Nowy endpoint /api/catastro/:refcat/terrain: rzeźba terenu w obrębie obrysu (Copernicus DEM GLO-30) i przecięcie z obszarami Natura 2000 oraz krajowymi obszarami chronionymi (CDDA), bez powtarzania obszarów występujących na obu listach. Zmiany: #67, #69, #70
  • Nowy endpoint /api/catastro/:refcat14/units: wszystkie jednostki hiszpańskiej finca, 200 na stronę z kursorem, po 1 jednostce limitu za każdą zwróconą jednostkę i nigdy więcej, niż Ci pozostało; Kraj Basków i Nawarra odpowiadają 422 CNV_COVERAGE. Zmiany: #53, #55, #73, #74, #75
  • Wyszukiwanie finca po adresie w Hiszpanii z kandydatami z CartoCiudad, ETag i bezpłatnym 304 przy ponownym imporcie oraz specyfikacja OpenAPI 3.1 pod /api/openapi.json. Zmiany: #72
  • Nagłówki X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset i X-Quota-Tier z miesięcznym limitem oraz limit na minutę dla każdego klucza zależny od planu. Zmiany: #52, #58