Documentação API

Referência completa da API cadastral

Base URL

https://api.parcelgps.com

Códigos de país

Os endpoints aceitam ?country=XX. É opcional: sem ele, a API deteta o país pela forma da referência em 21 países. Uma referência ambígua devolve 300 CNV_AMBIGUOUS com os candidatos; um país ainda sem cobertura, 422 CNV_COVERAGE; algo que parece um nome de lugar, 422 CNV_PLACE_NAME com o ponto geocodificado. A Espanha peninsular usa ES, mas o País Basco e Navarra têm cadastro próprio (foral) e exigem o seu próprio código: com ES as suas parcelas não são encontradas.

ES · EspanhaPV · País BascoNA · NavarraPT · PortugalFR · FrançaIT · ItáliaDE · AlemanhaAT · ÁustriaPL · PolandNL · NetherlandsCZ · CzechiaFI · FinlandBE · BelgiumEE · EstoniaSI · SloveniaLT · LithuaniaLU · LuxembourgSK · SlovakiaBG · BulgariaCY · ChipreIS · IslândiaLI · ListenstaineCH · Switzerland

Referência de endpoints

MétodoEndpointAuthDescrição
GET/api/resolve?q=TEXTAPI KeyClassifica qualquer texto: referência (e país), coordenadas ou topónimo. Sem quota.
GET/api/catastro/:refcatAPI KeyConsulta de parcela
GET/api/catastro/:refcat/polygon?country=XXAPI KeyGeometria da parcela (GeoJSON)
GET/api/catastro/:refcat/solar?country=XXAPI KeyPotencial solar
GET/api/catastro/:refcat/agro?country=XXAPI KeyDados agrícolas do solo
GET/api/export/kml?refcat=X&country=XAPI KeyExportar KML/GPX/PDF/DXF
GET/api/catastro/:refcat/market?country=XXWeb e appDados de mercado (não via API)
GET/api/catastro/:refcat/score?country=XXWeb e appScore de investimento (não via API)

Fiabilidade

O que servimos a partir da nossa própria infraestrutura e o que depende de um organismo público. Vale a pena ler antes de ir para produção.

EndpointDe onde vêm os dados
/catastro/:refcat (ES)Cópia própria do cadastro (50,9 M de parcelas). Não depende do Catastro para responder.
/polygon · /search/address · /search/coordinatesCatastro (organismo público). Pode falhar sem aviso.
/agroSIGPAC
/solarPVGIS

Erros e novas tentativas

Um 503 significa que uma fonte oficial não responde neste momento: tente de novo com espera crescente e resolve-se sozinho. Um 429 é a sua quota, e repetir não a devolve — aguarde o reinício ou mude de plano. Um 404 é uma referência que não existe e não deve ser repetida.

Página de estado

Publicamos o estado da nossa API e das nove fontes cadastrais de que dependemos, verificado a cada cinco minutos e alojado fora desta API para continuar fiável durante uma falha: catastrogps.es/status.

Autenticação

Todas as chamadas à API requerem uma API key enviada no cabeçalho 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

EstadoCódigoDescrição
200—OK — O pedido foi concluído com sucesso.
400VALIDATION_ERRORBad Request — Parâmetros inválidos ou referência cadastral com formato incorreto.
401UNAUTHORIZEDUnauthorized — API key inválida, expirada ou não fornecida.
404NOT_FOUNDNot Found — Não foi encontrada a parcela com a referência ou coordenadas indicadas. Não gasta quota.
429KEY_AUTH_004Quota Exceeded — Atingiu o limite mensal do seu plano. Consulte os cabeçalhos X-RateLimit-Remaining e X-RateLimit-Reset para saber quando é reiniciado.
429RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHEDToo Many Requests — Limite de pesquisas gratuitas por IP e dia (tier gratuito). Com API key aplica-se a quota mensal do plano (acima).
500INTERNAL_ERRORInternal Server Error — Erro no nosso servidor. Se persistir, contacte o suporte.
503SERVICE_UNAVAILABLEService Unavailable — O serviço cadastral externo do país consultado está temporariamente indisponível. Estes serviços são geridos por organismos públicos (Catastro, DGT, Géoportail, Agenzia Entrate, ALKIS...) e estão fora do nosso controlo. Tente de novo dentro de alguns minutos.

Cabeçalhos de rate limit

