Dokumentace API

Kompletní reference katastrálního API

Základní 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

Kódy zemí

Endpointy přijímají ?country=XX. Je volitelný: bez něj API rozpozná zemi podle tvaru reference v 21 zemích. Nejednoznačná reference vrátí 300 CNV_AMBIGUOUS s kandidáty; země, kterou zatím nepokrýváme, 422 CNV_COVERAGE; něco, co vypadá jako místní název, 422 CNV_PLACE_NAME s geokódovaným bodem. Pevninské Španělsko používá ES, ale Baskicko a Navarra mají vlastní (foralní) katastry a potřebují vlastní kód: s ES se jejich parcely nenajdou.

ES · ŠpanělskoPV · BaskickoNA · NavarraPT · PortugalskoFR · FrancieIT · ItálieDE · NěmeckoAT · RakouskoPL · PolskoNL · NizozemskoCZ · ČeskoFI · FinskoBE · BelgieEE · EstonskoSI · SlovinskoLT · LitvaLU · LucemburskoSK · SlovenskoBG · BulharskoCY · KyprIS · IslandLI · LichtenštejnskoCH · Švýcarsko

Reference endpointů

MetodaEndpointOvěřeníPopis
GET/api/resolve?q=TEXTAPI KeyKlasifikuje jakýkoli vstup: referenci (a zemi), souřadnice nebo místní název. Nezapočítává se do kvóty.
GET/api/search/address/candidates?q=TEXT&country=XXAPI KeyAdresa → parcela s kandidáty podle jistoty: Španělsko a dalších 25 evropských zemí
GET/api/catastro/:refcatAPI KeyVyhledání parcely
GET/api/catastro/:refcat14/unitsAPI KeyVšechny jednotky pozemku (byty, prostory, garáže) — Španělsko
GET/api/catastro/:refcat/polygon?country=XXAPI KeyGeometrie parcely (GeoJSON)
GET/api/catastro/:refcat/terrain?country=XXAPI KeyReliéf (nadmořská výška, sklon, orientace) a Natura 2000 / chráněná území parcely
GET/api/catastro/:refcat/ground-motion?country=XXAPI KeyPohyb terénu (pokles nebo zdvih v mm/rok, 2020-2024) měřený satelitem
GET/api/catastro/:refcat/solar?country=XXAPI KeySolární potenciál
GET/api/catastro/:refcat/agro?country=XXAPI KeyÚdaje o zemědělské půdě
GET/api/export/kml?refcat=X&country=XAPI KeyExport KML/GPX/PDF/DXF
GET/api/catastro/:refcat/market?country=XXWeb a aplikaceTržní údaje (ne přes API)
GET/api/catastro/:refcat/score?country=XXWeb a aplikaceInvestiční skóre (ne přes API)

Spolehlivost

Co poskytujeme z vlastní infrastruktury a co závisí na veřejném úřadu. Vyplatí se to přečíst před nasazením do produkce.

EndpointOdkud údaje pocházejí
/catastro/:refcat (ES)Naše vlastní kopie katastru (50,9 mil. parcel). K odpovědi nepotřebuje Catastro.
/polygon · /search/address · /search/coordinatesCatastro (veřejný úřad). Může bez varování selhat.
/agroSIGPAC
/solarPVGIS

Chyby a opakování

503 znamená, že oficiální zdroj právě neodpovídá: opakujte s postupným odstupem (backoff) a problém sám odezní. 429 je vaše kvóta a opakováním ji nezískáte zpět — počkejte na obnovení nebo přejděte na vyšší tarif. 404 je reference, která neexistuje, a neměla by se opakovat.

Stavová stránka

Zveřejňujeme stav našeho API a devíti katastrálních zdrojů, na kterých závisíme. Kontrolujeme je každých pět minut a stránka běží mimo toto API, aby zůstala důvěryhodná i během výpadku: catastrogps.es/status.

Ověření

Všechny požadavky na API vyžadují API klíč zaslaný v hlavičce X-API-Key.

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

Bezplatný API klíč získáte na své vývojářské nástěnce.

Chybové kódy

