Documentação API

Referencia completa da API cadastral

Base URL

https://api.parcelgps.com

Referencia de endpoints

Método	Endpoint	Auth	Descripción
GET	/api/catastro/:refcat?country=XX	API Key	Parcel lookup
GET	/api/catastro/:refcat/solar?country=XX	API Key + Pro	Solar potential
GET	/api/catastro/:refcat/agro?country=XX	API Key + Pro	Agricultural data
GET	/api/catastro/:refcat/market?country=XX	API Key + Pro	Market data
GET	/api/catastro/:refcat/score?country=XX	API Key + Pro	Investment score
POST	/api/catastro/compare	API Key + Pro	Compare parcels
GET	/api/export/kml?refcat=X&country=X	API Key + Pro	Export KML/GPX/PDF

Autenticação

Todas as chamadas a API requerem uma API key enviada no cabecalho X-API-Key.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S"

Obtenha a sua API key gratuita em o seu painel de desenvolvedor.

Códigos de erro

Status	Code	Descrição
200	—	OK — La petición se ha completado correctamente.
400	VALIDATION_ERROR	Bad Request — Parámetros inválidos o referencia catastral con formato incorrecto.
401	UNAUTHORIZED	Unauthorized — API key inválida, expirada o no proporcionada.
404	NOT_FOUND	Not Found — No se encontró la parcela con la referencia o coordenadas indicadas.
429	KEY_AUTH_004	Quota Exceeded — Has alcanzado el límite mensual de tu plan. Comprueba las cabeceras `X-RateLimit-Remaining` y `X-RateLimit-Reset` para saber cuándo se reinicia.
500	INTERNAL_ERROR	Internal Server Error — Error en nuestro servidor. Si persiste, contacta soporte.
503	SERVICE_UNAVAILABLE	Service Unavailable — El servicio catastral externo del país consultado no está disponible temporalmente. Estos servicios son gestionados por organismos públicos (Catastro, DGT, Géoportail, Agenzia Entrate, ALKIS...) y están fuera de nuestro control. Reintenta en unos minutos.

Cabeceras de rate limit

Cada respuesta incluye cabeceras que indican el estado de tu quota:

Header	Descrição
X-RateLimit-Limit	Límite mensual total de tu plan (ej: 5000).
X-RateLimit-Remaining	Llamadas restantes este mes.
X-RateLimit-Reset	Fecha de reinicio de la quota (ISO 8601).
X-Quota-Tier	Nombre del tier actual (free, basic, pro, business).

Spain (ES)

Spanish Cadastre — Direccion General del Catastro

GET/api/catastro/:refcat

Obter dados de parcela por referencia cadastral (14 ou 20 caracteres).

Parametros

:refcat

string

Cadastral reference (e.g. 9872023VH5797S0001WX)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX"

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data);

Exemplo de resposta

{
  "success": true,
  "data": {
    "refCatastral": "9872023VH5797S0001WX",
    "pais": "ES",
    "direccion": "CL GRAN VIA 1",
    "codigoPostal": "28013",
    "municipio": "MADRID",
    "provincia": "MADRID",
    "latitud": 40.4168,
    "longitud": -3.7038,
    "googleMapsUrl": "https://maps.google.com/?q=40.4168,-3.7038",
    "uso": "Residencial",
    "clase": "Urbana",
    "superficieConstruida": 125,
    "superficieParcela": 200,
    "anioConstruccion": 1920,
    "coefParticipacion": "12.50",
    "poligono": [[-3.704, 40.416], [-3.703, 40.416], ...],
    "availableFields": {
      "uso": true, "clase": true, "anioConstruccion": true,
      "superficieConstruida": true, "coefParticipacion": true,
      "direccion": true, "busquedaDireccion": true
    }
  },
  "searchesRemaining": 4
}

Experimentar ao vivo

POST/api/search/coordinates

Geocodificação inversa: encontrar a parcela cadastral em coordenadas GPS.

Parametros