Cada resposta inclui cabeçalhos que indicam o estado da sua quota:

CabeçalhoDescrição
X-RateLimit-LimitLimite mensal total do seu plano (p. ex. 5000).
X-RateLimit-RemainingChamadas restantes este mês.
X-RateLimit-ResetData de reinício da quota (ISO 8601).
X-Quota-TierNome do tier atual (free, basic, pro, business).

Espanha (ES)

Cadastro espanhol — Dirección General del Catastro

GET/api/catastro/:refcat

Obter dados de parcela por referência cadastral (14 ou 20 caracteres).

Parâmetros

:refcatstringReferência cadastral (p. ex. 9872023VH5797S0001WX)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S0001WX"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "9872023VH5797S0001WX",
    "direccion": "CL GLORIA 51",
    "codigoPostal": "13730",
    "municipio": "SANTA CRUZ DE MUDELA",
    "provincia": "CIUDAD REAL",
    "latitud": 38.640143,
    "longitud": -3.463284,
    "googleMapsUrl": "https://www.google.com/maps?q=38.640143,-3.463284",
    "uso": "Residencial",
    "clase": "Urbano",
    "superficieConstruida": 308,
    "superficieParcela": 397,
    "anioConstruccion": 1980,
    "coefParticipacion": "100",
    "poligono": [ /* geometría de la parcela */ ],
    "availableFields": {
      "uso": true, "clase": true, "anioConstruccion": true,
      "superficieConstruida": true, "coefParticipacion": true,
      "direccion": true, "busquedaDireccion": true
    }
  },
  "searchesRemaining": 4
}

Erros possíveis

CódigoHTTPDescrição
VALIDATION_ERROR400A referência não tem um formato válido para o país.
NOT_FOUND404Referência não encontrada. Um ?country não suportado é tratado como Espanha (ES) e normalmente devolve NOT_FOUND; use ES/PT/FR/IT/DE/PV/NA. Em cadastros forais (NA, PV) o campo message acrescenta uma dica de formato.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Limite de pesquisas gratuitas por IP e dia.
KEY_AUTH_004429Quota mensal da API key esgotada (ver cabeçalhos X-RateLimit-*).
SERVICE_UNAVAILABLE503O serviço cadastral oficial do país está em baixo ou em manutenção. Tente de novo.
POST/api/search/coordinates

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

Parâmetros

latitudenumberLatitude (WGS84)
longitudenumberLongitude (WGS84)
countrystringCódigo de país (opcional: detetado pela referência)
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"

Exemplo de resposta

200 OK
{
  "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
}

Erros possíveis

CódigoHTTPDescrição
VALIDATION_ERROR400Coordenadas fora dos limites do país indicado ou detetado, ou lat/lng ausentes ou mal formadas.
NOT_FOUND404Não existe nenhuma parcela nessas coordenadas.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Limite de pesquisas gratuitas por IP e dia.
SERVICE_UNAVAILABLE503Serviço cadastral temporariamente indisponível.
POST/api/search/address/parse

Pesquisar parcela cadastral por morada.

Parâmetros

direccionstringMorada em texto livre (apenas Espanha). Formato recomendado: «Calle, Número, Municipio» — p. ex. «Calle Mallorca, 213, Barcelona». O número também pode ir junto à rua («Gran Vía 1, Madrid»).
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"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "referenciaCatastral": "0847106VK4704F",
    "refCat14": "0847106VK4704F",
    "direccion": "CL GRAN VIA, 1, Madrid",
    "tipoVia": "CL",
    "nombreVia": "GRAN VIA",
    "numero": 1,
    "municipio": "Madrid",
    "provincia": "MADRID"
  },
  "searchesRemaining": -1
}

Erros possíveis

CódigoHTTPDescrição
VALIDATION_ERROR400Corpo do pedido inválido (faltam campos ou JSON mal formado).
NOT_FOUND404Morada não encontrada (rua, município ou número inexistente ou sem correspondência cadastral). A pesquisa por morada só está disponível em Espanha.
RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED429Limite de pesquisas gratuitas por IP e dia.

País Basco (PV)

Cadastros forais — Araba/Álava, Bizkaia e Gipuzkoa (WFS INSPIRE)

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

Consulta de parcela nos três territórios forais. Requer country=PV: as suas parcelas têm cadastro próprio e não estão no Catastro central.