StavKódPopis
200—OK — Požadavek byl úspěšně dokončen.
400VALIDATION_ERRORBad Request — Neplatné parametry nebo katastrální reference ve špatném formátu.
401UNAUTHORIZEDUnauthorized — Neplatný, prošlý nebo chybějící API klíč.
404NOT_FOUNDNot Found — Pro zadanou referenci nebo souřadnice nebyla nalezena žádná parcela. Nespotřebovává kvótu.
429KEY_AUTH_004Quota Exceeded — Vyčerpali jste měsíční kvótu svého tarifu. Hlavičky X-Quota-Remaining a X-Quota-Reset ukazují, kolik zbývá a kdy se obnoví.
429RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHEDToo Many Requests — KEY_RATE_002: překročili jste minutový nárazový limit svého klíče (Free 10, Developer 60, Startup 120, Growth 300). RATE_LIMIT_EXCEEDED: příliš mnoho požadavků ze stejné IP. Obě odpovědi obsahují X-RateLimit-* a Retry-After. DAILY_LIMIT_REACHED: denní limit bezplatných vyhledávání bez API klíče.
500INTERNAL_ERRORInternal Server Error — Chyba na naší straně. Pokud přetrvává, kontaktujte podporu.
503SERVICE_UNAVAILABLEService Unavailable — Externí katastrální služba požadované země je dočasně nedostupná. Tyto služby provozují veřejné úřady (Catastro, DGT, Géoportail, Agenzia Entrate, ALKIS...) a nemáme je pod kontrolou. Zkuste to znovu za několik minut.

Hlavičky kvóty a rate limitu

Existují dvě rodiny hlaviček a měří různé věci. X-Quota-* je měsíční kvóta vašeho tarifu: ta, která se vyčerpá s KEY_AUTH_004.

HlavičkaPopis
X-Quota-LimitVolání zahrnutá v tarifu za měsíc (např. 5000).
X-Quota-RemainingZbývající volání v tomto měsíci.
X-Quota-ResetDatum obnovení měsíční kvóty (ISO 8601, UTC).
X-Quota-TierNázev aktuální úrovně (free, basic, pro, business).

X-RateLimit-* je minutový nárazový limit vašeho klíče podle tarifu: Free 10, Developer 60, Startup 120 a Growth 300 požadavků každých 60 sekund. S měsíční kvótou nesouvisí.

HlavičkaPopis
X-RateLimit-LimitPovolené požadavky za minutu s vaším klíčem (podle tarifu).
X-RateLimit-RemainingZbývající požadavky v aktuální minutě.
X-RateLimit-ResetSekundy do obnovení jednominutového okna.

Návody podle případu použití

Čtyři skutečné úlohy vyřešené voláním API. Každý krok obsahuje volání v cURL, v SDK pro JavaScript a v SDK pro Python a skutečnou odpověď, kterou vrátilo produkční prostředí.

Prověření nemovitosti před koupí

Od adresy v inzerátu k tomu, co uvádí katastr a co vidí satelit: jaká finca to je, co obsahuje, zda leží v chráněném území a zda se terén pohybuje. Každý krok používá jinou parcelu, aby ukázal případ s daty; ve vašem procesu jde od začátku do konce o stejnou referenci.

Země: ES

1. Od adresy k nemovitosti (finca)

Adresa ve volném textu vrací kandidáty seřazené podle spolehlivosti (0 až 1) se 14znakovou referencí, účelem užívání, počtem bytů a rokem. Od hodnoty 0,75 výše se shoduje číslo i obec. Stojí 1 jednotku kvóty, jen pokud jsou nalezeni kandidáti.

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"

Skutečná odpověď

