catastrogps 1.0.0 → 1.2.0

package/README.md

@@ -1,11 +1,14 @@
 # catastrogps
 
-Official JavaScript and TypeScript 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.
+Official JavaScript and TypeScript client for the [Catastro GPS API](https://www.catastrogps.es/developers): 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 **Spanish postal address in free text** into a cadastral reference.
+- 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.
-- **Solar** (PVGIS) and **agricultural** context for parcels in Spain, Portugal, France, Italy and Germany.
+- **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 errors for every API code.
 - Zero runtime dependencies. Node.js 18+, Deno, Bun and edge runtimes with `fetch`. ESM and CommonJS, fully typed.
 
 **Free tier: 250 calls a month, forever. Failed lookups are not charged.** Get a key at [catastrogps.es/developers](https://www.catastrogps.es/developers).
@@ -29,40 +32,106 @@ console.log(parcel.municipio, parcel.superficieParcela, parcel.latitud, parcel.l
 
 `new CatastroGPS()` with no arguments reads `CATASTROGPS_API_KEY` from the environment.
 
+## Methods
+
+| 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.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 |
+
 ## Examples
 
 ```ts
-const fromAddress = await client.parcels.findByAddress('Calle Mallorca 213, Barcelona');
-fromAddress.referenciaCatastral;
-
 const inWarsaw = await client.parcels.atPoint({ lat: 52.2297, lng: 21.0122 });
 inWarsaw.referenciaCatastral;
 inWarsaw.pais;
 
-const foral = await client.parcels.get('<Navarre reference>', { country: 'NA' });
+const { candidatos } = await client.searchAddressCandidates({ q: 'Damrak 1, 1012 LG Amsterdam', country: 'NL' });
+candidatos[0].refCatastral;
+candidatos[0].confianza;
+
+const terrain = await client.parcels.terrain('10194A00110004');
+terrain.relief.slope?.class;
+terrain.protected_areas.natura2000;
+terrain.climate?.baseline;
 
-const outline = await client.parcels.geometry('9872023VH5797S', { country: 'ES' });
-outline.geojson;
+const brussels = await client.parcels.terrain('21004C0123/00', { country: 'BE', lat: 50.848139, lng: 4.353613 });
 
-const solar = await client.parcels.solar('9872023VH5797S0001WX');
-solar.kwh_year;
+const motion = await client.parcels.groundMotion('0745901TG4304N0002KH');
+motion.status;
+motion.ground_motion?.vertical.mean_mm_year;
+
+const comparison = await client.parcels.compare([
+  { reference: '9872023VH5797S0001WX', country: 'ES' },
+  { reference: '750560000AB0001', country: 'FR' },
+]);
 
 const kml = await client.export.file('9872023VH5797S0001WX', 'kml');
 
 const guess = await client.resolve('05102200100005');
 guess.candidates;
+```
 
-client.lastQuota;
+`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`.
+
+## 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 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);
+}
+comunidad.dataSource;
+comunidad.attribution;
+
+const refreshed = await client.getUnits(finca.refCatastral, { previous: comunidad });
+refreshed.changed;
 ```
 
-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).
+- `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.
+- 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
+
+`client.lastQuota` is read from the headers of the last response; `conditionalRequest` also returns the `quota` of that exact response.
+
+| Field | Header | Meaning |
+|-------|--------|---------|
+| `plan`, `limit`, `remaining`, `resetsAt` | `X-Quota-Tier`, `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset` | Monthly quota of your plan, after this response |
+| `overage.balance`, `overage.unitPrice`, `overage.remainingUnits` | `X-Quota-Overage`, `X-Quota-Balance`, `X-Quota-Overage-Unit-Price`, `X-Quota-Overage-Remaining` | Prepaid pay-as-you-go balance in euros, used once the monthly quota is spent |
+| `rateLimit.limit`, `rateLimit.remaining`, `rateLimit.resetSeconds` | `X-RateLimit-*` | Per-minute burst limit of your key (Free 10, Developer 60, Startup 120, Growth 300) |
+| `fincaCap.cap`, `fincaCap.used` | `X-Quota-Finca-Cap`, `X-Quota-Finca-Cap-Used` | Only on `/units`, only with a contract cap |
+
+When the monthly quota is spent and there is no prepaid balance left, the API answers `429 KEY_AUTH_004` (never `402`): the client throws `QuotaExceededError` with the `quota` of that response, and `prepaidBalanceEmpty` 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`. Subclasses let you branch cleanly:
 
 ```ts
-import { AmbiguousReferenceError, CoverageError, NotFoundError, QuotaExceededError } from 'catastrogps';
+import { AmbiguousReferenceError, CoverageError, NotFoundError, PlaceNameError, QuotaExceededError } from 'catastrogps';
 
 try {
   await client.parcels.get('05102200100005');
@@ -70,57 +139,79 @@ try {
   if (error instanceof AmbiguousReferenceError) {
     const [first] = error.candidates;
     await client.parcels.get('05102200100005', { country: first.country as 'DE' });
-  } else if (error instanceof NotFoundError || error instanceof CoverageError) {
+  } else if (error instanceof PlaceNameError) {
+    console.log('A place name, not a reference', error.location);
+  } else if (error instanceof CoverageError) {
+    console.log(error.country, error.feature, error.supportedCountries);
+  } else if (error instanceof NotFoundError) {
     console.log(error.message);
   } else if (error instanceof QuotaExceededError) {
-    console.log('Monthly quota used up');
+    console.log('Quota spent', error.quota?.resetsAt, error.prepaidBalanceEmpty);
   } else {
     throw error;
   }
 }
 ```
 
-Also available: `AuthenticationError`, `ValidationError`, `RateLimitError`, `ServiceUnavailableError`, `ServerError`, `TimeoutError`, `NetworkError`.
-
-Timeouts, network errors, 429 rate limits and 502/503/504 are retried up to `maxRetries` times (default 2) with exponential backoff. An exhausted monthly quota is never retried. Each attempt that reaches the API counts as a call.
+| Class | API code / status |
+|-------|-------------------|
+| `AmbiguousReferenceError` | `300 CNV_AMBIGUOUS`: bare digits of several countries; `candidates` lists them |
+| `CoverageError` | `422 CNV_COVERAGE`: country not covered, or an analysis outside its countries |
+| `PlaceNameError` (a `ValidationError`) | `422 CNV_PLACE_NAME`: a place name, with the geocoded `location` when found |
+| `ValidationError` | `400 VALIDATION_ERROR`, other `422` |
+| `AuthenticationError` / `ForbiddenError` | `401 KEY_AUTH_001..003`, `403` |
+| `NotFoundError` | `404 NOT_FOUND` |
+| `QuotaExceededError` | `429 KEY_AUTH_004` |
+| `RateLimitError` | `429 KEY_RATE_002`, `RATE_LIMIT_EXCEEDED`; `retryAfterSeconds` |
+| `ServiceUnavailableError` | `503 SERVICE_UNAVAILABLE`; `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.
 
 ## Options
 
 | Option | Default | |
 |--------|---------|---|
 | `apiKey` | `process.env.CATASTROGPS_API_KEY` | Required |
-| `baseUrl` | `https://api.catastrogps.es` | |
+| `baseUrl` | `https://api.catastrogps.es` | `https://api.parcelgps.com` is the same API |
 | `timeoutMs` | `30000` | Official cadastres can be slow |
 | `maxRetries` | `2` | |
 | `fetch` | `globalThis.fetch` | Inject your own for tests or proxies |
 
 ## 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.
+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.
+
+| Code | Country / region | Reference | Coordinates | Address | Notes |
+|------|------------------|:---:|:---:|:---:|-------|
+| `ES` | Spain | Yes | Yes | Yes | Units per building |
+| `PV` · `NA` | Basque Country · Navarre | Yes | Yes | With `country: 'ES'` | Foral cadastres; units per building |
+| `FR` · `IT` | France · Italy | Yes | Yes | Yes | |
+| `DE` | Germany | Partial | Partial | Partial | 15 of 16 Länder: **no Bavaria** |
+| `PT` | Portugal | Yes | Partial | Partial | The cadastre does not cover Lisbon, Porto or Coimbra |
+| `AT` `NL` `BE` `PL` `CZ` `DK` `NO` `FI` `EE` | Austria, Netherlands, Belgium, Poland, Czechia, Denmark, Norway, Finland, Estonia | Yes | Yes | Yes | Belgium is slow (3-15 s) |
+| `CH` | Switzerland | Yes | Partial | Yes | Not in cantons that publish no parcels (e.g. Vaud) |
+| `LT` `SI` `SK` `BG` `LU` `LI` `IS` `CY` | Lithuania, Slovenia, Slovakia, Bulgaria, Luxembourg, Liechtenstein, Iceland, Cyprus | Yes | Yes | Yes | |
+| `GR` · `LV` | Greece · Latvia | With the country set | Yes | Yes | |
+| `IE` | Ireland | With `country: 'IE'` | Partial | Partial | Numeric SP_ID |
+| `SE` | Sweden | Agricultural blocks | Agricultural blocks | No | Not property units |
+| `HR` | Croatia | No | ARKOD only | No | Agricultural parcels of the Paying Agency, not the cadastre |
+| `UK` | United Kingdom | No | Scotland | Scotland | |
+
+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
 
-| Plan | Price | Calls / month |
-|------|-------|---------------|
-| Free | €0, forever | 100 |
-| Developer | €19 / month | 5,000 |
-| Startup | €49 / month | 15,000 |
-| Growth | €99 / month | 50,000 |
+| Plan | Price | Calls / month | Prepaid overage per 1,000 |
+|------|-------|---------------|---------------------------|
+| Free | €0, forever | 250 | €10 |
+| Developer | €19 / month | 5,000 | €5 |
+| Startup | €49 / month | 15,000 | €4 |
+| Growth | €99 / month | 50,000 | €2.50 |
+
+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 Python SDK (`pip install catastrogps`) and the MCP server for AI agents ([`catastro-gps-mcp`](https://www.npmjs.com/package/catastro-gps-mcp)).
+The same key works with the Python SDK (`pip install catastrogps`), the Go SDK and the MCP server for AI agents ([`catastro-gps-mcp`](https://www.npmjs.com/package/catastro-gps-mcp)).
 
 ## License
 

package/dist/index.d.mts

@@ -14,11 +14,33 @@ interface CatastroGPSOptions {
 interface CountryOption<C extends string = CountryCode> {
     country?: C;
 }
+declare const ADDRESS_COUNTRY_CODES: readonly ["ES", "FR", "IT", "DE", "AT", "NL", "BE", "PL", "CH", "CZ", "DK", "NO", "FI", "EE", "LV", "LT", "SI", "SK", "BG", "GR", "CY", "LU", "LI", "IS", "IE", "UK", "PT"];
+type AddressCountryCode = (typeof ADDRESS_COUNTRY_CODES)[number];
+declare const UNITS_COUNTRY_CODES: readonly ["ES", "PV", "NA"];
+type UnitsCountryCode = (typeof UNITS_COUNTRY_CODES)[number];
+interface PrepaidOverage {
+    enabled: boolean;
+    balance?: number;
+    unitPrice?: number;
+    remainingUnits?: number;
+}
+interface BurstLimit {
+    limit?: number;
+    remaining?: number;
+    resetSeconds?: number;
+}
+interface FincaCap {
+    cap?: number;
+    used?: number;
+}
 interface Quota {
     plan?: string;
     limit?: number;
     remaining?: number;
     resetsAt?: string;
+    overage?: PrepaidOverage;
+    rateLimit?: BurstLimit;
+    fincaCap?: FincaCap;
 }
 interface Parcel {
     refCatastral: string;
@@ -117,6 +139,233 @@ interface ResolveResult {
     candidates: ResolveCandidate[];
     ambiguous: boolean;
 }
+interface AddressCandidatesQuery {
+    q?: string;
+    country?: AddressCountryCode;
+    street?: string;
+    number?: number;
+    municipality?: string;
+    postcode?: string;
+    limit?: number;
+}
+interface AddressCandidate {
+    refCatastral: string;
+    pais: 'ES' | 'PV' | 'NA' | string;
+    direccion: string;
+    numero?: number;
+    codigoPostal?: string;
+    municipio: string;
+    provincia: string;
+    latitud: number;
+    longitud: number;
+    confianza: number;
+    coincideNumero: boolean;
+    coincideMunicipio: boolean;
+    enCopia: boolean;
+    direccionCatastro?: string;
+    uso?: string;
+    viviendas?: number;
+    anioConstruccion?: number;
+}
+interface AddressCandidatesResult {
+    consulta: {
+        texto: string;
+        calle?: string;
+        numero?: number;
+        municipio?: string;
+        codigoPostal?: string;
+    };
+    candidatos: AddressCandidate[];
+    attribution: string;
+}
+interface Unit {
+    refCatastral: string;
+    escalera: string;
+    planta: string;
+    puerta: string;
+    uso: string;
+    superficie: number;
+    descripcion: string;
+    participacion?: number;
+    anio?: number;
+    direccion?: string;
+}
+interface Construction {
+    escalera: string;
+    planta: string;
+    puerta: string;
+    uso: string;
+    superficie: number;
+    descripcion: string;
+}
+interface UnitsPageData {
+    refCatastral: string;
+    direccion?: string;
+    codigoPostal?: string;
+    municipio?: string;
+    provincia?: string;
+    usoGeneral?: string;
+    superficieTotal?: number;
+    anioConstruccion?: number;
+    participacion?: string;
+    totalUnidades: number;
+    totalUnidadesFinca: number;
+    unidades: Unit[];
+    construcciones?: Construction[];
+    truncated: boolean;
+    nextCursor?: string;
+    dataSource: 'clone' | 'catastro' | string;
+    dataDate: string;
+    attribution: string;
+}
+interface UnitsPage {
+    cursor?: string;
+    etag?: string;
+    notModified: boolean;
+    data: UnitsPageData;
+}
+interface UnitsResult {
+    refCatastral: string;
+    direccion?: string;
+    codigoPostal?: string;
+    municipio?: string;
+    provincia?: string;
+    usoGeneral?: string;
+    anioConstruccion?: number;
+    totalUnidadesFinca: number;
+    unidades: Unit[];
+    construcciones: Construction[];
+    dataSource: string;
+    dataDate: string;
+    attribution: string;
+    changed: boolean;
+    pages: UnitsPage[];
+}
+interface GetUnitsOptions {
+    country?: UnitsCountryCode;
+    previous?: UnitsResult;
+}
+interface LocatedOptions extends CountryOption<Exclude<CountryCode, 'UK' | 'HR'>> {
+    lat?: number;
+    lng?: number;
+}
+interface DataSource {
+    name?: string;
+    provider?: string;
+    license?: string;
+    attribution?: string;
+    url?: string;
+    resolution?: string;
+    edition?: string;
+}
+type BlockStatus = 'ok' | 'no_data' | 'unavailable';
+interface ProtectedSite {
+    code: string;
+    name: string;
+    type?: 'SPA' | 'SCI' | 'SPA_SCI' | string;
+    designation?: string;
+    country?: string;
+    overlap_pct?: number | null;
+}
+interface Terrain {
+    refcat: string;
+    country: string;
+    relief: {
+        status: BlockStatus;
+        elevation_m?: {
+            mean: number;
+            min: number;
+            max: number;
+        };
+        slope?: {
+            mean_pct: number;
+            mean_deg: number;
+            max_pct: number;
+            class: string;
+            max_class: string;
+            share_over_10_pct: number;
+            classes_pct: Record<string, number>;
+        };
+        aspect?: {
+            dominant: string;
+            dominant_share_pct: number;
+            mean_deg: number | null;
+            flat_share_pct: number;
+            sectors_pct: Record<string, number>;
+        };
+        sample?: {
+            method: string;
+            cells: number;
+            resolution_m: number;
+        };
+        source?: DataSource;
+    };
+    protected_areas: {
+        status: BlockStatus;
+        intersects?: boolean;
+        inside?: boolean;
+        max_overlap_pct?: number | null;
+        natura2000?: ProtectedSite[];
+        national?: ProtectedSite[];
+        method?: string;
+        sources?: DataSource[];
+    };
+    climate?: {
+        status: BlockStatus;
+        baseline?: Record<string, number>;
+        recent?: Record<string, number>;
+        [key: string]: unknown;
+    };
+    calculated_at?: string;
+    provenance?: string;
+}
+interface GroundMotion {
+    refcat: string;
+    country: string;
+    status: BlockStatus;
+    reason?: 'no_reflectors' | 'outside_coverage' | 'parcel_too_large' | string;
+    period?: {
+        from: string;
+        to: string;
+        label: string;
+    };
+    ground_motion?: {
+        class: string;
+        worst_class?: string;
+        vertical: {
+            mean_mm_year: number;
+            max_subsidence_mm_year?: number;
+            max_uplift_mm_year?: number;
+            std_mm_year?: number;
+            acceleration_mm_year2?: number;
+            rmse_mm?: number;
+        };
+        east_west?: {
+            mean_mm_year: number;
+            std_mm_year?: number;
+        };
+        yearly_displacement?: Array<{
+            year: number;
+            mm: number;
+        }>;
+        cells_with_data: number;
+        cells_considered: number;
+        coverage_pct: number;
+        basis?: 'parcel' | 'surroundings' | string;
+        cell_size_m?: number;
+    };
+    source?: DataSource;
+    calculated_at?: string;
+    provenance?: string;
+}
+type MarketData = Record<string, unknown>;
+type ScoreData = Record<string, unknown>;
+type ValueHistory = Record<string, unknown>;
+type Comparison = Record<string, unknown>;
+interface CompareItem {
+    reference: string;
+    country: EnrichmentCountryCode;
+}
 
 declare class ExportResource {
     private readonly client;
@@ -124,6 +373,14 @@ declare class ExportResource {
     file(reference: string, format: ExportFormat, options?: CountryOption): Promise<ArrayBuffer>;
 }
 
+declare class FincasResource {
+    private readonly client;
+    constructor(client: CatastroGPS);
+    searchAddress(query: string | AddressCandidatesQuery): Promise<AddressCandidatesResult>;
+    pages(refcat14: string, options?: GetUnitsOptions): AsyncGenerator<UnitsPage>;
+    units(refcat14: string, options?: GetUnitsOptions): Promise<UnitsResult>;
+}
+
 interface PointQuery extends CountryOption {
     lat: number;
     lng: number;
@@ -137,6 +394,12 @@ declare class ParcelsResource {
     geometry(reference: string, options?: CountryOption<Exclude<CountryCode, 'UK'>>): Promise<ParcelGeometry>;
     solar(reference: string, options?: CountryOption<EnrichmentCountryCode>): Promise<SolarEstimate>;
     agriculture(reference: string, options?: CountryOption<EnrichmentCountryCode>): Promise<AgricultureData>;
+    terrain(reference: string, options?: LocatedOptions): Promise<Terrain>;
+    groundMotion(reference: string, options?: LocatedOptions): Promise<GroundMotion>;
+    market(reference: string, options?: CountryOption<EnrichmentCountryCode>): Promise<MarketData>;
+    score(reference: string, options?: CountryOption<EnrichmentCountryCode>): Promise<ScoreData>;
+    valueHistory(reference: string, options?: CountryOption<EnrichmentCountryCode | 'AT'>): Promise<ValueHistory>;
+    compare(parcels: CompareItem[]): Promise<Comparison>;
 }
 
 declare const DEFAULT_BASE_URL = "https://api.catastrogps.es";
@@ -147,10 +410,18 @@ interface RequestOptions {
     query?: Query;
     body?: unknown;
     raw?: boolean;
+    ifNoneMatch?: string;
+}
+interface ConditionalResponse<T> {
+    data?: T;
+    etag?: string;
+    notModified: boolean;
+    quota?: Quota;
 }
 declare class CatastroGPS {
     readonly parcels: ParcelsResource;
     readonly export: ExportResource;
+    readonly fincas: FincasResource;
     lastQuota?: Quota;
     private readonly apiKey;
     private readonly baseUrl;
@@ -158,18 +429,23 @@ declare class CatastroGPS {
     private readonly maxRetries;
     private readonly fetchImpl;
     constructor(options?: CatastroGPSOptions);
+    searchAddressCandidates(query: string | AddressCandidatesQuery): Promise<AddressCandidatesResult>;
+    getUnits(refcat14: string, options?: GetUnitsOptions): Promise<UnitsResult>;
+    iterUnitPages(refcat14: string, options?: GetUnitsOptions): AsyncGenerator<UnitsPage>;
     resolve(text: string, options?: {
         hint?: string;
     }): Promise<ResolveResult>;
     request<T>(method: 'GET' | 'POST', path: string, options?: RequestOptions): Promise<T>;
+    conditionalRequest<T>(method: 'GET' | 'POST', path: string, options?: RequestOptions): Promise<ConditionalResponse<T>>;
     private once;
     private buildUrl;
     private shouldRetry;
     private retryDelayMs;
     private captureQuota;
 }
+declare function readQuota(headers: Headers): Quota | undefined;
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.2.0";
 
 declare class CatastroGPSError extends Error {
     readonly status?: number;
@@ -195,8 +471,20 @@ declare class NotFoundError extends CatastroGPSError {
 declare class ValidationError extends CatastroGPSError {
     name: string;
 }
+declare class PlaceNameError extends ValidationError {
+    name: string;
+    get location(): {
+        lat: number;
+        lng: number;
+        address?: string;
+        label?: string;
+    } | undefined;
+}
 declare class CoverageError extends CatastroGPSError {
     name: string;
+    get country(): string | undefined;
+    get feature(): string | undefined;
+    get supportedCountries(): string[];
 }
 declare class AmbiguousReferenceError extends CatastroGPSError {
     name: string;
@@ -208,6 +496,8 @@ declare class AmbiguousReferenceError extends CatastroGPSError {
 }
 declare class QuotaExceededError extends CatastroGPSError {
     name: string;
+    quota?: Quota;
+    get prepaidBalanceEmpty(): boolean;
 }
 declare class RateLimitError extends CatastroGPSError {
     name: string;
@@ -215,6 +505,7 @@ declare class RateLimitError extends CatastroGPSError {
 }
 declare class ServiceUnavailableError extends CatastroGPSError {
     name: string;
+    retryAfterSeconds?: number;
 }
 declare class ServerError extends CatastroGPSError {
     name: string;
@@ -226,4 +517,4 @@ declare class NetworkError extends CatastroGPSError {
     name: string;
 }
 
-export { type AddressMatch, type AgricultureData, AmbiguousReferenceError, AuthenticationError, COUNTRY_CODES, CatastroGPS, CatastroGPSError, type CatastroGPSOptions, type CountryCode, type CountryOption, CoverageError, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ENRICHMENT_COUNTRY_CODES, type EnrichmentCountryCode, type ExportFormat, type FetchLike, ForbiddenError, NetworkError, NotFoundError, type Parcel, type ParcelGeometry, type PointMatch, type PointQuery, type Quota, QuotaExceededError, RateLimitError, type ResolveCandidate, type ResolveResult, ServerError, ServiceUnavailableError, type SolarEstimate, TimeoutError, VERSION, ValidationError };
+export { ADDRESS_COUNTRY_CODES, type AddressCandidate, type AddressCandidatesQuery, type AddressCandidatesResult, type AddressCountryCode, type AddressMatch, type AgricultureData, AmbiguousReferenceError, AuthenticationError, type BlockStatus, type BurstLimit, COUNTRY_CODES, CatastroGPS, CatastroGPSError, type CatastroGPSOptions, type CompareItem, type Comparison, type ConditionalResponse, type Construction, type CountryCode, type CountryOption, CoverageError, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DataSource, ENRICHMENT_COUNTRY_CODES, type EnrichmentCountryCode, type ExportFormat, type FetchLike, type FincaCap, ForbiddenError, type GetUnitsOptions, type GroundMotion, type LocatedOptions, type MarketData, NetworkError, NotFoundError, type Parcel, type ParcelGeometry, PlaceNameError, type PointMatch, type PointQuery, type PrepaidOverage, type ProtectedSite, type Quota, QuotaExceededError, RateLimitError, type ResolveCandidate, type ResolveResult, type ScoreData, ServerError, ServiceUnavailableError, type SolarEstimate, type Terrain, TimeoutError, UNITS_COUNTRY_CODES, type Unit, type UnitsCountryCode, type UnitsPage, type UnitsPageData, type UnitsResult, VERSION, ValidationError, type ValueHistory, readQuota };