Parâmetros

:refcatstringReferência foral. Bizkaia com pontos (48.020.1611.02001); Álava e Gipuzkoa em dígitos (64010007, 8594149).
countrystringObrigatório: PV.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/48.020.1611.02001?country=PV"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "48.020.1611.02001",
    "pais": "PV",
    "municipio": "Bizkaia",
    "provincia": "Bizkaia",
    "latitud": 43.263633,
    "longitud": -2.935856,
    "superficieParcela": 3061,
    "googleMapsUrl": "https://www.google.com/maps?q=43.263633,-2.935856",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Com country=ES (incorreto)

404
{
  "success": false,
  "error": "Parcela no encontrado: 48.020.1611.02001",
  "code": "NOT_FOUND"
}

Portugal (PT)

Cadastro português — Direção-Geral do Território

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

Obter dados de parcela portuguesa por referência cadastral.

Parâmetros

:refcatstringReferência cadastral portuguesa (p. ex. AAA000587359). A cobertura é parcial (~30 %); zonas como Lisboa e Porto ainda não estão digitalizadas pela DGT.
countrystringObrigatório: PT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/AAA000587359?country=PT"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "AAA000587359",
    "pais": "PT",
    "municipio": "TAVIRA, Tavira (Santa Maria e Santiago)",
    "latitud": 37.127156,
    "longitud": -7.648066,
    "superficieParcela": 49,
    "googleMapsUrl": "https://www.google.com/maps?q=37.127156,-7.648066",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

França (FR)

Cadastro francês — Cadastre / Géoplateforme

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

Obter dados de parcela francesa por referência cadastral.

Parâmetros

:refcatstringReferência cadastral francesa (p. ex. 75104000AE0003)
countrystringObrigatório: FR.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/75104000AE0003?country=FR"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "75104000AE0003",
    "pais": "FR",
    "municipio": "Paris",
    "provincia": "75",
    "latitud": 48.856347,
    "longitud": 2.352415,
    "superficieParcela": 15168,
    "googleMapsUrl": "https://www.google.com/maps?q=48.856347,2.352415",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Itália (IT)

Cadastro italiano — Agenzia delle Entrate

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

Obter dados de parcela italiana por referência cadastral.

Parâmetros

:refcatstringReferência catastale italiana (foglio/particella, p. ex. H501A048100.A)
countrystringObrigatório: IT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/H501A048100.A?country=IT"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "H501A048100.A",
    "pais": "IT",
    "municipio": "H501",
    "provincia": "H501",
    "latitud": 41.902698,
    "longitud": 12.496247,
    "superficieParcela": 1059,
    "googleMapsUrl": "https://www.google.com/maps?q=41.902698,12.496247",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Alemanha (DE)

Cadastro alemão — ALKIS (8 Bundesländer)

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

Obter dados de parcela alemã por referência cadastral.

Parâmetros

:refcatstringReferência cadastral alemã (Flurstückskennzeichen)
countrystringObrigatório: DE.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/05495803101122?country=DE"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "05495803101122",
    "pais": "DE",
    "latitud": 50.937566,
    "longitud": 6.960140,
    "superficieParcela": 54,
    "googleMapsUrl": "https://www.google.com/maps?q=50.937566,6.960140",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Áustria (AT)

Cadastro austríaco — BEV (Katastralgemeinde / Grundstück)

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

Consulta de parcela na Áustria. Requer country=AT. A referência é KATASTRALGEMEINDE-GRUNDSTÜCK. Cobertura parcial, em expansão.

Parâmetros

:refcatstringFormato Katastralgemeinde-Grundstück (p. ex. 01004-1711).
countrystringObrigatório: AT.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/01004-1711?country=AT"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "refCatastral": "01004-1711",
    "pais": "AT",
    "municipio": "Innere Stadt",
    "provincia": "Wien",
    "latitud": 48.208478,
    "longitud": 16.372810,
    "uso": "Gebäude, Straßenverkehrsanlagen",
    "superficieParcela": 10641,
    "googleMapsUrl": "https://www.google.com/maps?q=48.208478,16.372810",
    "poligono": [ /* geometría de la parcela */ ]
  }
}

Com country=ES (incorreto)

400
{
  "success": false,
  "error": "La referencia catastral debe tener al menos 14 caracteres",
  "code": "VALIDATION_ERROR"
}