{
  "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 obsahuje: byty, nebytové prostory a příslušenství

Se 14znakovou referencí získáte všechny jednotky, které finca obsahuje, s účelem užívání, plochou, podlažím, číslem dveří a koeficientem podílu. Slouží k ověření, že plocha a účel užívání v inzerátu odpovídají katastru. Stojí 1 jednotku kvóty za každou vrácenou jednotku.

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

Skutečná odpověď

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. Chráněná území: Natura 2000 a parky

Před koupí venkovského pozemku je dobré vědět, zda leží v chráněném území: omezuje to, co se na něm smí stavět nebo pěstovat. /terrain protne obrys parcely s územími Natura 2000 a národními chráněnými územími (CDDA) a uvede, jaká část parcely leží uvnitř. Skutečný příklad: parcela celá uvnitř národního parku Monfragüe.

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

Skutečná odpověď, zkrácená

{
  "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. Zda terén klesá

/ground-motion udává vertikální rychlost pohybu terénu nad parcelou měřenou radarem Sentinel-1 (Copernicus EGMS, 2020-2024). Skutečný příklad: parcela v Murcii, která klesá o 40,9 mm ročně, třída severe_subsidence. Když satelit nemá odrazné body (otevřená pole, les, voda), odpoví status no_data místo odhadování.

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

Skutečná odpověď

{
  "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"
  }
}

Portfolio správce nemovitostí

Importujte každou spravovanou nemovitost (finca) i s jejími jednotkami a každý měsíc ji znovu zkontrolujte, aniž byste dvakrát platili za to, co se nezměnilo.

Země: ES

1. První import

Projděte seznam svých 14znakových referencí. Každá stránka obsahuje až 200 jednotek a nextCursor; SDK kurzor procházejí za vás. ETag každé stránky si uložte spolu s danou nemovitostí (finca). Zbývající kvótu najdete v hlavičce X-Quota-Remaining a v lastQuota v 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"

Skutečná odpověď

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. Měsíční kontrola s ETag

Zopakujte volání s If-None-Match a uloženým ETag. Pokud se finca nezměnila, odpověď je 304 Not Modified a nic nestojí. V SDK předejte předchozí výsledek: changed uvádí, zda se něco změnilo. Dodržujte minutový limit svého tarifu (Free 10, Developer 60, Startup 120, Growth 300): SDK při odpovědi 429 opakují požadavek samy.

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
Úplný návod k importu společenství vlastníků jednotek

Solární proveditelnost parcely

Odhadovaná výroba z PVGIS, úspora, návratnost a u pozemních instalací skutečný sklon a orientace terénu. /solar pokrývá Španělsko (včetně Baskicka a Navarry), Portugalsko, Francii, Itálii a Německo; jinde odpovídá 422 CNV_COVERAGE.

Země: ESPVNAPTFRITDE

1. Výroba a ekonomika instalace

Odpověď obsahuje instalovatelný výkon v kWp, kWh za rok, úsporu, dobu návratnosti, zamezené emise CO2 a blok economics s vlastní spotřebou, přebytky, čistým příjmem, dobou návratnosti a IRR. Když solární data chybí, odpoví disponible false a nic nestojí.

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

Skutečná odpověď

{
  "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. Sklon a orientace terénu

Pro pozemní instalaci /terrain udává průměrný a maximální sklon s jeho třídou a převládající orientaci nad skutečným obrysem (Copernicus DEM GLO-30, 30 m). Skutečný příklad: velmi strmý svah orientovaný na sever, málo vhodný pro pozemní panely.

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

Skutečná odpověď, zkrácená

{
  "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"
      }
    }
  }
}

Riziko parcely pro pojišťovnu

Tři signály pro každou parcelu z otevřených evropských zdrojů: pokles terénu (EGMS), reliéf a chráněná území (Copernicus DEM, EEA) a klima (ERA5-Land). Funguje v celém pokrytí EGMS (EEA-39) všude, kde máme obrys; mimo Španělsko, Portugalsko, Francii, Itálii a Německo předejte také lat a lng.

Země: EEA-39

1. Pokles a zrychlení

class a worst_class shrnují pohyb (stable, slow_subsidence, notable_subsidence, severe_subsidence a jejich protějšky pro zdvih). vertical obsahuje průměr, nejrychlejší pokles, zrychlení a kumulativní posun za každý rok. Každá odpověď obsahuje atribuci Copernicus, kterou musíte zobrazit.

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

Skutečná odpověď

