catastrogps

Official JavaScript and TypeScript 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.
• 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.

Install

npm install catastrogps

Quick start

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);

new CatastroGPS() with no arguments reads CATASTROGPS_API_KEY from the environment.

Examples

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 outline = await client.parcels.geometry('9872023VH5797S', { country: 'ES' });
outline.geojson;

const solar = await client.parcels.solar('9872023VH5797S0001WX');
solar.kwh_year;

const kml = await client.export.file('9872023VH5797S0001WX', 'kml');

const guess = await client.resolve('05102200100005');
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.

Importar una comunidad de propietarios (Spain)

Address → finca (14-character reference) → every unit, with use, area, participation coefficient, stair, floor and door.

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:

import { AmbiguousReferenceError, CoverageError, NotFoundError, QuotaExceededError } from 'catastrogps';

try {
  await client.parcels.get('05102200100005');
} catch (error) {
  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) {
    console.log(error.message);
  } else if (error instanceof QuotaExceededError) {
    console.log('Monthly quota used up');
  } 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. Only 2xx responses spend quota; failed attempts and 304 Not Modified are free.

Options

| Option | Default | | |--------|---------|---| | apiKey | process.env.CATASTROGPS_API_KEY | Required | | baseUrl | https://api.catastrogps.es | | | 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.

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 Python SDK (pip install catastrogps) and the MCP server for AI agents (catastro-gps-mcp).

License

MIT