---
title: "All units (dwellings, shops, garages, storage) of a finca"
method: GET
path: "/api/catastro/{refcat14}/units"
tags: ["Fincas"]
---

# All units (dwellings, shops, garages, storage) of a finca

`GET /api/catastro/{refcat14}/units`

## Request

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

Returns every unit of a finca, up to 200 per page, ordered by reference. Follow `nextCursor` while `truncated` is true. **Common territory (`ES`)**: pass the 14-character finca reference. Served from our copy of the Catastro (`dataSource: clone`); when the copy lacks the finca, or has fewer dwellings than the building declares, it is read live from the Catastro (`dataSource: catastro`). A finca that is a single property (a hotel, a detached house) is returned as one unit with its 20-character reference, and its building elements go in `construcciones`. **Basque Country (`PV`) and Navarra (`NA`)**: pass the foral reference of any unit of the building (Bizkaia: Número Fijo, e.g. `N0714723L`; Araba: 20-character CODETI; Gipuzkoa: Referen+N.Fijo+D, 15 characters; Navarra: 20-character reference starting with 31) or the finca key returned in `refCatastral` (municipio-polígono-parcela, e.g. `020-3-657` in Bizkaia, `59-0002-183` in Araba, `201-04-2651` in Navarra; in Gipuzkoa municipio+Referen). Units come from our copy of each foral cadastre (`dataSource: clone`, `dataDate` = publication of the source, `attribution` = the Diputación Foral or the Gobierno de Navarra). The foral open data carry no participation coefficient, so `participacion` is absent; Navarra and Araba carry stair, floor and door, Bizkaia floor and door, Gipuzkoa floor and door. A foral parcel without units (rústica, solar) is returned as one whole-property unit. Foral references and municipio-polígono-parcela keys are detected without `country`: a reference the detected foral copy does not hold is looked up in the other one (Navarra or the Basque Country). Gipuzkoa finca keys need `country=PV`. Costs one quota unit per unit served in the page (minimum 1), and the page is cut to what the quota and the prepaid balance still cover; a 304 on refresh is free. A per-finca cap is a per-contract condition agreed with specific customers, not part of any plan: organisations that have one pay at most that cap per finca and quota period across all its pages; see the `X-Quota-Finca-Cap*` headers. Requires an organisation API key or a signed-in user.

## Path parameters

- `refcat14` string, required

## Query parameters

- `cursor` string
- `country` 'ES' | 'PV' | 'NA'

## Headers

- `If-None-Match` string

## Response `200`

One page of units.

- UnitsResponse
  - `success` true, required
  - `data` UnitsPage, required
    - `refCatastral` string, required: ES: the 14-character finca reference. PV/NA: the finca key (municipio-polígono-parcela; Gipuzkoa urban: municipio+Referen); pass it back to list the same finca.
    - `direccion` string
    - `codigoPostal` string
    - `municipio` string
    - `provincia` string
    - `usoGeneral` string
    - `superficieTotal` integer: Sum of the unit areas in this page (m²).
    - `anioConstruccion` integer
    - `participacion` string: Finca-level coefficient as text; only meaningful for single-unit fincas. Use the per-unit number.
    - `totalUnidades` integer, required: Units in this page.
    - `totalUnidadesFinca` integer, required: Units in the whole finca.
    - `unidades` Unit[], required
      - `refCatastral` string, required: Unit reference: 20 characters in ES and NA; Número Fijo (Bizkaia), CODETI (Araba) or Referen+N.Fijo+D (Gipuzkoa) in PV.
      - `escalera` string, required
      - `planta` string, required: Floor as the cadastre writes it (01, 00 = ground floor, -1, SM = semi-basement, AT, OD = whole building…).
      - `puerta` string, required
      - `uso` string, required
      - `superficie` integer, required: Built area of the unit, m².
      - `descripcion` string, required
      - `participacion` number: Participation coefficient in %, full precision. Absent when the source does not have it (always absent in PV and NA).
      - `anio` integer
      - `direccion` string
    - `construcciones` Construction[]: Building elements of a single-property finca.
      - `escalera` string
      - `planta` string
      - `puerta` string
      - `uso` string
      - `superficie` integer
      - `descripcion` string
    - `truncated` boolean, required: More pages follow.
    - `nextCursor` string: Pass as `cursor` to get the next page.
    - `dataSource` 'clone' | 'catastro', required
    - `dataDate` string, date, required: Publication of the source the rows come from (clone; in PV/NA the date of the foral file) or the query date (catastro).
    - `attribution` string, required: Mandatory attribution: Dirección General del Catastro (ES), Diputación Foral de Álava / Bizkaia / Gipuzkoa (PV) or Gobierno de Navarra - Registro de la Riqueza Territorial (NA).
  - `searchesRemaining` integer: Daily web searches left; -1 for API keys.

## Other responses

- `304`: Unchanged since the ETag you sent. No body, no quota spent.
- `400`: Malformed parameters (code VALIDATION_ERROR).
- `401`: Missing, malformed or unknown API key (KEY_AUTH_001, KEY_AUTH_002, KEY_AUTH_003, UNAUTHORIZED).
- `404`: Finca not found in our copy (ES: neither in the Catastro). PV/NA: the reference is neither a foral unit, a foral parcel nor a finca key. 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)