latitude	number	Latitude (WGS84)
longitude	number	Longitude (WGS84)
country	string	Country code (default: ES)

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 40.4168, "longitude": -3.7038, "country": "ES"}' \
  "https://api.parcelgps.com/api/search/coordinates"

import requests

resp = requests.post(
    "https://api.parcelgps.com/api/search/coordinates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"latitude": 40.4168, "longitude": -3.7038, "country": "ES"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/search/coordinates",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ latitude: 40.4168, longitude: -3.7038, country: "ES" })
  }
);
const data = await res.json();

Exemplo de resposta

{
  "success": true,
  "data": {
    "referenciaCatastral": "9872023VH5797S0001WX",
    "refCat14": "9872023VH5797S",
    "direccion": "CL GRAN VIA 1",
    "municipio": "MADRID",
    "tipoInmueble": "",
    "coordenadas": { "latitud": 40.4168, "longitud": -3.7038 },
    "googleMapsUrl": "https://maps.google.com/?q=40.4168,-3.7038"
  },
  "searchesRemaining": 3
}

Experimentar ao vivo

POST/api/search/address/parse

Pesquisar parcela cadastral por morada.

Parametros

direccion

string

Free-text address (Spain only)

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direccion": "Gran Via 1, Madrid"}' \
  "https://api.parcelgps.com/api/search/address/parse"

import requests

resp = requests.post(
    "https://api.parcelgps.com/api/search/address/parse",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"direccion": "Gran Via 1, Madrid"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/search/address/parse",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ direccion: "Gran Via 1, Madrid" })
  }
);
const data = await res.json();

Exemplo de resposta

{
  "success": true,
  "data": {
    "referenciaCatastral": "9872023VH5797S0001WX",
    "direccion": "CL GRAN VIA 1",
    "municipio": "MADRID",
    "provincia": "MADRID"
  },
  "searchesRemaining": 2
}

Experimentar ao vivo

Portugal (PT)

Portuguese Cadastre — Direcao-Geral do Territorio

GET/api/catastro/:refcat?country=PT

Obter dados de parcela portuguesa por referencia cadastral.

Parametros

:refcat	string	Portuguese cadastral reference (NIP)
country	string	Must be "PT"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/U0512N0003200?country=PT"

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/catastro/U0512N0003200",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"country": "PT"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/catastro/U0512N0003200?country=PT",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Exemplo de resposta

{
  "success": true,
  "data": {
    "refCatastral": "U0512N0003200",
    "pais": "PT",
    "latitud": 38.7223,
    "longitud": -9.1393,
    "googleMapsUrl": "https://maps.google.com/?q=38.7223,-9.1393",
    "municipio": "LISBOA",
    "superficieParcela": 450,
    "poligono": [[-9.14, 38.72], ...]
  },
  "searchesRemaining": 4
}

Experimentar ao vivo

France (FR)

French Cadastre — Cadastre / Geoplateforme

GET/api/catastro/:refcat?country=FR

Obter dados de parcela francesa por referencia cadastrale.

Parametros

:refcat	string	French cadastral reference (e.g. 750560000AB0001)
country	string	Must be "FR"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/750560000AB0001?country=FR"

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/catastro/750560000AB0001",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"country": "FR"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/catastro/750560000AB0001?country=FR",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Exemplo de resposta

{
  "success": true,
  "data": {
    "refCatastral": "750560000AB0001",
    "pais": "FR",
    "latitud": 48.8566,
    "longitud": 2.3522,
    "googleMapsUrl": "https://maps.google.com/?q=48.8566,2.3522",
    "municipio": "PARIS",
    "provincia": "Paris",
    "superficieParcela": 320,
    "poligono": [[2.35, 48.85], ...]
  },
  "searchesRemaining": 4
}

Experimentar ao vivo

Italy (IT)

Italian Cadastre — Agenzia delle Entrate

GET/api/catastro/:refcat?country=IT

Obter dados de parcela italiana por referencia catastale.

Parametros

:refcat	string	Italian cadastral reference
country	string	Must be "IT"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/A0420001?country=IT"

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/catastro/A0420001",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"country": "IT"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/catastro/A0420001?country=IT",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Exemplo de resposta

