Métodos disponíveis
Consulte dados postais e geográficos, calcule distâncias e encontre uma ordem eficiente para as suas paragens.
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.
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.
/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
Listar ruas distintas
Devolve apenas as moradas distintas. As diferenças no número de porta são ignoradas e NumeroPorta é devolvido vazio.
/cp/v1/rua/{codigo-postal}Exemplo de pedido
http GET https://api.ptapi.net/cp/v1/rua/4450251
Obter coordenadas
Calcula um ponto representativo do código postal a partir das suas coordenadas únicas válidas.
/cp/v1/coordenadas/{codigo-postal}Exemplo de resposta
{
"CodigoPostal": "2590-432",
"Latitude": "38.980804",
"Longitude": "-9.177953",
"NumeroCoordenadas": 3
}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.
/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" }
}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.
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.
/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.
O cálculo é aproximado, sobretudo a partir de dez paragens, e não garante matematicamente a rota ótima.
Listar distritos
Devolve os distritos e as regiões autónomas registados na plataforma.
/cp/v1/distritosExemplo 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.
invalid_postal_code — o formato, a quantidade ou os parâmetros do código postal são inválidos.invalid_circular_parameter — o valor de circular não é válido.postal_coordinates_unavailable — não existem coordenadas válidas para o código postal.