catastrogps

Official Python client for the Catastro GPS API: cadastral parcels from 26 European cadastres plus the foral cadastres of the Basque Country and Navarre with one API key.

• Look up a parcel by its official cadastral reference or by coordinates, with the country detected for you.
• Turn a postal address into parcels in Spain and 26 more countries, ranked by confidence.
• Import every unit of a Spanish building (dwellings, shops, garages) with paging and free 304 refreshes.
• Get the parcel outline (GeoJSON or a [lat, lng] ring), and KML / GPX / DXF exports.
• Relief, Natura 2000 and climate (Copernicus DEM, EEA, ERA5-Land) and ground motion (Copernicus EGMS, mm/year) for any covered country.
• Solar, agriculture, market, score, value history and comparison for Spain, Portugal, France, Italy and Germany.
• Quota, prepaid balance and per-minute limit of every response, typed exceptions for every API code.
• Two small dependencies (httpx, typing_extensions), typed, Python 3.9+.

Free tier: 250 calls a month, forever. Failed lookups are not charged. Get a key at parcelgps.com/developers.

Install

pip install catastrogps

Quick start

from catastrogps import CatastroGPS

client = CatastroGPS("pk_live_your_key_here")

parcel = client.parcels.get("9872023VH5797S0001WX")
print(parcel["municipio"], parcel.get("superficieParcela"), parcel["latitud"], parcel["longitud"])

CatastroGPS() with no arguments reads CATASTROGPS_API_KEY from the environment. Use it as a context manager to close the connection pool:

with CatastroGPS() as client:
    ...

Methods

Examples

in_warsaw = client.parcels.at_point(52.2297, 21.0122)
in_warsaw["referenciaCatastral"], in_warsaw.get("pais")

found = client.search_address_candidates("Damrak 1, 1012 LG Amsterdam", country="NL")
found["candidatos"][0]["refCatastral"], found["candidatos"][0]["confianza"]

terrain = client.parcels.terrain("10194A00110004")
terrain["relief"]["slope"]["class"], terrain["protected_areas"]["natura2000"], terrain.get("climate")

brussels = client.parcels.terrain("21004C0123/00", country="BE", lat=50.848139, lng=4.353613)

motion = client.parcels.ground_motion("0745901TG4304N0002KH")
motion["status"], motion.get("ground_motion", {}).get("vertical", {}).get("mean_mm_year")

comparison = client.parcels.compare([("9872023VH5797S0001WX", "ES"), ("750560000AB0001", "FR")])

kml_bytes = client.export.file("9872023VH5797S0001WX", "kml")

guess = client.resolve("05102200100005")
guess["candidates"]

terrain and ground_motion carry a source.attribution string that must be shown next to the data. A ground motion answer with status: "no_data" and reason: "no_reflectors" means the satellite had nothing stable to measure (fields, forest, water): there is no figure, not a zero.

Responses are the API's data object as a dict, with the field names the API uses (refCatastral, municipio, superficieParcela…). See the API reference and the OpenAPI spec at https://api.parcelgps.com/api/openapi.json.

Import a building (comunidad de propietarios, Spain)

Address, then finca (14-character reference), then every unit with use, area, participation coefficient, stair, floor and door.

found = client.search_address_candidates("Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas")
finca = found["candidatos"][0]

comunidad = client.get_units(finca["refCatastral"], country=finca["pais"])
comunidad["totalUnidadesFinca"]
for u in comunidad["unidades"]:
    print(u["refCatastral"], u["uso"], u["superficie"], u.get("participacion"), u["escalera"], u["planta"], u["puerta"])
comunidad["dataSource"], comunidad["attribution"]

refreshed = client.get_units(finca["refCatastral"], previous=comunidad)
refreshed["changed"]

• get_units follows nextCursor for you (up to 200 units per page). iter_unit_pages(ref) yields page by page.
• Cost: one quota unit per unit served in each page, minimum one per page; a page is cut to the quota you have left. Pass the previous result as previous= to re-import: unchanged pages come back as 304 Not Modified, cost nothing and are reused; changed tells you if anything moved.
• Basque Country and Navarre (country="PV" or "NA") are served from our copy of each foral cadastre: pass the foral reference of any unit or the finca key in refCatastral. The foral open data carry no participation coefficient.
• Organisations with a per-finca cap agreed by contract (Startup and Growth) pay at most that cap per finca and period: see client.last_quota["finca_cap"] ({"cap", "used"}), also in each page's quota.

Quota, prepaid balance and limits

client.last_quota is read from the headers of the last response; conditional_request also returns the quota of that exact response.

When the monthly quota is spent and there is no prepaid balance left, the API answers 429 KEY_AUTH_004 (never 402): the client raises QuotaExceededError with the quota of that response, and prepaid_balance_empty is true when your organisation has the prepaid overage on (top up at https://parcelgps.com/app/developer). Only 2xx responses spend quota; 300, 304, 4xx and 5xx are free, and so are 2xx answers without data.

Errors

Every error is a CatastroGPSError with status, code and details:

from catastrogps import (
    AmbiguousReferenceError,
    CoverageError,
    NotFoundError,
    PlaceNameError,
    QuotaExceededError,
)

try:
    client.parcels.get("05102200100005")
except AmbiguousReferenceError as error:
    client.parcels.get("05102200100005", country=error.candidates[0]["country"])
except PlaceNameError as error:
    print("A place name, not a reference", error.location)
except CoverageError as error:
    print(error.country, error.feature, error.supported_countries)
except NotFoundError as error:
    print(error.message)
except QuotaExceededError as error:
    print("Quota spent", error.quota, error.prepaid_balance_empty)

Timeouts, network errors, per-minute 429s and 502/503/504 are retried up to max_retries times (default 2) with exponential backoff, waiting Retry-After when the API sends it (up to 60 s). An exhausted monthly quota is never retried.

Options

Coverage

Measured against production on 1 October 2026. 26 European cadastres plus the Basque Country and Navarre; Croatia, Sweden and the United Kingdom are partial sources, listed for honesty.

Not covered: Hungary, Romania and the rest (CoverageError). Terrain and ground motion work wherever a parcel outline exists, with lat/lng outside the seven analysis countries. Data comes from each official source, so availability follows theirs.

Pricing

Overage prices are net (VAT apart) and are charged from a prepaid balance you top up in the portal; with the balance at zero the API answers 429, never debt.

The same key works with the JavaScript SDK (npm install catastrogps), the Go SDK and the MCP server for AI agents (catastro-gps-mcp).

License

MIT