{
  "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. Reliéf, chráněná území a klima

Totéž volání /terrain vrací reliéf, chráněná území a blok climate s klimatickými normály ERA5-Land: průměrnou teplotu, roční srážky, počet mrazových dnů a dnů nad 35 stupňů za referenční období ve srovnání s posledními lety. Mřížka ERA5-Land se načítá: dokud načítání neskončí, climate odpovídá status unavailable a zbytek odpovědi přichází jako obvykle. Příklad používá belgickou referenci, která obsahuje lomítko a posílá se zakódovaná 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 během načítání mřížky 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 a MCP

Oficiální klienti pro JavaScript/TypeScript a Python a server MCP, díky kterému může asistent AI vyhledávat parcely s vaším klíčem. Všechny tři čtou klíč z proměnné prostředí CATASTROGPS_API_KEY.

JavaScript a 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)

Pro endpoint bez vlastní metody v SDK, například /terrain nebo /ground-motion, použijte client.request: podepíše volání, při odpovědích 429 a 5xx požadavek opakuje a aktualizuje kvótu stejně jako ostatní metody.

Připojení serveru MCP k asistentovi

Server catastro-gps-mcp (npm) zpřístupňuje API jako nástroje pro Claude, Cursor, VS Code a libovolného klienta MCP. Každé volání nástroje je jedno volání API, které se odečte z vaší kvóty.

Claude Desktop: přidejte toto do claude_desktop_config.json a restartujte aplikaci.

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

Claude Code: jeden příkaz v terminálu.

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

Cursor, Windsurf, VS Code a další klienti MCP: stejný příkaz s CATASTROGPS_API_KEY v prostředí.

npx -y catastro-gps-mcp

Nástroje

get_parcelsearch_addressget_boundariesget_solar_potentialget_terrainget_agricultureget_market_dataget_investment_scoreget_value_historycompare_parcels

Zkuste se zeptat

  • 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.

Španělsko (ES)

Španělský katastr — 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"

Příklad odpovědi

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žné chyby

KódHTTPPopis
VALIDATION_ERROR400Reference nemá pro danou zemi platný formát.
NOT_FOUND404No building entrance with a cadastral reference matches the address.
KEY_AUTH_004429Vyčerpaná měsíční kvóta API klíče (viz hlavičky X-Quota-*).
SERVICE_UNAVAILABLE503CartoCiudad is not answering. Retry after Retry-After.
GET/api/catastro/:refcat

Získá údaje o parcele podle katastrální reference (14 nebo 20 znaků).

Parametry

:refcatstringKatastrální reference (např. 9872023VH5797S0001WX)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX"

Příklad odpovědi

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žné chyby

KódHTTPPopis
VALIDATION_ERROR400Reference nemá pro danou zemi platný formát.
NOT_FOUND404Reference nenalezena. Nepodporovaná hodnota ?country se považuje za Španělsko (ES) a obvykle vrátí NOT_FOUND; použijte ES/PT/FR/IT/DE/PV/NA. U foralních katastrů (NA, PV) pole message doplní nápovědu k formátu.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429KEY_RATE_002: minutový nárazový limit vašeho klíče. RATE_LIMIT_EXCEEDED: příliš mnoho požadavků ze stejné IP. DAILY_LIMIT_REACHED: denní limit bezplatných vyhledávání bez API klíče.
KEY_AUTH_004429Vyčerpaná měsíční kvóta API klíče (viz hlavičky X-Quota-*).
SERVICE_UNAVAILABLE503Oficiální katastrální služba země je nedostupná nebo v údržbě. Zkuste to znovu.
GET/api/catastro/:refcat14/units

Všechny jednotky španělského pozemku podle 14místné reference v jediném volání (až 200 na stránku, s kurzorem). Každá jednotka obsahuje užití, plochu, spoluvlastnický podíl, rok a schodiště/patro/dveře. Stojí 1 jednotku kvóty za každých 50 vrácených jednotek (minimálně 1). Vyžaduje API klíč nebo přihlášení. Zdroj: Dirección General del Catastro.

Parametry

:refcat14string14místná katastrální reference pozemku (např. 0745901TG4304N)
cursorstringVolitelné. nextCursor předchozí stránky, když je truncated true.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/0745901TG4304N/units"

Příklad odpovědi

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žné chyby

