catastrogps 1.0.0 → 1.1.0

package/README.md

@@ -55,8 +55,40 @@ guess.candidates;
 client.lastQuota;
 ```
 
+`client.lastQuota` is the monthly quota of your plan as of the last response: `{ plan, limit, remaining, resetsAt }`, read from the `X-Quota-Tier`, `X-Quota-Limit`, `X-Quota-Remaining` and `X-Quota-Reset` headers. The `X-RateLimit-*` headers are a different thing: a per-key burst limit per minute that depends on your plan (Free 10, Developer 60, Startup 120, Growth 300; a global per-IP guard also applies) that the client handles by retrying.
+
 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).
 
+## Importar una comunidad de propietarios (Spain)
+
+Address → finca (14-character reference) → 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];
+finca.refCatastral;
+finca.confianza;
+finca.pais;
+
+const comunidad = await client.getUnits(finca.refCatastral);
+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.dataDate;
+comunidad.attribution;
+
+const refreshed = await client.getUnits(finca.refCatastral, { previous: comunidad });
+refreshed.changed;
+```
+
+- `searchAddressCandidates` also takes `{ street, number, municipality, postcode, limit }`. Candidates come ranked by `confianza` (0.75 or more: number and municipality match). It costs 1 quota unit.
+- `getUnits` follows `nextCursor` for you (200 units per page) and costs one quota unit per 50 units, minimum one per page. `iterUnitPages(ref)` yields page by page.
+- Pass the previous result as `previous` to re-import: pages that did not change come back as `304 Not Modified`, cost nothing, and are reused; `changed` tells you if anything moved.
+- Fincas in the Basque Country or Navarra (`pais: 'PV' | 'NA'`) throw `CoverageError`: their foral cadastres are not served per finca.
+- A `ServiceUnavailableError` carries `retryAfterSeconds`; the client already waits for it (up to 60 s) before its retries.
+
 ## Errors
 
 Every error is a `CatastroGPSError` with `status`, `code` and `details`. Subclasses let you branch cleanly:
@@ -82,7 +114,7 @@ try {
 
 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.
+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. Only 2xx responses spend quota; failed attempts and `304 Not Modified` are free.
 
 ## Options
 

package/dist/index.d.mts

@@ -117,6 +117,110 @@ interface ResolveResult {
     candidates: ResolveCandidate[];
     ambiguous: boolean;
 }
+interface AddressCandidatesQuery {
+    q?: string;
+    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 {
+    previous?: UnitsResult;
+}
 
 declare class ExportResource {
     private readonly client;
@@ -124,6 +228,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;
@@ -147,10 +259,17 @@ interface RequestOptions {
     query?: Query;
     body?: unknown;
     raw?: boolean;
+    ifNoneMatch?: string;
+}
+interface ConditionalResponse<T> {
+    data?: T;
+    etag?: string;
+    notModified: boolean;
 }
 declare class CatastroGPS {
     readonly parcels: ParcelsResource;
     readonly export: ExportResource;
+    readonly fincas: FincasResource;
     lastQuota?: Quota;
     private readonly apiKey;
     private readonly baseUrl;
@@ -158,10 +277,14 @@ 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;
@@ -169,7 +292,7 @@ declare class CatastroGPS {
     private captureQuota;
 }
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.1.0";
 
 declare class CatastroGPSError extends Error {
     readonly status?: number;
@@ -215,6 +338,7 @@ declare class RateLimitError extends CatastroGPSError {
 }
 declare class ServiceUnavailableError extends CatastroGPSError {
     name: string;
+    retryAfterSeconds?: number;
 }
 declare class ServerError extends CatastroGPSError {
     name: string;
@@ -226,4 +350,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 { type AddressCandidate, type AddressCandidatesQuery, type AddressCandidatesResult, type AddressMatch, type AgricultureData, AmbiguousReferenceError, AuthenticationError, COUNTRY_CODES, CatastroGPS, CatastroGPSError, type CatastroGPSOptions, type ConditionalResponse, type Construction, type CountryCode, type CountryOption, CoverageError, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ENRICHMENT_COUNTRY_CODES, type EnrichmentCountryCode, type ExportFormat, type FetchLike, ForbiddenError, type GetUnitsOptions, NetworkError, NotFoundError, type Parcel, type ParcelGeometry, type PointMatch, type PointQuery, type Quota, QuotaExceededError, RateLimitError, type ResolveCandidate, type ResolveResult, ServerError, ServiceUnavailableError, type SolarEstimate, TimeoutError, type Unit, type UnitsPage, type UnitsPageData, type UnitsResult, VERSION, ValidationError };

package/dist/index.d.ts

@@ -117,6 +117,110 @@ interface ResolveResult {
     candidates: ResolveCandidate[];
     ambiguous: boolean;
 }
+interface AddressCandidatesQuery {
+    q?: string;
+    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 {
+    previous?: UnitsResult;
+}
 
 declare class ExportResource {
     private readonly client;
@@ -124,6 +228,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;
@@ -147,10 +259,17 @@ interface RequestOptions {
     query?: Query;
     body?: unknown;
     raw?: boolean;
+    ifNoneMatch?: string;
+}
+interface ConditionalResponse<T> {
+    data?: T;
+    etag?: string;
+    notModified: boolean;
 }
 declare class CatastroGPS {
     readonly parcels: ParcelsResource;
     readonly export: ExportResource;
+    readonly fincas: FincasResource;
     lastQuota?: Quota;
     private readonly apiKey;
     private readonly baseUrl;
@@ -158,10 +277,14 @@ 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;
@@ -169,7 +292,7 @@ declare class CatastroGPS {
     private captureQuota;
 }
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.1.0";
 
 declare class CatastroGPSError extends Error {
     readonly status?: number;
@@ -215,6 +338,7 @@ declare class RateLimitError extends CatastroGPSError {
 }
 declare class ServiceUnavailableError extends CatastroGPSError {
     name: string;
+    retryAfterSeconds?: number;
 }
 declare class ServerError extends CatastroGPSError {
     name: string;
@@ -226,4 +350,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 { type AddressCandidate, type AddressCandidatesQuery, type AddressCandidatesResult, type AddressMatch, type AgricultureData, AmbiguousReferenceError, AuthenticationError, COUNTRY_CODES, CatastroGPS, CatastroGPSError, type CatastroGPSOptions, type ConditionalResponse, type Construction, type CountryCode, type CountryOption, CoverageError, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ENRICHMENT_COUNTRY_CODES, type EnrichmentCountryCode, type ExportFormat, type FetchLike, ForbiddenError, type GetUnitsOptions, NetworkError, NotFoundError, type Parcel, type ParcelGeometry, type PointMatch, type PointQuery, type Quota, QuotaExceededError, RateLimitError, type ResolveCandidate, type ResolveResult, ServerError, ServiceUnavailableError, type SolarEstimate, TimeoutError, type Unit, type UnitsPage, type UnitsPageData, type UnitsResult, VERSION, ValidationError };

package/dist/index.js

@@ -89,6 +89,7 @@ var RateLimitError = class extends CatastroGPSError {
 };
 var ServiceUnavailableError = class extends CatastroGPSError {
   name = "ServiceUnavailableError";
+  retryAfterSeconds;
 };
 var ServerError = class extends CatastroGPSError {
   name = "ServerError";
@@ -116,7 +117,11 @@ function errorFromResponse(status, body, retryAfter) {
   if (status === 403) return new ForbiddenError(message, options);
   if (status === 404) return new NotFoundError(message, options);
   if (status === 400 || status === 422) return new ValidationError(message, options);
-  if (status === 503) return new ServiceUnavailableError(message, options);
+  if (status === 503) {
+    const error = new ServiceUnavailableError(message, options);
+    error.retryAfterSeconds = retryAfter;
+    return error;
+  }
   if (status >= 500) return new ServerError(message, options);
   return new CatastroGPSError(message, options);
 }
@@ -179,8 +184,73 @@ function parcelPath(reference, suffix = "") {
   return `/api/catastro/${encodeURIComponent(reference.trim())}${suffix}`;
 }
 
+// src/resources/fincas.ts
+var MAX_PAGES = 1e3;
+var FincasResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async searchAddress(query) {
+    const params = typeof query === "string" ? { q: query } : query;
+    if (!params.q?.trim() && !params.street?.trim()) throw new CatastroGPSError("q or street is required");
+    return this.client.request("GET", "/api/search/address/candidates", {
+      query: {
+        q: params.q?.trim(),
+        street: params.street?.trim(),
+        number: params.number,
+        municipality: params.municipality?.trim(),
+        postcode: params.postcode?.trim(),
+        limit: params.limit
+      }
+    });
+  }
+  async *pages(refcat14, options = {}) {
+    const path = parcelPath(refcat14, "/units");
+    const previousByCursor = new Map((options.previous?.pages ?? []).map((page) => [page.cursor ?? "", page]));
+    let cursor;
+    for (let count = 0; count < MAX_PAGES; count += 1) {
+      const previous = previousByCursor.get(cursor ?? "");
+      const response = await this.client.conditionalRequest("GET", path, {
+        query: { cursor },
+        ifNoneMatch: previous?.etag
+      });
+      const data = response.notModified && previous ? previous.data : response.data;
+      if (!data) throw new CatastroGPSError("The API answered 304 for a page that was not in the previous import");
+      const page = { cursor, etag: response.etag, notModified: response.notModified, data };
+      yield page;
+      if (!data.truncated || !data.nextCursor) return;
+      cursor = data.nextCursor;
+    }
+    throw new CatastroGPSError(`Stopped after ${MAX_PAGES} pages`);
+  }
+  async units(refcat14, options = {}) {
+    const pages = [];
+    for await (const page of this.pages(refcat14, options)) pages.push(page);
+    const first = pages[0].data;
+    const last = pages[pages.length - 1].data;
+    return {
+      refCatastral: first.refCatastral,
+      direccion: first.direccion,
+      codigoPostal: first.codigoPostal,
+      municipio: first.municipio,
+      provincia: first.provincia,
+      usoGeneral: first.usoGeneral,
+      anioConstruccion: first.anioConstruccion,
+      totalUnidadesFinca: last.totalUnidadesFinca ?? pages.reduce((sum, p) => sum + p.data.unidades.length, 0),
+      unidades: pages.flatMap((page) => page.data.unidades),
+      construcciones: pages.flatMap((page) => page.data.construcciones ?? []),
+      dataSource: first.dataSource,
+      dataDate: first.dataDate,
+      attribution: first.attribution,
+      changed: !pages.every((page) => page.notModified) || pages.length !== (options.previous?.pages.length ?? -1),
+      pages
+    };
+  }
+};
+
 // src/version.ts
-var VERSION = "1.0.0";
+var VERSION = "1.1.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.catastrogps.es";
@@ -188,9 +258,12 @@ var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
 var BACKOFF_BASE_MS = 500;
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([502, 503, 504]);
+var NOT_MODIFIED = 304;
+var MAX_RETRY_AFTER_SECONDS = 60;
 var CatastroGPS = class {
   parcels;
   export;
+  fincas;
   lastQuota;
   apiKey;
   baseUrl;
@@ -215,11 +288,25 @@ var CatastroGPS = class {
     this.fetchImpl = fetchImpl;
     this.parcels = new ParcelsResource(this);
     this.export = new ExportResource(this);
+    this.fincas = new FincasResource(this);
+  }
+  async searchAddressCandidates(query) {
+    return this.fincas.searchAddress(query);
+  }
+  async getUnits(refcat14, options = {}) {
+    return this.fincas.units(refcat14, options);
+  }
+  iterUnitPages(refcat14, options = {}) {
+    return this.fincas.pages(refcat14, options);
   }
   async resolve(text, options = {}) {
     return this.request("GET", "/api/resolve", { query: { q: text, hint: options.hint } });
   }
   async request(method, path, options = {}) {
+    const result = await this.conditionalRequest(method, path, options);
+    return result.data;
+  }
+  async conditionalRequest(method, path, options = {}) {
     const url = this.buildUrl(path, options.query);
     let attempt = 0;
     for (; ; ) {
@@ -241,6 +328,7 @@ var CatastroGPS = class {
       "User-Agent": `catastrogps-js/${VERSION}`
     };
     if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    if (options.ifNoneMatch) headers["If-None-Match"] = options.ifNoneMatch;
     let response;
     try {
       response = await this.fetchImpl(url, {
@@ -258,14 +346,16 @@ var CatastroGPS = class {
       clearTimeout(timer);
     }
     this.captureQuota(response.headers);
+    const etag = response.headers.get("ETag") ?? void 0;
+    if (response.status === NOT_MODIFIED) return { etag: etag ?? options.ifNoneMatch, notModified: true };
     if (!response.ok) {
       const body2 = await readJson(response);
       const retryAfter = Number(response.headers.get("Retry-After"));
       throw errorFromResponse(response.status, body2, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0);
     }
-    if (options.raw) return await response.arrayBuffer();
+    if (options.raw) return { data: await response.arrayBuffer(), etag, notModified: false };
     const body = await readJson(response);
-    return "data" in body ? body.data : body;
+    return { data: "data" in body ? body.data : body, etag, notModified: false };
   }
   buildUrl(path, query) {
     const url = new URL(`${this.baseUrl}${path}`);
@@ -281,21 +371,29 @@ var CatastroGPS = class {
     return error instanceof CatastroGPSError && error.status !== void 0 && RETRYABLE_STATUS.has(error.status);
   }
   retryDelayMs(error, attempt) {
-    if (error instanceof RateLimitError && error.retryAfterSeconds) return error.retryAfterSeconds * 1e3;
+    if ((error instanceof RateLimitError || error instanceof ServiceUnavailableError) && error.retryAfterSeconds) {
+      return Math.min(error.retryAfterSeconds, MAX_RETRY_AFTER_SECONDS) * 1e3;
+    }
     return BACKOFF_BASE_MS * 2 ** attempt;
   }
   captureQuota(headers) {
-    const limit = headers.get("X-RateLimit-Limit");
-    if (limit === null) return;
-    const remaining = headers.get("X-RateLimit-Remaining");
-    this.lastQuota = {
-      plan: headers.get("X-Quota-Tier") ?? void 0,
-      limit: Number(limit),
-      remaining: remaining === null ? void 0 : Number(remaining),
-      resetsAt: headers.get("X-RateLimit-Reset") ?? void 0
-    };
+    const quota = readQuota(headers);
+    if (quota) this.lastQuota = quota;
   }
 };
+function readQuota(headers) {
+  const plan = headers.get("X-Quota-Tier") ?? void 0;
+  const family = headers.has("X-Quota-Limit") ? "X-Quota" : plan ? "X-RateLimit" : void 0;
+  if (!family) return void 0;
+  const limit = headers.get(`${family}-Limit`);
+  const remaining = headers.get(`${family}-Remaining`);
+  return {
+    plan,
+    limit: limit === null ? void 0 : Number(limit),
+    remaining: remaining === null ? void 0 : Number(remaining),
+    resetsAt: headers.get(`${family}-Reset`) ?? void 0
+  };
+}
 async function readJson(response) {
   try {
     const parsed = await response.json();

package/dist/index.mjs

@@ -44,6 +44,7 @@ var RateLimitError = class extends CatastroGPSError {
 };
 var ServiceUnavailableError = class extends CatastroGPSError {
   name = "ServiceUnavailableError";
+  retryAfterSeconds;
 };
 var ServerError = class extends CatastroGPSError {
   name = "ServerError";
@@ -71,7 +72,11 @@ function errorFromResponse(status, body, retryAfter) {
   if (status === 403) return new ForbiddenError(message, options);
   if (status === 404) return new NotFoundError(message, options);
   if (status === 400 || status === 422) return new ValidationError(message, options);
-  if (status === 503) return new ServiceUnavailableError(message, options);
+  if (status === 503) {
+    const error = new ServiceUnavailableError(message, options);
+    error.retryAfterSeconds = retryAfter;
+    return error;
+  }
   if (status >= 500) return new ServerError(message, options);
   return new CatastroGPSError(message, options);
 }
@@ -134,8 +139,73 @@ function parcelPath(reference, suffix = "") {
   return `/api/catastro/${encodeURIComponent(reference.trim())}${suffix}`;
 }
 
+// src/resources/fincas.ts
+var MAX_PAGES = 1e3;
+var FincasResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async searchAddress(query) {
+    const params = typeof query === "string" ? { q: query } : query;
+    if (!params.q?.trim() && !params.street?.trim()) throw new CatastroGPSError("q or street is required");
+    return this.client.request("GET", "/api/search/address/candidates", {
+      query: {
+        q: params.q?.trim(),
+        street: params.street?.trim(),
+        number: params.number,
+        municipality: params.municipality?.trim(),
+        postcode: params.postcode?.trim(),
+        limit: params.limit
+      }
+    });
+  }
+  async *pages(refcat14, options = {}) {
+    const path = parcelPath(refcat14, "/units");
+    const previousByCursor = new Map((options.previous?.pages ?? []).map((page) => [page.cursor ?? "", page]));
+    let cursor;
+    for (let count = 0; count < MAX_PAGES; count += 1) {
+      const previous = previousByCursor.get(cursor ?? "");
+      const response = await this.client.conditionalRequest("GET", path, {
+        query: { cursor },
+        ifNoneMatch: previous?.etag
+      });
+      const data = response.notModified && previous ? previous.data : response.data;
+      if (!data) throw new CatastroGPSError("The API answered 304 for a page that was not in the previous import");
+      const page = { cursor, etag: response.etag, notModified: response.notModified, data };
+      yield page;
+      if (!data.truncated || !data.nextCursor) return;
+      cursor = data.nextCursor;
+    }
+    throw new CatastroGPSError(`Stopped after ${MAX_PAGES} pages`);
+  }
+  async units(refcat14, options = {}) {
+    const pages = [];
+    for await (const page of this.pages(refcat14, options)) pages.push(page);
+    const first = pages[0].data;
+    const last = pages[pages.length - 1].data;
+    return {
+      refCatastral: first.refCatastral,
+      direccion: first.direccion,
+      codigoPostal: first.codigoPostal,
+      municipio: first.municipio,
+      provincia: first.provincia,
+      usoGeneral: first.usoGeneral,
+      anioConstruccion: first.anioConstruccion,
+      totalUnidadesFinca: last.totalUnidadesFinca ?? pages.reduce((sum, p) => sum + p.data.unidades.length, 0),
+      unidades: pages.flatMap((page) => page.data.unidades),
+      construcciones: pages.flatMap((page) => page.data.construcciones ?? []),
+      dataSource: first.dataSource,
+      dataDate: first.dataDate,
+      attribution: first.attribution,
+      changed: !pages.every((page) => page.notModified) || pages.length !== (options.previous?.pages.length ?? -1),
+      pages
+    };
+  }
+};
+
 // src/version.ts
-var VERSION = "1.0.0";
+var VERSION = "1.1.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.catastrogps.es";
@@ -143,9 +213,12 @@ var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
 var BACKOFF_BASE_MS = 500;
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([502, 503, 504]);
+var NOT_MODIFIED = 304;
+var MAX_RETRY_AFTER_SECONDS = 60;
 var CatastroGPS = class {
   parcels;
   export;
+  fincas;
   lastQuota;
   apiKey;
   baseUrl;
@@ -170,11 +243,25 @@ var CatastroGPS = class {
     this.fetchImpl = fetchImpl;
     this.parcels = new ParcelsResource(this);
     this.export = new ExportResource(this);
+    this.fincas = new FincasResource(this);
+  }
+  async searchAddressCandidates(query) {
+    return this.fincas.searchAddress(query);
+  }
+  async getUnits(refcat14, options = {}) {
+    return this.fincas.units(refcat14, options);
+  }
+  iterUnitPages(refcat14, options = {}) {
+    return this.fincas.pages(refcat14, options);
   }
   async resolve(text, options = {}) {
     return this.request("GET", "/api/resolve", { query: { q: text, hint: options.hint } });
   }
   async request(method, path, options = {}) {
+    const result = await this.conditionalRequest(method, path, options);
+    return result.data;
+  }
+  async conditionalRequest(method, path, options = {}) {
     const url = this.buildUrl(path, options.query);
     let attempt = 0;
     for (; ; ) {
@@ -196,6 +283,7 @@ var CatastroGPS = class {
       "User-Agent": `catastrogps-js/${VERSION}`
     };
     if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    if (options.ifNoneMatch) headers["If-None-Match"] = options.ifNoneMatch;
     let response;
     try {
       response = await this.fetchImpl(url, {
@@ -213,14 +301,16 @@ var CatastroGPS = class {
       clearTimeout(timer);
     }
     this.captureQuota(response.headers);
+    const etag = response.headers.get("ETag") ?? void 0;
+    if (response.status === NOT_MODIFIED) return { etag: etag ?? options.ifNoneMatch, notModified: true };
     if (!response.ok) {
       const body2 = await readJson(response);
       const retryAfter = Number(response.headers.get("Retry-After"));
       throw errorFromResponse(response.status, body2, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0);
     }
-    if (options.raw) return await response.arrayBuffer();
+    if (options.raw) return { data: await response.arrayBuffer(), etag, notModified: false };
     const body = await readJson(response);
-    return "data" in body ? body.data : body;
+    return { data: "data" in body ? body.data : body, etag, notModified: false };
   }
   buildUrl(path, query) {
     const url = new URL(`${this.baseUrl}${path}`);
@@ -236,21 +326,29 @@ var CatastroGPS = class {
     return error instanceof CatastroGPSError && error.status !== void 0 && RETRYABLE_STATUS.has(error.status);
   }
   retryDelayMs(error, attempt) {
-    if (error instanceof RateLimitError && error.retryAfterSeconds) return error.retryAfterSeconds * 1e3;
+    if ((error instanceof RateLimitError || error instanceof ServiceUnavailableError) && error.retryAfterSeconds) {
+      return Math.min(error.retryAfterSeconds, MAX_RETRY_AFTER_SECONDS) * 1e3;
+    }
     return BACKOFF_BASE_MS * 2 ** attempt;
   }
   captureQuota(headers) {
-    const limit = headers.get("X-RateLimit-Limit");
-    if (limit === null) return;
-    const remaining = headers.get("X-RateLimit-Remaining");
-    this.lastQuota = {
-      plan: headers.get("X-Quota-Tier") ?? void 0,
-      limit: Number(limit),
-      remaining: remaining === null ? void 0 : Number(remaining),
-      resetsAt: headers.get("X-RateLimit-Reset") ?? void 0
-    };
+    const quota = readQuota(headers);
+    if (quota) this.lastQuota = quota;
   }
 };
+function readQuota(headers) {
+  const plan = headers.get("X-Quota-Tier") ?? void 0;
+  const family = headers.has("X-Quota-Limit") ? "X-Quota" : plan ? "X-RateLimit" : void 0;
+  if (!family) return void 0;
+  const limit = headers.get(`${family}-Limit`);
+  const remaining = headers.get(`${family}-Remaining`);
+  return {
+    plan,
+    limit: limit === null ? void 0 : Number(limit),
+    remaining: remaining === null ? void 0 : Number(remaining),
+    resetsAt: headers.get(`${family}-Reset`) ?? void 0
+  };
+}
 async function readJson(response) {
   try {
     const parsed = await response.json();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catastrogps",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Official JavaScript/TypeScript client for the Catastro GPS API: cadastral parcels in 31 European countries and regions by reference, coordinates or Spanish address",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",