---
title: "Parcel or unit by cadastral reference"
method: GET
path: "/api/catastro/{refcat}"
tags: ["Parcels"]
---

# Parcel or unit by cadastral reference

`GET /api/catastro/{refcat}`

## Request

- Base URL: `https://api.parcelgps.com`
- URL: `https://api.parcelgps.com/api/catastro/{refcat}`
- Auth: API key in header `X-API-Key`

With a 20-character Spanish reference it returns that unit (dwelling), with the same per-unit fields as the units list: `uso`, `participacion` (number, %), `escalera`, `planta`, `puerta`. `superficieConstruida` here is `superficie` in the units list. The country is detected from the reference format unless `country` is given. Costs 1 quota unit.

## Path parameters

- `refcat` string, required

## Query parameters

- `country` string

## Response `200`

The parcel or unit.

- ParcelResponse
  - `success` true, required
  - `data` Parcel, required
    - `dataSource` string: `local_clone` when it came from our copy.
    - `refCatastral` string, required
    - `pais` string
    - `direccion` string
    - `codigoPostal` string
    - `municipio` string
    - `provincia` string
    - `latitud` number, required
    - `longitud` number, required
    - `googleMapsUrl` string, required
    - `uso` string
    - `clase` string
    - `superficieConstruida` integer: Built area (m²). Same value as `superficie` in the units list.
    - `superficieParcela` integer: Plot area (m²).
    - `anioConstruccion` integer
    - `coefParticipacion` string: Coefficient rounded to 2 decimals, as text. Kept for compatibility; use `participacion`.
    - `participacion` number: Participation coefficient in %, full precision (20-character references).
    - `escalera` string
    - `planta` string
    - `puerta` string
    - `viviendas` integer
    - `plantas` integer
    - `poligono` array[]: Outline as [lat, lng] pairs.
      - number[]
    - `availableFields` object
    - `poligonoCatastral` string: Spain, rustic parcels: cadastral polygon number (not the outline, which is `poligono`).
    - `parcelaCatastral` string: Spain, rustic parcels: parcel number inside the cadastral polygon.
    - `paraje` string: Spain, rustic parcels: place name (paraje) recorded by the Catastro.
    - `subparcelas` Subparcela[]: Spain, rustic parcels: crop subparcels (subparcelas de cultivo) recorded by the Catastro.
      - `subparcela` string, required: Subparcel letter, e.g. `a`.
      - `cultivo` string: Crop or use, e.g. `Labor secano`.
      - `calificacion` string: Catastro crop code, e.g. `C-` or `MB`.
      - `intensidad` integer: Productive intensity class.
      - `superficie` integer, required: Area (m²).
      - `geometria` object: GeoJSON MultiPolygon (EPSG:4326) of the subparcel, from the Catastro rustic cartography (SUBPARCE layer). Omitted while the subparcel's municipality has no cartography loaded.
        - `type` 'MultiPolygon'
        - `coordinates` unknown[]
          - unknown
  - `searchesRemaining` integer

## Other responses

- `300`: CNV_AMBIGUOUS: bare digits that could be a reference of several countries. `data.candidates` lists them; repeat with `?country=`. Free.
- `400`: Malformed parameters (code VALIDATION_ERROR).
- `401`: Missing, malformed or unknown API key (KEY_AUTH_001, KEY_AUTH_002, KEY_AUTH_003, UNAUTHORIZED).
- `404`: The reference or address does not exist (code NOT_FOUND). Never used for outages.
- `422`: CNV_COVERAGE: the reference belongs to a country without coverage (`data.country`). CNV_PLACE_NAME: the text is a place name, not a reference. Free.
- `429`: KEY_AUTH_004: monthly quota used up and no prepaid balance left to cover the request (see X-Quota-*); nothing is charged. The message says the plan, the price per 1,000 extra units, where to top up and when the quota resets. KEY_RATE_002 or RATE_LIMIT_EXCEEDED: per-minute limit, wait Retry-After seconds.
- `503`: The official source of that country is down or saturated and our copy cannot answer (code SERVICE_UNAVAILABLE). Retry after Retry-After seconds. Free.

---

[API](https://skmtc.dev/catastrogps/apis/catastro-gps-api.md) · [All operations](https://skmtc.dev/catastrogps/apis/catastro-gps-api/llms.txt) · [OpenAPI document](https://skmtc.dev/catastrogps/apis/catastro-gps-api/revisions/1a86d44aa8ae?raw)