{
  "success": true,
  "data": {
    "refCatastral": "A0420001",
    "pais": "IT",
    "latitud": 41.9028,
    "longitud": 12.4964,
    "googleMapsUrl": "https://maps.google.com/?q=41.9028,12.4964",
    "municipio": "ROMA",
    "superficieParcela": 180,
    "poligono": [[12.49, 41.90], ...]
  },
  "searchesRemaining": 4
}

Experimentar ao vivo

Germany (DE)

German Cadastre — ALKIS (8 Bundesländer)

GET/api/catastro/:refcat?country=DE

Obter dados de parcela alema (NRW) por referencia cadastral.

Parametros

:refcat	string	German cadastral reference (Flurstückskennzeichen)
country	string	Must be "DE"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/05315000200001?country=DE"

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/catastro/05315000200001",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"country": "DE"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/catastro/05315000200001?country=DE",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Exemplo de resposta

{
  "success": true,
  "data": {
    "refCatastral": "05315000200001",
    "pais": "DE",
    "latitud": 50.9375,
    "longitud": 6.9603,
    "googleMapsUrl": "https://maps.google.com/?q=50.9375,6.9603",
    "municipio": "KÖLN",
    "superficieParcela": 520,
    "poligono": [[6.96, 50.93], ...]
  },
  "searchesRemaining": 4
}

Experimentar ao vivo

Polygon / Solar / Export

Endpoints adicionais (requerem plano Pro ou superior).

GET/api/catastro/:refcat/polygon

Obter o poligono GeoJSON de uma parcela.

Parametros

:refcat	string	Cadastral reference
country	string	Country code (query param, default: ES)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon"

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Exemplo de resposta

{
  "success": true,
  "data": {
    "refCatastral": "9872023VH5797S",
    "pais": "ES",
    "latitud": 40.4168,
    "longitud": -3.7038,
    "poligono": [[-3.704, 40.416], [-3.703, 40.416], ...]
  },
  "searchesRemaining": 4
}

Experimentar ao vivo

GET/api/catastro/:refcat/solar

Obter dados de potêncial solar (PVGIS) de uma parcela europeia.

Parametros

:refcat	string	Cadastral reference
country	string	Country code (query param, default: ES)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar"

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(resp.json())

const res = await fetch(
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Exemplo de resposta

{
  "success": true,
  "data": {
    "kwh_year": 4200.0,
    "kw_instalables": 3.5,
    "ahorro_anual_eur": 680.0,
    "amortizacion_anos": 8.5,
    "co2_evitado_kg": 1890.0,
    "irradiacion_media": 1650.5,
    "nota_solar": 4,
    "disponible": true,
    "estado": "ok"
  }
}

Experimentar ao vivo

GET/api/export/kml?refcat=:refcat

Exportar dados de parcela em formato KML (Google Earth).

Parametros

refcat	string	Cadastral reference
country	string	Country code (default: ES)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kml

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/export/kml",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"refcat": "9872023VH5797S"}
)
with open("parcel.kml", "wb") as f:
    f.write(resp.content)

const res = await fetch(
  "https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const blob = await res.blob();

Exemplo de resposta

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <name>9872023VH5797S</name>
      ...
    </Placemark>
  </Document>
</kml>

Experimentar ao vivo

GET/api/export/gpx?refcat=:refcat

Exportar dados de parcela em formato GPX (navegadores GPS).

Parametros

refcat	string	Cadastral reference
country	string	Country code (default: ES)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpx

import requests

resp = requests.get(
    "https://api.parcelgps.com/api/export/gpx",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"refcat": "9872023VH5797S"}
)
with open("parcel.gpx", "wb") as f:
    f.write(resp.content)

const res = await fetch(
  "https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const blob = await res.blob();

Exemplo de resposta

<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1">
  <wpt lat="40.4168" lon="-3.7038">
    <name>9872023VH5797S</name>
  </wpt>
</gpx>

Experimentar ao vivo