npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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

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 304 refreshes.
  • 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 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.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;
  • 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 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