---
title: "Address to parcel in Spain and 25 other European countries, with ranked candidates"
method: GET
path: "/api/search/address/candidates"
tags: ["Fincas"]
---

# Address to parcel in Spain and 25 other European countries, with ranked candidates

`GET /api/search/address/candidates`

## Request

- Base URL: `https://api.parcelgps.com`
- URL: `https://api.parcelgps.com/api/search/address/candidates`
- Auth: API key in header `X-API-Key`

Turns a postal address into cadastral parcels, ranked by `confianza` (0 to 1).

- **Spain** (default, `country=ES`): geocodes against CartoCiudad (Instituto Geográfico Nacional) and returns the building entrances (portales) that match, each with its 14-character cadastral reference. Does not depend on the Catastro being up. Candidates in the Basque Country (`pais: PV`) and Navarra (`pais: NA`) carry the foral reference.
- **Other countries** (`country=FR`, `IT`, `DE`, `AT`, `NL`, `BE`, `PL`, `CH`, `CZ`, `DK`, `NO`, `FI`, `EE`, `LV`, `LT`, `SI`, `SK`, `BG`, `GR`, `CY`, `LU`, `LI`, `IS`, `IE`, `UK`, `PT`): the address is geocoded with the official national address register where there is a free one (France: Base Adresse Nationale; Netherlands: PDOK Locatieserver; Switzerland: swisstopo; Poland: GUGiK; Czechia: RÚIAN; Estonia: In-ADS; Denmark: Dataforsyningen; Flanders: Digitaal Vlaanderen) and with OpenStreetMap (Photon, Nominatim as backup) elsewhere. The parcel under each address point comes from that country's official cadastre, the same source as `/search/coordinates`. In Italy streets and waters (`STRADA…`, `ACQUA…`) are never returned. Sweden and Croatia answer 422: their sources have no parcels at urban addresses.

Outside Spain `confianza` combines the geocoder score with whether the house number, the municipality (or postcode) and the street match: 0.75 or more means the number and the municipality match; when the geocoder only knows the street, `coincideNumero` is false and the parcel is one on that street. Use the reference with `GET /api/catastro/{refcat}` for the outline and area.

Costs 1 quota unit when it returns candidates; 404 (nothing found), 422 and 304 are free.

## Query parameters

- `country` 'ES' | 'FR' | 'IT' | 'DE' | 'AT' | 'NL' | 'BE' | 'PL' | 'CH' | 'CZ' | 'DK' | 'NO' | 'FI' | 'EE' | 'LV' | 'LT' | 'SI' | 'SK' | 'BG' | 'GR' | 'CY' | 'LU' | 'LI' | 'IS' | 'IE' | 'UK' | 'PT'
- `q` string
- `street` string
- `number` integer
- `municipality` string
- `postcode` string
- `limit` integer

## Headers

- `If-None-Match` string

## Response `200`

Candidates ordered by confidence (best first).

- AddressCandidatesResponse
  - `success` true, required
  - `data` object, required
    - `consulta` object, required: How the address was read.
      - `texto` string
      - `calle` string
      - `numero` integer
      - `municipio` string
      - `codigoPostal` string
    - `candidatos` AddressCandidate[], required
      - `refCatastral` string, required: Spain: 14-character finca reference in common territory, the foral reference in PV and NA. France: 14-character parcel IDU. Italy: particella reference (Belfiore code, sheet and number, e.g. `F839_019800.166`).
      - `pais` 'ES' | 'PV' | 'NA' | 'FR' | 'IT', required: ES: common territory, use the units endpoint. PV and NA: foral cadastre; list its units with GET /api/catastro/{refcat}/units?country=PV|NA. FR and IT: look the parcel up with GET /api/catastro/{refcat}?country=FR|IT.
      - `direccion` string, required: Spain: address as the IGN writes it. France and Italy: the normalised address the geocoder matched.
      - `numero` integer
      - `codigoPostal` string
      - `municipio` string, required
      - `provincia` string, required: Province (Spain), département (France) or province (Italy).
      - `latitud` number, required: Point of the address (entrance in Spain, address point in France and Italy).
      - `longitud` number, required
      - `confianza` number, required: 0.75 or more: number and municipality match.
      - `coincideNumero` boolean, required
      - `coincideMunicipio` boolean, required
      - `enCopia` boolean, required: The finca is in our copy of the Catastro (Spain only; always false in France and Italy).
      - `direccionCatastro` string: Address as the Catastro writes it (when enCopia).
      - `uso` string
      - `viviendas` integer: Dwellings the building declares (when enCopia).
      - `anioConstruccion` integer
    - `attribution` string, required

## 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`: The reference or address does not exist (code NOT_FOUND). Never used for outages.
- `422`: `country` is not one of ES, FR, IT (`CNV_COVERAGE`).
- `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)