Metadata-Version: 2.5
Name: catastrogps
Version: 1.0.0
Summary: Official Python client for the Catastro GPS API: cadastral parcels in 31 European countries and regions by reference, coordinates or Spanish address
Project-URL: Homepage, https://www.catastrogps.es/developers
Project-URL: Documentation, https://www.catastrogps.es/developers
Project-URL: Support, https://www.catastrogps.es/developers
Author-email: The Hidden Panda <soporte@catastrogps.es>
License-Expression: MIT
License-File: LICENSE
Keywords: cadastral,cadastre,cadastre-api,catastro,europe,france,geojson,germany,gis,italy,land-registry,parcel,portugal,real-estate,spain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.25
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# catastrogps

Official Python client for the [Catastro GPS API](https://www.catastrogps.es/developers): 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](https://www.catastrogps.es/developers).

## Install

```bash
pip install catastrogps
```

## Quick start

```python
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:

```python
with CatastroGPS() as client:
    ...
```

## Examples

```python
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](https://www.catastrogps.es/developers).

## Errors

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

```python
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

| Argument | Default | |
|----------|---------|---|
| `api_key` | `CATASTROGPS_API_KEY` | Required |
| `base_url` | `https://api.catastrogps.es` | |
| `timeout` | `30.0` seconds | Official cadastres can be slow |
| `max_retries` | `2` | |
| `http_client` | new `httpx.Client` | Bring your own (proxies, tests with `httpx.MockTransport`) |

## Coverage

| Code | Country / region | Reference | Coordinates | Notes |
|------|------------------|:---:|:---:|-------|
| `ES` | Spain | ✅ | ✅ | Free-text address search |
| `PV` · `NA` | Basque Country · Navarre | ✅ | ✅ | Foral cadastres |
| `PT` | Portugal | Partial | ✅ | Digital cadastre is partial |
| `FR` · `IT` | France · Italy | ✅ | ✅ | |
| `DE` | Germany | Partial | Partial | All Länder except Bavaria |
| `AT` `CH` `LI` `BE` `NL` `LU` | Austria, Switzerland, Liechtenstein, Belgium, Netherlands, Luxembourg | ✅ | ✅ | |
| `PL` `CZ` `SK` `SI` `HR` `BG` `GR` `CY` | Poland, Czechia, Slovakia, Slovenia, Croatia, Bulgaria, Greece, Cyprus | ✅ | ✅ | |
| `DK` `NO` `FI` `IS` `EE` `LV` `LT` `IE` | Denmark, Norway, Finland, Iceland, Estonia, Latvia, Lithuania, Ireland | ✅ | ✅ | |
| `SE` | Sweden | ✅ | ✅ | Agricultural blocks, not property units |
| `UK` | United Kingdom | — | Scotland | England, Wales and Northern Ireland not yet |

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

| Plan | Price | Calls / month |
|------|-------|---------------|
| Free | €0, forever | 100 |
| Developer | €19 / month | 5,000 |
| Startup | €49 / month | 15,000 |
| Growth | €99 / month | 50,000 |

The same key works with the JavaScript SDK (`npm install catastrogps`) and the MCP server for AI agents ([catastro-gps-mcp](https://www.npmjs.com/package/catastro-gps-mcp)).

## License

MIT
