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

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.

Official documents (prepaid wallet)

Order a Spanish nota simple, an Italian visura or a German Flurstückskarte from code. The price comes from the catalogue and is charged to your organization's wallet; if the document cannot be issued the money goes back to the wallet by itself. Top up once at https://www.catastrogps.es/app/developer or with wallet.top_up.

catalog = client.documents.catalog(country="IT")
wallet = client.wallet.get()

placed = client.documents.order(
    country="IT", product="visura", parcel_ref="H501_1234.56", idempotency_key="my-order-000001"
)

status = client.documents.get(placed["order"]["id"])
if status["status"] == "ready":
    pdf = client.documents.file(status["id"])

The same idempotency_key never charges twice (the SDK generates one per call and keeps it across retries). InsufficientBalanceError carries balance_cents and required_cents. Test keys cannot order. Subscribe a webhook to document.ready and document.failed to skip polling.

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