KódHTTPPopis
VALIDATION_ERROR400Kurzor není 20místná reference tohoto pozemku.
UNAUTHORIZED / UNT_001401Chybí API klíč organizace i přihlášení.
NOT_FOUND404Pozemek není v naší kopii Catastro ani v Catastro.
CNV_COVERAGE422The finca is in the Basque Country or Navarra: their foral cadastre is not served per finca.
KEY_AUTH_004429Vyčerpaná měsíční kvóta API klíče (viz hlavičky X-Quota-*).
SERVICE_UNAVAILABLE503Oficiální katastrální služba země je nedostupná nebo v údržbě. Zkuste to znovu.
GET/api/catastro/:refcat/terrain

Reliéf počítaný nad polygonem parcely z Copernicus DEM GLO-30 (30 m): průměrná, minimální a maximální výška, průměrný a maximální sklon s třídou a rozložením, podíl plochy se sklonem > 10 % a převládající orientace. K tomu průnik se soustavou Natura 2000 (EEA, end 2024) a národními chráněnými územími (CDDA 2025): název, kód, typ (SPA = PO, SCI = EVL) a podíl parcely v každém území. Každý blok uvádí zdroj a licenci. status = ok, no_data (bez pokrytí) nebo unavailable (dočasná chyba, zkuste znovu). Stejná parcela, stejná jednotka kvóty jako dotaz.

Parametry

:refcatstringKatastrální reference
countrystringVolitelné. ES, PV, NA, PT, FR, IT, DE; odvodí se z reference, pokud chybí.
lat, lngnumberJen pro ostatní země s vlastní geometrií: přibližná poloha parcely pro nalezení jejího obrysu.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/10194A00110004/terrain?country=ES"

Příklad odpovědi

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žné chyby

KódHTTPPopis
UNAUTHORIZED401Chybí API klíč organizace i přihlášení.
NOT_FOUND404Parcela neexistuje nebo mimo sedm hlavních zemí v této poloze není žádný obrys.
KEY_AUTH_004429Vyčerpaná měsíční kvóta API klíče (viz hlavičky X-Quota-*).
TRN_040503Oficiální katastrální služba země je nedostupná nebo v údržbě. Zkuste to znovu.
GET/api/catastro/:refcat/ground-motion

Svislá a východo-západní rychlost terénu nad polygonem pozemku z European Ground Motion Service programu Copernicus (EGMS L3 Ortho, radar Sentinel-1, mřížka 100 m, 2020-2024): průměr, nejsilnější pokles, nejsilnější zdvih, třída, buňky s údajem a průměrný posun každého roku. Bez odražečů (pole, les, voda) odpoví status = no_data s reason = no_reflectors místo odhadu. Celé pokrytí EGMS (EEA-39). Obsahuje zdroj, licenci a povinné uvedení autorství. Stejný pozemek, stejná jednotka kvóty jako vyhledání.

Parametry

:refcatstringKatastrální reference
countrystringVolitelné. ES, PV, NA, PT, FR, IT, DE; odvodí se z reference, pokud chybí.
lat, lngnumberJen pro ostatní země s vlastní geometrií: přibližná poloha parcely pro nalezení jejího obrysu.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/30024A16000286/ground-motion?country=ES"

Příklad odpovědi

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žné chyby

KódHTTPPopis
UNAUTHORIZED401Chybí API klíč organizace i přihlášení.
NOT_FOUND404Parcela neexistuje nebo mimo sedm hlavních zemí v této poloze není žádný obrys.
KEY_AUTH_004429Vyčerpaná měsíční kvóta API klíče (viz hlavičky X-Quota-*).
GMV_040503Oficiální katastrální služba země je nedostupná nebo v údržbě. Zkuste to znovu.
POST/api/search/coordinates

Reverzní geokódování: najde katastrální parcelu na zadaných GPS souřadnicích.

Parametry

latitudenumberZeměpisná šířka (WGS84)
longitudenumberZeměpisná délka (WGS84)
countrystringKód země (volitelný: rozpozná se z reference)
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"

Příklad odpovědi

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žné chyby

