catastrogps

Official Python client for the Catastro GPS API: cadastral parcels in 29 European countries plus the Basque Country and Navarre (31 country and region codes) with one API key.

• Look up a parcel by its official cadastral reference or by coordinates, with the country detected for you.
• Turn a Spanish postal address in free text into a cadastral reference.
• Get the parcel outline (GeoJSON or a [lat, lng] ring), and KML / GPX / DXF exports.
• Solar (PVGIS) and agricultural context for parcels in Spain, Portugal, France, Italy and Germany.
• One dependency (httpx), typed, Python 3.9+.

Free tier: 250 calls a month, forever. Failed lookups are not charged. Get a key at catastrogps.es/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:
    ...

Examples

match = client.parcels.find_by_address("Calle Mallorca 213, Barcelona")
match["referenciaCatastral"]

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

foral = client.parcels.get("<Navarre reference>", country="NA")

outline = client.parcels.geometry("9872023VH5797S", country="ES")
outline.get("geojson")

solar = client.parcels.solar("9872023VH5797S0001WX")
solar["kwh_year"]

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

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

client.last_quota

Responses are the API's data object as a dict, with the field names the API uses (refCatastral, municipio, superficieParcela…). See the API reference.

Errors

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

from catastrogps import AmbiguousReferenceError, CoverageError, NotFoundError, QuotaExceededError

try:
    client.parcels.get("05102200100005")
except AmbiguousReferenceError as error:
    first = error.candidates[0]["country"]
    client.parcels.get("05102200100005", country=first)
except (NotFoundError, CoverageError) as error:
    print(error.message)
except QuotaExceededError:
    print("Monthly quota used up")

Also available: AuthenticationError, ValidationError, RateLimitError, ServiceUnavailableError, ServerError, TimeoutError, NetworkError.

Timeouts, network errors, 429 rate limits and 502/503/504 are retried up to max_retries times (default 2) with exponential backoff. An exhausted monthly quota is never retried. Each attempt that reaches the API counts as a call.

Options

Coverage

Geometry is available wherever a reference works. Solar and agriculture: ES, PV, NA, PT, FR, IT, DE. Data comes live from each official source, so availability follows theirs.

Pricing

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

License

MIT