Inteligência de parcela e exportações

Geometria, potencial solar, dados agrícolas e exportação de ficheiros (KML/GPX/PDF/DXF), disponíveis com a sua API key. Os dados de mercado e o score de investimento ficam na web e na app (Pro) e não são expostos via API.

GET/api/catastro/:refcat/polygon

Obter o polígono GeoJSON de uma parcela.

Parâmetros

:refcatstringReferência cadastral
countrystringCódigo de país (parâmetro de query, predefinição: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/polygon"

Exemplo de resposta

200 OK
{
  "data": {
    "refcat": "9872023VH5797S",
    "geojson": {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [ [ [-3.463391, 38.640317], [-3.463174, 38.640217], /* ... */ ] ]
      }
    }
  }
}

Quota mensal esgotada

429
{
  "success": false,
  "error": "Cuota mensual agotada (5000/5000). Upgrade en https://catastrogps.es/developers",
  "code": "KEY_AUTH_004"
}
GET/api/catastro/:refcat/solar

Obter dados de potencial solar (PVGIS) de uma parcela europeia.

Parâmetros

:refcatstringReferência cadastral
countrystringCódigo de país (parâmetro de query, predefinição: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/9872023VH5797S/solar"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "kwh_year": 23749.9,
    "kw_instalables": 17.86,
    "ahorro_anual_eur": 3562.49,
    "amortizacion_anos": 5,
    "co2_evitado_kg": 5533.73,
    "irradiacion_media": 1807.08,
    "nota_solar": 5,
    "orientacion_optima": "Sur",
    "angulo_inclinacion": 34,
    "costo_instalacion_eur": 17865,
    "disponible": true,
    "estado": "ok",
    "fuente": "PVGIS (JRC)",
    "economics": {
      "autoconsumo_kwh_ano": 5000,
      "excedentes_kwh_ano": 18749.9,
      "ingreso_neto_anual_eur": 1473.18,
      "payback_anos": 12.13,
      "tir_pct": 6.56,
      "retorno_total_25_anos_eur": 18964.5
    }
  }
}

Parcela sem dados solares

200
{
  "success": true,
  "data": { "disponible": false, "estado": "sin_datos" }
}
GET/api/catastro/:refcat/agro

Dados agrícolas do solo de uma parcela (SIGPAC): cultura principal, uso do solo, declive, altitude e área. Apenas parcelas rústicas — as urbanas devolvem "cultivo_principal": "urbano".

Parâmetros

:refcatstringReferência cadastral
countrystringCódigo de país (parâmetro de query, predefinição: ES)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/catastro/23058A00700036/agro"

Exemplo de resposta

200 OK
{
  "success": true,
  "data": {
    "agro": {
      "cultivo_principal": "olivar",
      "uso_suelo": "Asociación olivar - viñedo",
      "superficie_ha": 10.6045,
      "coef_regadio": 1,
      "ndvi": {
        "valor_medio": 0.18,
        "salud_cultivo": "bajo",
        "ultima_actualizacion": "2026-06-18T00:00:00Z"
      },
      "precios_mercado": {
        "precio_kg": 8.5,
        "tendencia": "+12.5% vs periodo anterior"
      },
      "recinto": {
        "provincia": 23,
        "municipio": 58,
        "poligono": 7,
        "parcela": 36,
        "recinto": 1,
        "altitud": 559,
        "pendiente_media": 12.3
      }
    }
  }
}

Quota mensal esgotada

429
{
  "success": false,
  "error": "Cuota mensual agotada (5000/5000). Upgrade en https://catastrogps.es/developers",
  "code": "KEY_AUTH_004"
}
GET/api/export/kml?refcat=:refcat

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

Parâmetros

refcatstringReferência cadastral
countrystringCódigo de país (opcional: detetado pela referência)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/kml?refcat=9872023VH5797S" -o parcel.kml

Exemplo de resposta

200 OK
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <name>9872023VH5797S</name>
      ...
    </Placemark>
  </Document>
</kml>
GET/api/export/gpx?refcat=:refcat

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

Parâmetros

refcatstringReferência cadastral
countrystringCódigo de país (opcional: detetado pela referência)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parcelgps.com/api/export/gpx?refcat=9872023VH5797S" -o parcel.gpx

Exemplo de resposta

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