KódHTTPPopis
VALIDATION_ERROR400Souřadnice mimo hranice zadané nebo rozpoznané země, případně chybějící či chybně zapsané lat/lng.
NOT_FOUND404Na těchto souřadnicích není žádná parcela.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429KEY_RATE_002: minutový nárazový limit vašeho klíče. RATE_LIMIT_EXCEEDED: příliš mnoho požadavků ze stejné IP. DAILY_LIMIT_REACHED: denní limit bezplatných vyhledávání bez API klíče.
SERVICE_UNAVAILABLE503Katastrální služba je dočasně nedostupná.
POST/api/search/address/parse

Vyhledá katastrální parcelu podle poštovní adresy.

Parametry

direccionstringAdresa volným textem (pouze Španělsko). Doporučený formát: «Ulice, Číslo, Obec» — např. «Calle Mallorca, 213, Barcelona». Číslo domu může být i připojeno k ulici («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"

Příklad odpovědi

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žné chyby

KódHTTPPopis
VALIDATION_ERROR400Neplatné tělo požadavku (chybějící pole nebo chybný JSON).
NOT_FOUND404Adresa nenalezena (ulice, obec nebo číslo neexistuje nebo nemá katastrální shodu). Vyhledávání podle adresy je dostupné pouze ve Španělsku.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429KEY_RATE_002: minutový nárazový limit vašeho klíče. RATE_LIMIT_EXCEEDED: příliš mnoho požadavků ze stejné IP. DAILY_LIMIT_REACHED: denní limit bezplatných vyhledávání bez API klíče.

Baskicko (PV)

Foralní katastry — Araba/Álava, Bizkaia a Gipuzkoa (INSPIRE WFS)

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

Vyhledání parcely ve třech foralních územích. Vyžaduje country=PV: jejich parcely mají vlastní katastr a nejsou v centrálním Catastru.

Parametry

:refcatstringForalní reference. Bizkaia s tečkami (48.020.1611.02001); Álava a Gipuzkoa číslicemi (64010007, 8594149).
countrystringPovinné: PV.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/48.020.1611.02001?country=PV"

Příklad odpovědi

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 */ ]
  }
}

S country=ES (nesprávně)

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

Portugalsko (PT)

Portugalský katastr — Direção-Geral do Território

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

Získá údaje o portugalské parcele podle katastrální reference.

Parametry

:refcatstringPortugalská katastrální reference (např. AAA000587359). Pokrytí je částečné (~30 %); oblasti jako Lisabon a Porto zatím DGT nedigitalizovalo.
countrystringPovinné: PT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/AAA000587359?country=PT"

Příklad odpovědi

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 */ ]
  }
}

Francie (FR)

Francouzský katastr — Cadastre / Géoplateforme

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

Převede francouzskou adresu na katastrální parcelu (14místné IDU) pod ní: geokóduje přes Base Adresse Nationale a v tom bodě se dotáže oficiálního katastru. Kandidáti seřazení podle spolehlivosti (0 až 1). Stojí 1 jednotku kvóty, jen když vrátí kandidáty.

Parametry

qstringFree-text address: street and number, municipality (and postcode if you have it).
countrystringPovinné: 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

Příklad odpovědi

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žné chyby

KódHTTPPopis
VALIDATION_ERROR400Reference nemá pro danou zemi platný formát.
NOT_FOUND404No building entrance with a cadastral reference matches the address.
CNV_COVERAGE422Země nemá hledání podle adresy (SE, HR nebo země bez pokrytí)
KEY_AUTH_004429Vyčerpaná měsíční kvóta API klíče (viz hlavičky X-Quota-*).
SERVICE_UNAVAILABLE503CartoCiudad is not answering. Retry after Retry-After.
GET/api/catastro/:refcat?country=FR

Získá údaje o francouzské parcele podle katastrální reference.

Parametry

:refcatstringFrancouzská katastrální reference (např. 75104000AE0003)
countrystringPovinné: FR.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/75104000AE0003?country=FR"

Příklad odpovědi

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 */ ]
  }
}

Itálie (IT)

Italský katastr — Agenzia delle Entrate

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

Převede italskou adresu na katastrální parcelu (particella) pod ní: geokóduje přes OpenStreetMap (Photon, záložně Nominatim) a v tom bodě se dotáže Agenzia delle Entrate. Nikdy nevrací ulice ani vody (STRADA, ACQUA): pokud bod padne na ulici, vezme nejbližší parcelu. Stojí 1 jednotku kvóty, jen když vrátí kandidáty.

