catastrogps
v2.2.0
Published
Official JavaScript/TypeScript client for the Catastro GPS API: parcels from 29 European countries (including the Basque Country and Navarre foral cadastres) by reference, coordinates or address; building units, terrain, ground motion, solar and more
Maintainers
Readme
catastrogps
Official JavaScript and TypeScript client for the Catastro GPS API: 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.
- Import every unit of a Spanish building (dwellings, shops, garages) with paging and free
304refreshes. - Get the parcel outline (GeoJSON or a
[lat, lng]ring), and KML / GPX / DXF exports. - 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.
Install
npm install catastrogpsQuick 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.municipality, parcel.parcelArea, parcel.latitude, parcel.longitude);new CatastroGPS() with no arguments reads CATASTROGPS_API_KEY from the environment.
Methods
| Method | Endpoint | Countries |
|--------|----------|-----------|
| 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, DE, CZ, NL, FR, PT, SE, CH, FI, BE, IE, SI, EE, GR. 1 unit; 0 when there are none; 503 SUB_001 is not charged |
| parcels.sigpac(ref, { country, lang }) | GET /v1/parcels/{ref}/sigpac | ES, PV, NA. SIGPAC enclosures with land use, irrigation, slope, CAP eligibility, incidents and outline. 1 unit; 0 when there are none; 503 SIG_001 is not charged |
| parcels.sigpacGeoJSON(ref, { country, lang }) | GET /v1/parcels/{ref}/sigpac?format=geojson | The same as a GeoJSON FeatureCollection |
| 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 /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
const inWarsaw = await client.parcels.atPoint({ lat: 52.2297, lng: 21.0122 });
inWarsaw.reference;
inWarsaw.country;
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.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.groundMotion?.vertical.meanMmYear;
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;
const crops = await client.parcels.subparcels('46063A00100121', { lang: 'en' });
crops.subparcels[0].cropCode;
crops.subparcels[0].crop;
crops.subparcels[0].cropOriginal;
const sigpac = await client.parcels.sigpac('46063A00100121', { lang: 'en' });
sigpac.enclosures[0].landUseCode;
sigpac.enclosures[0].irrigationPct;
const collection = await client.parcels.sigpacGeoJSON('46063A00100121');
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 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 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.
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.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.reference, { previous: comunidad });
refreshed.changed;getUnitsfollowsnextCursorfor 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
previousto re-import: unchanged pages come back as304 Not Modified, cost nothing and are reused;changedtells 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 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
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:
import { AmbiguousReferenceError, CoverageError, NotFoundError, PlaceNameError, 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 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('Quota spent', error.quota?.resetsAt, error.prepaidBalanceEmpty);
} else {
throw error;
}
}| 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, 503 SUB_001 / 503 SIG_001 (subparcels or SIGPAC 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.
Options
| Option | Default | |
|--------|---------|---|
| apiKey | process.env.CATASTROGPS_API_KEY | Required |
| 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, 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 |
|------|------------------|:---:|:---:|:---:|-------|
| 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 | 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), the Go SDK and the MCP server for AI agents (catastro-gps-mcp).
License
MIT
