PT Zipcode API – Documentação (Dev)

API REST para consulta de códigos postais portugueses. Suporta modo grátis (trial) e autenticação por API key.
Base URL: https://ptzc.jobinoo.tech Endpoint: GET /cp.php Trial: 10/dia/IP sem key Auth: X-API-Key (opcional)
Input aceita 1100-365 ou 1100365

Índice

Visão geral

A API retorna dados de um código postal português via parâmetro cp. Você pode enviar 1100-365 ou 1100365 (o sistema normaliza).

A resposta retorna found, count, a lista data, e informações de uso: mode e trial (quando aplicável).

Quando o banco estiver ajustado, a resposta inclui nome_distrito (JOIN com distritos).

Autenticação e modo grátis

Com API key (recomendado)

Envie a chave no header:

X-API-Key: SUA_API_KEY

Alternativa por querystring (menos seguro):

GET /cp.php?cp=1100365&key=SUA_API_KEY

Modo grátis (trial)

Se você não enviar API key, a API permite até 10 consultas por dia por IP. A resposta vem com mode=trial e trial.

Ao atingir o limite, a API retorna 429.

Como chamar a API

Endpoint

GET https://ptzc.jobinoo.tech/cp.php

Parâmetros

Parâmetro Tipo Obrigatório Descrição
cp string Sim Código postal. Aceita 1100-365, 1100365, 1100 365, 1100/365.
key string Não API key alternativa ao header X-API-Key (menos seguro).
json int Não Opcional/compatibilidade. A API sempre retorna JSON.

Normalização

A API remove caracteres não numéricos do cp e valida se o resultado tem 7 dígitos. O retorno formata como NNNN-NNN no campo cp.

Formato de resposta

Sucesso (200) — exemplo real

{
  "cp": "1100-365",
  "found": true,
  "count": 1,
  "data": [
    {
      "id": 236515,
      "cod_distrito": "11",
      "cod_concelho": "06",
      "cod_localidade": "21696",
      "nome_localidade": "Lisboa",
      "cod_arteria": "33610611",
      "tipo_arteria": "Praça",
      "prep_1": "do",
      "titulo_arteria": "",
      "prep2": "",
      "nome_arteria": "Município",
      "local_arteria": "",
      "troco": "",
      "porta": "",
      "cliente": "",
      "num_cod_postal": "1100",
      "ext_cod_postal": "365",
      "desig_postal": "Lisboa",
      "nome_distrito": "Lisboa"
    }
  ],
  "mode": "trial",
  "trial": {
    "limit": 10,
    "used": 1,
    "remaining": 9
  }
}

Exemplos

cURL (modo grátis)

curl "https://ptzc.jobinoo.tech/cp.php?cp=1100365&json=1"

cURL (com API key)

curl -H "X-API-Key: SUA_API_KEY" \
"https://ptzc.jobinoo.tech/cp.php?cp=1100365&json=1"

JavaScript (fetch)

fetch("https://ptzc.jobinoo.tech/cp.php?cp=1100365&json=1", {
  headers: { "X-API-Key": "SUA_API_KEY" }
})
  .then(r => r.json())
  .then(console.log);

PHP (cURL)

$url = "https://ptzc.jobinoo.tech/cp.php?cp=1100365&json=1";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: SUA_API_KEY"
]);

$res = curl_exec($ch);
curl_close($ch);

echo $res;

Erros e códigos HTTP

Status Quando acontece Body (exemplo)
400 Formato inválido (não vira 7 dígitos) {"error":"bad_request"}
401 API key inválida {"error":"unauthorized"}
404 Código postal não encontrado {"found":false}
429 Limite grátis (trial) atingido {"error":"rate_limited"}
500 Erro interno (DB / query) {"error":"server_error"}

Notas

  • Produção: prefira X-API-Key em vez de ?key= (evita vazamento em logs/histórico).
  • Trial: 10/dia/IP é só demo. Para uso sério, use API key.
  • Distrito: nome_distrito vem do JOIN com distritos.
Copiado ✅