Parametry

qstringFree-text address: street and number, municipality (and postcode if you have it).
countrystringPovinné: 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

Příklad odpovědi

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žné chyby

KódHTTPPopis
VALIDATION_ERROR400Reference nemá pro danou zemi platný formát.
NOT_FOUND404No building entrance with a cadastral reference matches the address.
CNV_COVERAGE422Země nemá hledání podle adresy (SE, HR nebo země bez pokrytí)
KEY_AUTH_004429Vyčerpaná měsíční kvóta API klíče (viz hlavičky X-Quota-*).
SERVICE_UNAVAILABLE503CartoCiudad is not answering. Retry after Retry-After.
GET/api/catastro/:refcat?country=IT

Získá údaje o italské parcele podle katastrální reference.

Parametry

:refcatstringItalská katastrální reference (foglio/particella, např. H501A048100.A)
countrystringPovinné: IT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/H501A048100.A?country=IT"

Příklad odpovědi

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 */ ]
  }
}

Německo (DE)

Německý katastr — ALKIS (8 spolkových zemí)

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

Získá údaje o německé parcele podle katastrální reference.

Parametry

:refcatstringNěmecká katastrální reference (Flurstückskennzeichen)
countrystringPovinné: DE.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/05495803101122?country=DE"

Příklad odpovědi

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 */ ]
  }
}

Rakousko (AT)

Rakouský katastr — BEV (Katastralgemeinde / Grundstück)

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

Vyhledání parcely v Rakousku. Vyžaduje country=AT. Reference má tvar KATASTRALGEMEINDE-GRUNDSTÜCK. Částečné pokrytí, rozšiřuje se.

Parametry

:refcatstringFormát Katastralgemeinde-Grundstück (např. 01004-1711).
countrystringPovinné: AT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/01004-1711?country=AT"

Příklad odpovědi

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 */ ]
  }
}

S country=ES (nesprávně)

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

Zbytek Evropy (adresa)

Hledání podle adresy funguje stejně ve 26 zemích: v Nizozemsku, Švýcarsku, Polsku, Česku, Estonsku, Dánsku a Flandrech s úředním registrem adres, jinde s OpenStreetMap. Parcela vždy pochází z úředního katastru dané země. Švédsko a Chorvatsko ho nemají.

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

Převede evropskou adresu na katastrální parcelu pod ní: geokóduje úředním registrem adres (PDOK v Nizozemsku) nebo OpenStreetMap a v tom bodě se dotáže úředního katastru země. Kandidáti seřazení podle jistoty (0 až 1). Stojí 1 jednotku kvóty jen tehdy, když vrátí kandidáty.

Parametry

qstringFree-text address: street and number, municipality (and postcode if you have it).
countrystringPovinné: 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

Příklad odpovědi

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žné chyby

KódHTTPPopis
VALIDATION_ERROR400Reference nemá pro danou zemi platný formát.
NOT_FOUND404No building entrance with a cadastral reference matches the address.
CNV_COVERAGE422Země nemá hledání podle adresy (SE, HR nebo země bez pokrytí)
KEY_AUTH_004429Vyčerpaná měsíční kvóta API klíče (viz hlavičky X-Quota-*).
SERVICE_UNAVAILABLE503CartoCiudad is not answering. Retry after Retry-After.

Analýza parcel a exporty

Geometrie, solární potenciál, zemědělské údaje a exporty souborů (KML/GPX/PDF/DXF), dostupné s vaším API klíčem. Tržní údaje a investiční skóre zůstávají ve webu a mobilní aplikaci (Pro) a přes API se neposkytují.

GET/api/catastro/:refcat/polygon

Získá GeoJSON polygon parcely.

Parametry

:refcatstringKatastrální reference
countrystringKód země (parametr dotazu, výchozí: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon"

Příklad odpovědi

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

Měsíční kvóta vyčerpána

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

Získá údaje o solárním potenciálu (PVGIS) pro jakoukoli evropskou parcelu.

Parametry

:refcatstringKatastrální reference
countrystringKód země (parametr dotazu, výchozí: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar"

Příklad odpovědi

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
    }
  }
}

