catastrogps 1.2.1 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # catastrogps
 
-Official JavaScript and TypeScript client for the [Catastro GPS API](https://www.catastrogps.es/developers): cadastral parcels from **29 European countries (31 official cadastres, including the Basque Country and Navarre)**, with one API key.
+Official JavaScript and TypeScript client for the [Catastro GPS API](https://www.catastrogps.es/developers): cadastral parcels from **29 European countries (including the Basque Country and Navarre foral cadastres)**, with one API key: by cadastral reference in 27, by coordinates in all 29.
 
 - 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.
@@ -27,7 +27,7 @@ import { CatastroGPS } from 'catastrogps';
 const client = new CatastroGPS({ apiKey: process.env.CATASTROGPS_API_KEY });
 
 const parcel = await client.parcels.get('9872023VH5797S0001WX');
-console.log(parcel.municipio, parcel.superficieParcela, parcel.latitud, parcel.longitud);
+console.log(parcel.municipality, parcel.parcelArea, parcel.latitude, parcel.longitude);
 ```
 
 `new CatastroGPS()` with no arguments reads `CATASTROGPS_API_KEY` from the environment.
@@ -36,42 +36,46 @@ console.log(parcel.municipio, parcel.superficieParcela, parcel.latitud, parcel.l
 
 | Method | Endpoint | Countries |
 |--------|----------|-----------|
-| `parcels.get(ref, { country })` | `GET /api/catastro/{ref}` | All references (see coverage) |
-| `parcels.atPoint({ lat, lng, country })` | `GET /api/search/coordinates` | All, including HR, SE and UK (Scotland) |
-| `searchAddressCandidates(q \| { q, street, number, municipality, postcode, country, limit })` | `GET /api/search/address/candidates` | Spain (with Basque Country and Navarre) and 26 more; not SE or HR |
-| `parcels.findByAddress(text)` | `POST /api/search/address/parse` | Spain, central Catastro, live (prefer the candidates search) |
-| `getUnits(ref14, { country, previous })`, `iterUnitPages` | `GET /api/catastro/{ref14}/units` | `ES`, `PV`, `NA` |
-| `parcels.geometry(ref, { country })` | `GET /api/catastro/{ref}/polygon` | All but UK |
-| `parcels.terrain(ref, { country, lat, lng })` | `GET /api/catastro/{ref}/terrain` | All; `lat`/`lng` required outside ES, PV, NA, PT, FR, IT, DE |
-| `parcels.groundMotion(ref, { country, lat, lng })` | `GET /api/catastro/{ref}/ground-motion` | Same as terrain, inside EGMS coverage |
-| `parcels.solar`, `parcels.agriculture`, `parcels.score` | `/solar`, `/agro`, `/score` | ES, PV, NA, PT, FR, IT, DE |
-| `parcels.market(ref, { country })` | `/market` | Figures in FR, IT and DE (NRW); a note without figures elsewhere |
+| `parcels.get(ref, { country, lang })` | `GET /v1/parcels/{ref}` | All references (see coverage); `subparcelCount` and `cropSummary` where there are crops |
+| `parcels.subparcels(ref, { country, lang })` | `GET /v1/parcels/{ref}/subparcels` | ES (with Bizkaia, Álava, Navarre, Gipuzkoa), AT, EE, GR. 1 unit; 0 when there are none; `503 SUB_001` is not charged |
+| `parcels.neighbors(ref, { country })` | `GET /v1/parcels/{ref}/neighbors` | Spain from the cadastre; elsewhere from our own copy (`supported: false`, free, when not) |
+| `parcels.atPoint({ lat, lng, country })` | `GET /v1/search/coordinates` | All, including HR, SE and UK (Scotland) |
+| `searchAddressCandidates(q \| { q, street, number, municipality, postcode, country, limit })` | `GET /v1/search/address/candidates` | Spain (with Basque Country and Navarre) and 26 more; not SE or HR |
+| `parcels.findByAddress(text)` | `POST /v1/search/address/parse` | Spain, central Catastro, live (prefer the candidates search) |
+| `getUnits(ref14, { country, previous })`, `iterUnitPages` | `GET /v1/parcels/{ref14}/units` | `ES`, `PV`, `NA` |
+| `parcels.geometry(ref, { country })` | `GET /v1/parcels/{ref}/polygon` | All but UK |
+| `parcels.terrain(ref, { country, lat, lng })` | `GET /v1/parcels/{ref}/terrain` | All; `lat`/`lng` required outside ES, PV, NA, PT, FR, IT, DE |
+| `parcels.groundMotion(ref, { country, lat, lng })` | `GET /v1/parcels/{ref}/ground-motion` | Same as terrain, inside EGMS coverage |
+| `parcels.solar`, `parcels.agriculture`, `parcels.score` | `/solar`, `/agriculture`, `/score` | ES, PV, NA, PT, FR, IT, DE |
+| `parcels.market(ref, { country })` | `/market` | Sales in FR (DVF), IT (OMI) and DE (NRW); official province prices in `zonePrices` for ES, PV, NA; PT `available: false` |
 | `parcels.valueHistory(ref, { country })` | `/value-history` | ES, PV, NA, PT, FR, IT, DE, AT |
-| `parcels.compare([{ reference, country }, ...])` | `POST /api/catastro/compare` | 2 or 3 parcels in ES, PT, FR, IT, DE |
-| `export.file(ref, 'kml' \| 'gpx' \| 'dxf', { country })` | `GET /api/export/{format}` | Where a geometry exists |
-| `resolve(text, { hint })` | `GET /api/resolve` | Free, no quota: which country and kind a text is |
+| `parcels.compare([{ reference, country }, ...])` | `POST /v1/parcels/compare` | 2 or 3 parcels in ES, PT, FR, IT, DE |
+| `export.file(ref, 'kml' \| 'gpx', { country })` | `GET /v1/export/{format}` | Where a geometry exists |
+| `locations.provinces()`, `locations.municipalities(region)`, `locations.streets({ region, municipality, name })` | `GET /v1/locations/...` | Spain (common territory): the names `findByAddress` expects |
+| `cropCatalog({ lang })` | `GET /v1/reference/crops` | Free, no quota: every `cropCode` with its name in 10 languages |
+| `resolve(text, { hint })` | `GET /v1/resolve` | Free, no quota: which country and kind a text is |
 
 ## Examples
 
 ```ts
 const inWarsaw = await client.parcels.atPoint({ lat: 52.2297, lng: 21.0122 });
-inWarsaw.referenciaCatastral;
-inWarsaw.pais;
+inWarsaw.reference;
+inWarsaw.country;
 
-const { candidatos } = await client.searchAddressCandidates({ q: 'Damrak 1, 1012 LG Amsterdam', country: 'NL' });
-candidatos[0].refCatastral;
-candidatos[0].confianza;
+const { candidates } = await client.searchAddressCandidates({ q: 'Damrak 1, 1012 LG Amsterdam', country: 'NL' });
+candidates[0].reference;
+candidates[0].confidence;
 
 const terrain = await client.parcels.terrain('10194A00110004');
 terrain.relief.slope?.class;
-terrain.protected_areas.natura2000;
+terrain.protectedAreas.natura2000;
 terrain.climate?.baseline;
 
 const brussels = await client.parcels.terrain('21004C0123/00', { country: 'BE', lat: 50.848139, lng: 4.353613 });
 
 const motion = await client.parcels.groundMotion('0745901TG4304N0002KH');
 motion.status;
-motion.ground_motion?.vertical.mean_mm_year;
+motion.groundMotion?.vertical.meanMmYear;
 
 const comparison = await client.parcels.compare([
   { reference: '9872023VH5797S0001WX', country: 'ES' },
@@ -82,35 +86,51 @@ const kml = await client.export.file('9872023VH5797S0001WX', 'kml');
 
 const guess = await client.resolve('05102200100005');
 guess.candidates;
+
+const crops = await client.parcels.subparcels('46063A00100121', { lang: 'en' });
+crops.subparcels[0].cropCode;
+crops.subparcels[0].crop;
+crops.subparcels[0].cropOriginal;
+
+const catalog = await client.cropCatalog({ lang: 'fr' });
+catalog.crops.find((crop) => crop.code === 'G-')?.name;
+
+const around = await client.parcels.neighbors('9872023VH5797S');
+around.neighbors.map((n) => n.reference);
+
+const { provinces } = await client.locations.provinces();
+const { streets } = await client.locations.streets({ region: 'CIUDAD REAL', municipality: 'AGUDO', name: 'GLORIA' });
 ```
 
+Crop names come in `lang` (`es`, `ca`, `en`, `pt`, `fr`, `it`, `de`, `pl`, `nl`, `cs`; English by default); the label as the source writes it is always in `cropOriginal`, and `cropCode` is stable across languages. Since 2.1.0 the parcel no longer embeds its subparcels: it carries `subparcelCount` and a `cropSummary` (crop and share of the area), and the full list with outlines is `parcels.subparcels`.
+
 `terrain` and `groundMotion` 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, with the field names the API uses (`refCatastral`, `municipio`, `superficieParcela`…). See the [API reference](https://www.catastrogps.es/developers) and the OpenAPI spec at `https://api.parcelgps.com/api/openapi.json`.
+Responses are the `data` object of the English v1 API (`https://api.parcelgps.com/v1`), typed: `reference`, `municipality`, `parcelArea`, `latitude`, `longitude`… Values that come from an official source (land use, addresses) stay in its language. See the [API reference](https://www.parcelgps.com/en/api/docs) and the OpenAPI spec at `https://api.parcelgps.com/v1/openapi.json`. Version 2 of this SDK talks only to `/v1`; 1.x used the deprecated Spanish-named `/api` routes.
 
 ## 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.
 
 ```ts
-const { candidatos } = await client.searchAddressCandidates('Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas');
-const finca = candidatos[0];
+const { candidates } = await client.searchAddressCandidates('Avenida José Rodríguez de la Borbolla Camoyán 10, Dos Hermanas');
+const finca = candidates[0];
 
-const comunidad = await client.getUnits(finca.refCatastral, { country: finca.pais as 'ES' | 'PV' | 'NA' });
-comunidad.totalUnidadesFinca;
-for (const u of comunidad.unidades) {
-  console.log(u.refCatastral, u.uso, u.superficie, u.participacion, u.escalera, u.planta, u.puerta);
+const comunidad = await client.getUnits(finca.reference, { country: finca.country as 'ES' | 'PV' | 'NA' });
+comunidad.propertyUnitCount;
+for (const u of comunidad.units) {
+  console.log(u.reference, u.use, u.area, u.ownershipShare, u.staircase, u.floor, u.door);
 }
 comunidad.dataSource;
 comunidad.attribution;
 
-const refreshed = await client.getUnits(finca.refCatastral, { previous: comunidad });
+const refreshed = await client.getUnits(finca.reference, { previous: comunidad });
 refreshed.changed;
 ```
 
 - `getUnits` follows `nextCursor` for you (up to 200 units per page). `iterUnitPages(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' | '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.
+- Basque Country and Navarre (`country: 'PV' | 'NA'`) are served from our copy of each foral cadastre: pass the foral reference of any unit or the finca key as the reference. 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.lastQuota.fincaCap` (`{ cap, used }`).
 
 ## Quota, prepaid balance and limits
@@ -163,7 +183,7 @@ try {
 | `NotFoundError` | `404 NOT_FOUND` |
 | `QuotaExceededError` | `429 KEY_AUTH_004` |
 | `RateLimitError` | `429 KEY_RATE_002`, `RATE_LIMIT_EXCEEDED`; `retryAfterSeconds` |
-| `ServiceUnavailableError` | `503 SERVICE_UNAVAILABLE`; `retryAfterSeconds` |
+| `ServiceUnavailableError` | `503 SERVICE_UNAVAILABLE`, `503 SUB_001` (subparcels source down, not charged); `retryAfterSeconds` |
 | `ServerError`, `TimeoutError`, `NetworkError` | `5xx`, client timeout, network failure |
 
 Timeouts, network errors, per-minute 429s and 502/503/504 are retried up to `maxRetries` 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.
@@ -173,14 +193,14 @@ Timeouts, network errors, per-minute 429s and 502/503/504 are retried up to `max
 | Option | Default | |
 |--------|---------|---|
 | `apiKey` | `process.env.CATASTROGPS_API_KEY` | Required |
-| `baseUrl` | `https://api.catastrogps.es` | `https://api.parcelgps.com` is the same API |
+| `baseUrl` | `https://api.parcelgps.com` | Paths are under `/v1` |
 | `timeoutMs` | `30000` | Official cadastres can be slow |
 | `maxRetries` | `2` | |
 | `fetch` | `globalThis.fetch` | Inject your own for tests or proxies |
 
 ## Coverage
 
-Measured against production on 1 October 2026. 29 European countries, 31 official cadastres including the Basque Country and Navarre; in Croatia, Sweden and the United Kingdom the source is partial, as the table shows.
+Measured against production on 1 October 2026. 29 European countries, including the Basque Country and Navarre foral cadastres: by cadastral reference in 27, by coordinates in all 29; in Croatia, Sweden and the United Kingdom the source is partial, as the table shows.
 
 | Code | Country / region | Reference | Coordinates | Address | Notes |
 |------|------------------|:---:|:---:|:---:|-------|