Documentação API
Referência completa da API cadastral
Base URL
https://api.parcelgps.comCó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.
Referência de endpoints
| Método | Endpoint | Auth | Descrição |
|---|---|---|---|
| GET | /api/resolve?q=TEXT | API Key | Classifica qualquer texto: referência (e país), coordenadas ou topónimo. Sem quota. |
| GET | /api/catastro/:refcat | API Key | Consulta de parcela |
| GET | /api/catastro/:refcat/polygon?country=XX | API Key | Geometria da parcela (GeoJSON) |
| GET | /api/catastro/:refcat/solar?country=XX | API Key | Potencial solar |
| GET | /api/catastro/:refcat/agro?country=XX | API Key | Dados agrícolas do solo |
| GET | /api/export/kml?refcat=X&country=X | API Key | Exportar KML/GPX/PDF/DXF |
| GET | /api/catastro/:refcat/market?country=XX | Web e app | Dados de mercado (não via API) |
| GET | /api/catastro/:refcat/score?country=XX | Web e app | Score 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.
| Endpoint | De 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/coordinates | Catastro (organismo público). Pode falhar sem aviso. |
| /agro | SIGPAC |
| /solar | PVGIS |
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
| Estado | Código | Descrição |
|---|---|---|
| 200 | — | OK — O pedido foi concluído com sucesso. |
| 400 | VALIDATION_ERROR | Bad Request — Parâmetros inválidos ou referência cadastral com formato incorreto. |
| 401 | UNAUTHORIZED | Unauthorized — API key inválida, expirada ou não fornecida. |
| 404 | NOT_FOUND | Not Found — Não foi encontrada a parcela com a referência ou coordenadas indicadas. Não gasta quota. |
| 429 | KEY_AUTH_004 | Quota Exceeded — Atingiu o limite mensal do seu plano. Consulte os cabeçalhos X-RateLimit-Remaining e X-RateLimit-Reset para saber quando é reiniciado. |
| 429 | RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | Too Many Requests — Limite de pesquisas gratuitas por IP e dia (tier gratuito). Com API key aplica-se a quota mensal do plano (acima). |
| 500 | INTERNAL_ERROR | Internal Server Error — Erro no nosso servidor. Se persistir, contacte o suporte. |
| 503 | SERVICE_UNAVAILABLE | Service 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çalho | Descrição |
|---|---|
| X-RateLimit-Limit | Limite mensal total do seu plano (p. ex. 5000). |
| X-RateLimit-Remaining | Chamadas restantes este mês. |
| X-RateLimit-Reset | Data de reinício da quota (ISO 8601). |
| X-Quota-Tier | Nome do tier atual (free, basic, pro, business). |
Espanha (ES)
Cadastro espanhol — Dirección General del Catastro
/api/catastro/:refcatObter dados de parcela por referência cadastral (14 ou 20 caracteres).
Parâmetros
| :refcat | string | Referê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ódigo | HTTP | Descrição |
|---|---|---|
| VALIDATION_ERROR | 400 | A referência não tem um formato válido para o país. |
| NOT_FOUND | 404 | Referê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_REACHED | 429 | Limite de pesquisas gratuitas por IP e dia. |
| KEY_AUTH_004 | 429 | Quota mensal da API key esgotada (ver cabeçalhos X-RateLimit-*). |
| SERVICE_UNAVAILABLE | 503 | O serviço cadastral oficial do país está em baixo ou em manutenção. Tente de novo. |
/api/search/coordinatesGeocodificação inversa: encontrar a parcela cadastral em coordenadas GPS.
Parâmetros
| latitude | number | Latitude (WGS84) |
| longitude | number | Longitude (WGS84) |
| country | string | Có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ódigo | HTTP | Descrição |
|---|---|---|
| VALIDATION_ERROR | 400 | Coordenadas fora dos limites do país indicado ou detetado, ou lat/lng ausentes ou mal formadas. |
| NOT_FOUND | 404 | Não existe nenhuma parcela nessas coordenadas. |
| RATE_LIMIT_EXCEEDED / DAILY_LIMIT_REACHED | 429 | Limite de pesquisas gratuitas por IP e dia. |
| SERVICE_UNAVAILABLE | 503 | Serviço cadastral temporariamente indisponível. |
/api/search/address/parsePesquisar parcela cadastral por morada.
Parâmetros
| direccion | string | Morada 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ódigo | HTTP | Descrição |
|---|---|---|
| VALIDATION_ERROR | 400 | Corpo do pedido inválido (faltam campos ou JSON mal formado). |
| NOT_FOUND | 404 | Morada 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_REACHED | 429 | Limite de pesquisas gratuitas por IP e dia. |
País Basco (PV)
Cadastros forais — Araba/Álava, Bizkaia e Gipuzkoa (WFS INSPIRE)
/api/catastro/:refcat?country=PVConsulta 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
| :refcat | string | Referência foral. Bizkaia com pontos (48.020.1611.02001); Álava e Gipuzkoa em dígitos (64010007, 8594149). |
| country | string | Obrigató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
/api/catastro/:refcat?country=PTObter dados de parcela portuguesa por referência cadastral.
Parâmetros
| :refcat | string | Referência cadastral portuguesa (p. ex. AAA000587359). A cobertura é parcial (~30 %); zonas como Lisboa e Porto ainda não estão digitalizadas pela DGT. |
| country | string | Obrigató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
/api/catastro/:refcat?country=FRObter dados de parcela francesa por referência cadastral.
Parâmetros
| :refcat | string | Referência cadastral francesa (p. ex. 75104000AE0003) |
| country | string | Obrigató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
/api/catastro/:refcat?country=ITObter dados de parcela italiana por referência cadastral.
Parâmetros
| :refcat | string | Referência catastale italiana (foglio/particella, p. ex. H501A048100.A) |
| country | string | Obrigató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)
/api/catastro/:refcat?country=DEObter dados de parcela alemã por referência cadastral.
Parâmetros
| :refcat | string | Referência cadastral alemã (Flurstückskennzeichen) |
| country | string | Obrigató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)
/api/catastro/:refcat?country=ATConsulta de parcela na Áustria. Requer country=AT. A referência é KATASTRALGEMEINDE-GRUNDSTÜCK. Cobertura parcial, em expansão.
Parâmetros
| :refcat | string | Formato Katastralgemeinde-Grundstück (p. ex. 01004-1711). |
| country | string | Obrigató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.
/api/catastro/:refcat/polygonObter o polígono GeoJSON de uma parcela.
Parâmetros
| :refcat | string | Referência cadastral |
| country | string | Có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"
}/api/catastro/:refcat/solarObter dados de potencial solar (PVGIS) de uma parcela europeia.
Parâmetros
| :refcat | string | Referência cadastral |
| country | string | Có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" }
}/api/catastro/:refcat/agroDados 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
| :refcat | string | Referência cadastral |
| country | string | Có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"
}/api/export/kml?refcat=:refcatExportar dados de parcela em formato KML (Google Earth).
Parâmetros
| refcat | string | Referência cadastral |
| country | string | Có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.kmlExemplo 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>/api/export/gpx?refcat=:refcatExportar dados de parcela em formato GPX (navegadores GPS).
Parâmetros
| refcat | string | Referência cadastral |
| country | string | Có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.gpxExemplo 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>