API CÓDIGOS POSTAIS

Métodos disponíveis

Consulte dados postais e geográficos, calcule distâncias e encontre uma ordem eficiente para as suas paragens.

Autenticação obrigatória

Envie Authorization: Bearer CHAVE_API em todos os métodos desta página. Consulte a introdução para mais detalhes.

Formato dos códigos postais

Pode enviar o código postal com ou sem hífen: 2590432 e 2590-432 são equivalentes. Nas respostas, os códigos são sempre apresentados no formato 0000-000.

01

Listar moradas

Devolve todas as moradas e intervalos de números de porta associados ao código postal. O campo ID é sequencial dentro de cada resposta.

GET/cp/v1/ruas/{codigo-postal}

Exemplo de pedido

http GET https://api.ptapi.net/cp/v1/ruas/2590432

Exemplo de resposta

[
  {
    "ID": 1,
    "CodigoPostal": "2590-432",
    "Morada": "Quinta da Bica",
    "Localidade": "Sapataria",
    "NumeroPorta": "Sizandros",
    "Freguesia": "Sapataria",
    "Concelho": "Sobral de Monte Agraço",
    "CodigoDistrito": 11,
    "Distrito": "Lisboa",
    "Latitude": "38.997235",
    "Longitude": "-9.161673"
  }
]

Campos devolvidos

IDPosição sequencial na resposta.
CodigoPostalCódigo postal formatado.
MoradaDesignação da morada.
LocalidadeLocalidade associada.
NumeroPortaNúmero ou intervalo de porta, quando disponível.
FreguesiaFreguesia associada.
ConcelhoConcelho associado.
CodigoDistritoCódigo numérico do distrito.
DistritoNome do distrito.
LatitudeLatitude do registo.
LongitudeLongitude do registo.
02

Listar ruas distintas

Devolve apenas as moradas distintas. As diferenças no número de porta são ignoradas e NumeroPorta é devolvido vazio.

GET/cp/v1/rua/{codigo-postal}

Exemplo de pedido

http GET https://api.ptapi.net/cp/v1/rua/4450251
03

Obter coordenadas

Calcula um ponto representativo do código postal a partir das suas coordenadas únicas válidas.

GET/cp/v1/coordenadas/{codigo-postal}

Exemplo de resposta

{
  "CodigoPostal": "2590-432",
  "Latitude": "38.980804",
  "Longitude": "-9.177953",
  "NumeroCoordenadas": 3
}
04

Calcular distância NOVO

Devolve a distância em linha reta e, quando o serviço de rotas está disponível, a distância e a duração estimadas por estrada.

GET/cp/v1/distancia/{origem}/{destino}

Exemplo de pedido

http GET https://api.ptapi.net/cp/v1/distancia/2590432/4450251

Exemplo de resposta

{
  "CodigoPostalOrigem": "2590-432",
  "CodigoPostalDestino": "4450-251",
  "DistanciaMetros": 249148,
  "DistanciaQuilometros": 249.15,
  "DistanciaLinhaRetaMetros": 249148,
  "DistanciaLinhaRetaQuilometros": 249.15,
  "DistanciaEstradaMetros": 295440,
  "DistanciaEstradaQuilometros": 295.44,
  "DuracaoEstradaSegundos": 11880,
  "DuracaoEstradaMinutos": 198,
  "Origem": { "Latitude": "38.980804", "Longitude": "-9.177953" },
  "Destino": { "Latitude": "41.181584", "Longitude": "-8.690671" }
}
Resposta resiliente

Se o serviço de rotas estiver desativado, inacessível ou não encontrar uma rota, os quatro campos de distância e duração por estrada são devolvidos com null. A distância em linha reta continua disponível e o pedido não falha.

05

Otimizar uma rota NOVO

Aceita entre 2 e 50 códigos postais. Numa rota aberta, o primeiro é a origem, o último é o destino e a ordem das paragens intermédias é otimizada.

GET/cp/v1/rota-otimizar/{origem}/{paragens...}/{destino}

Rota aberta

http GET https://api.ptapi.net/cp/v1/rota-otimizar/2590432/1000001/4000001/4450251

Rota circular

Para regressar à origem, use circular=true ou circular=1.

http GET "https://api.ptapi.net/cp/v1/rota-otimizar/2590432/1000001/4000001?circular=true"

Exemplo de resposta

{
  "CodigosPostais": ["2590-432", "1000-001", "4000-001", "4450-251"],
  "Circular": false,
  "Ordem": [
    {
      "Posicao": 1,
      "CodigoPostal": "2590-432",
      "Latitude": "38.980804",
      "Longitude": "-9.177953"
    }
  ],
  "DistanciaEstradaMetros": 518260,
  "DistanciaEstradaQuilometros": 518.26,
  "DuracaoEstimadaSegundos": 21676,
  "DuracaoEstimadaMinutos": 361
}

Numa rota circular, a origem não é repetida em Ordem, mas o regresso está incluído na distância e duração totais. Se o serviço de rotas não responder, Ordem e os campos de distância e duração são devolvidos com null.

Otimização aproximada

O cálculo é aproximado, sobretudo a partir de dez paragens, e não garante matematicamente a rota ótima.

06

Listar distritos

Devolve os distritos e as regiões autónomas registados na plataforma.

GET/cp/v1/distritos

Exemplo de resposta

[
  { "CodigoDistrito": 1, "Distrito": "Aveiro" },
  { "CodigoDistrito": 2, "Distrito": "Braga" }
]

Erros da API

Além dos erros gerais da plataforma, estes códigos podem ser devolvidos pelos métodos desta API.

400invalid_postal_code — o formato, a quantidade ou os parâmetros do código postal são inválidos.
400invalid_circular_parameter — o valor de circular não é válido.
422postal_coordinates_unavailable — não existem coordenadas válidas para o código postal.