Parcela bez solárních údajů

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

Údaje o zemědělské půdě parcely (SIGPAC): hlavní plodina, využití pozemku, sklon, nadmořská výška a výměra. Pouze venkovské parcely — městské parcely vracejí "cultivo_principal": "urbano".

Parametry

:refcatstringKatastrální reference
countrystringKód země (parametr dotazu, výchozí: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/23058A00700036/agro"

Příklad odpovědi

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
      }
    }
  }
}

Měsíční kvóta vyčerpána

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

Exportuje údaje o parcele ve formátu KML (Google Earth).

Parametry

refcatstringKatastrální reference
countrystringKód země (volitelný: rozpozná se z reference)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kml

Příklad odpovědi

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

Exportuje údaje o parcele ve formátu GPX (GPS navigace).

Parametry

refcatstringKatastrální reference
countrystringKód země (volitelný: rozpozná se z reference)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpx

Příklad odpovědi

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>

Přehled změn

Co bylo tento týden v API vydáno, s číslem změny v repozitáři. Odpovědi zůstávají kompatibilní: žádné existující pole se nepřejmenovává.

  • Z adresy na parcelu ve 26 evropských zemích přes /api/search/address/candidates?country=XX: oficiální registr adres tam, kde existuje (Nizozemsko, Švýcarsko, Polsko, Česko, Estonsko, Dánsko, Flandry), a jinde OpenStreetMap, nejvýše 10 sekund na bod. Změny: #93, #94
  • Nový /api/catastro/:refcat/ground-motion: vertikální rychlost pohybu terénu a rychlost ve směru východ-západ z Copernicus EGMS 2020-2024 v celém rozsahu jeho pokrytí, včetně znovu zveřejněných dlaždic pro Nizozemsko, Belgii a Pyreneje. Změny: #80, #91
  • Blok climate v /terrain s klimatickými normály ERA5-Land. Mřížka se načítá: dokud načítání neskončí, odpovídá status unavailable. Změny: #78
  • Mimo Španělsko: availableFields uvádí, co která odpověď obsahuje, prázdné odpovědi nic nestojí, /solar /agro /score odpovídají 422 CNV_COVERAGE tam, kde nejsou data, nejednoznačné číslice odpovídají 300 CNV_AMBIGUOUS, reference se vrací celá a Belgie vrací zeměpisnou šířku a délku ve správném pořadí. Změny: #76
  • S klíčem API přicházejí texty chyb v angličtině; pole code se nemění. Změny: #77
  • Z adresy na parcelu ve Francii (Base Adresse Nationale) a v Itálii; Německo a Rakousko podle souřadnic s plochou a obrysem; Kypr za méně než sekundu; /terrain a /ground-motion najdou obrys ve zbytku Evropy. Změny: #83, #84, #85, #86
  • POST /api/search/coordinates směruje všechny země stejně jako GET. Změny: #79
  • /terrain a /ground-motion dekódují reference s lomítkem (Belgie, Česko, Polsko): pole refcat se už nevrací jako %2F. Změny: #95

  • Nový /api/catastro/:refcat/terrain: reliéf nad obrysem (Copernicus DEM GLO-30) a průnik s územími Natura 2000 a národními chráněnými územími (CDDA), bez opakování lokalit, které jsou v obou seznamech. Změny: #67, #69, #70
  • Nový /api/catastro/:refcat14/units: všechny jednotky španělské nemovitosti (finca), 200 na stránku s kurzorem, za 1 jednotku kvóty za každou vrácenou jednotku a nikdy více, než vám zbývá; Baskicko a Navarra odpovídají 422 CNV_COVERAGE. Změny: #53, #55, #73, #74, #75
  • Z adresy na nemovitost (finca) ve Španělsku s kandidáty z CartoCiudad, ETag a bezplatnými reimporty s odpovědí 304 a specifikace OpenAPI 3.1 na /api/openapi.json. Změny: #72
  • Hlavičky X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset a X-Quota-Tier s měsíční kvótou a minutový limit pro každý klíč podle tarifu. Změny: #52, #58