Moradas API beta

API gratuita para autocompletar moradas e códigos postais (CP7) de Portugal. Demo ao vivo →

Especificação OpenAPI 3.1: openapi.json

Começar em 2 minutos

Sem registo nem chave de API: copie um exemplo e execute-o. Três pedidos cobrem um checkout — sugestões enquanto o cliente escreve, o CP7 exato pelo número de porta e a ficha de um código postal. Os comentários mostram a resposta real.

# 1. Suggestions as the user types (a trailing door number picks the exact CP7)
curl "https://moradas.dev/suggest?q=av%20liberdade%20lisboa%20196&count=3"

# 2. Exact CP7 for a street and door number
#    art_id comes from /suggest (read here with jq) and changes when the data is refreshed: never store it
ART=$(curl -s "https://moradas.dev/suggest?q=av%20liberdade%20lisboa&count=1" | jq '.suggestions[0].data.art_id')
curl "https://moradas.dev/resolve?art=$ART&numero=196"

# 3. Postal code card: locality, municipality, district and streets
curl "https://moradas.dev/cp/1000-098"

# Errors: -i prints the status line and headers (404 = not found, and the X-Moradas-Hint header says why;
#         429 = too many requests)
curl -i "https://moradas.dev/cp/9999-999"

Erros, limites e formato do CP7

GET /suggest

Um único endpoint para tudo o que o checkout precisa. Dígitos são tratados como código postal, texto como rua ou localidade. Um número no fim é entendido como número de porta e escolhe o CP7 exato quando possível.

GET /suggest?q=estrada%20malveira%20da%20serra%20920&count=2

{ "suggestions": [
  { "value": "Estrada Malveira da Serra, Malveira da Serra",
    "data": { "art_id": 125494, "kind": "street", "street": "Estrada Malveira da Serra",
              "localidade": "Malveira da Serra", "concelho": "Cascais", "distrito": "Lisboa",
              "cp7": "2755-332", "nseg": 1, "numero": "920", "resolved_cp7": "2755-332" } },
  { "value": "Estrada Malveira da Serra, Aldeia de Juso",
    "data": { "art_id": 126122, "kind": "street", "street": "Estrada Malveira da Serra",
              "localidade": "Aldeia de Juso", "concelho": "Cascais", "distrito": "Lisboa",
              "cp7": "2750-834", "nseg": 11, "numero": "920", "resolved_cp7": "2750-834" } }
] }

Os exemplos desta página são respostas reais de 30.09.2026. Os valores de art_id mudam a cada atualização semanal dos dados: tire-os sempre de uma resposta nova do /suggest e nunca os copie destes exemplos para o seu código.

O mesmo nome de rua pode existir em várias localidades postais (aqui Malveira da Serra e Aldeia de Juso). nseg é o número de troços de código postal nessa rua; com nseg > 1, resolved_cp7 significa que o número de porta correspondeu a um troço específico.

Cada sugestão traz kind: street é uma rua; loc é um lugar sem nome de rua. Um loc com "art_id": 0 e "cp7": null é a localidade ou o concelho inteiro — aparece primeiro quando a pessoa escreve o nome de um lugar («carcav», «Lisboa»); não há rua a resolver (/resolve?art=0 devolve 404): mostre-o como lugar e deixe a pessoa continuar a escrever a rua. Um loc com art_id > 0 é uma localidade pequena com código postal próprio: cp7 vem preenchido e usa-se como o de uma rua. O rótulo value pode repetir-se (três «Carcavelos» diferentes abaixo): mostre o concelho ao lado. Resposta real de 21.10.2026:

GET /suggest?q=carcav&count=3

{ "suggestions": [
  { "value": "Carcavelos",
    "data": { "art_id": 0, "kind": "loc", "street": "", "localidade": "Carcavelos",
              "concelho": "Cascais", "distrito": "Lisboa", "cp7": null, "nseg": 140 } },
  { "value": "Carcavelos",
    "data": { "art_id": 273402, "kind": "loc", "street": "", "localidade": "Carcavelos",
              "concelho": "Viseu", "distrito": "Viseu", "cp7": "3505-340", "nseg": 1 } },
  { "value": "Carcavelos",
    "data": { "art_id": 273585, "kind": "loc", "street": "", "localidade": "Carcavelos",
              "concelho": "Viseu", "distrito": "Viseu", "cp7": "3510-891", "nseg": 1 } }
] }
parâmetrosignificado
qcódigo postal (1000-098, 4–7 dígitos) ou texto livre (av liberdade lisboa 196)
countmáximo de sugestões, 10 por defeito, limite 20

A pesquisa é tolerante: acentos opcionais (sao joao), abreviaturas (av → Avenida), preposições opcionais (rua das flores também encontra «Rua Flores»). Cidades maiores aparecem primeiro.

Se a linha traz um código postal válido mas o texto da rua não encontra nada — nem com a correção de gralhas («Rua Agsta nº 5, 1100-053 Lisboa», «Hotel Tivoli, 1269-050 Lisboa») — a resposta são as ruas desse código postal, como em /suggest?q=1100-053, cada uma com "by_cp7": true em data. Um número de porta na linha é tratado como de costume (numero, resolved_cp7). Sem este campo, a sugestão veio do texto; se o código postal não existir nos dados, a resposta continua vazia.

Se o texto não encontra nada e a linha não traz um código postal completo, mas traz uma zona postal de 4 dígitos que existe («Rua Augusta 100, 1100 Lisboa», «Rua Desconhecida 12, 4700 Braga»), a zona é retirada da linha e a rua é procurada de novo, primeiro dentro dessa zona: se aparecer, vem como sugestão de rua normal (numero e resolved_cp7 como de costume, sem campo extra). Se também não houver rua, a resposta são as localidades dessa zona como lugares ("kind": "loc", "art_id": 0, "cp7": null, nseg = códigos postais da localidade na zona), as maiores primeiro e, à frente, a localidade escrita na linha — no máximo 5, cada uma com "by_cp4": true e "cp4" em data. Assim o formulário fica pelo menos com localidade, concelho e distrito; a rua continua por escrever. Sem este campo, a sugestão veio do texto; se a zona não existir nos dados (ou os 4 dígitos forem um número de porta), a resposta continua vazia.

GET /resolve

Quando uma rua tem vários códigos postais ("cp7": null, "nseg" > 1), resolva pelo número de porta — a paridade e os intervalos de números decidem. O art_id é efémero: muda quando os dados são atualizados — use-o logo a seguir ao suggest e não o guarde. Uma sugestão com "kind": "loc", "art_id": 0 e "cp7": null é a localidade ou o concelho inteiro (por exemplo, ao escrever só «Lisboa»): não há rua a resolver, peça à pessoa que continue a escrever a morada. O início do nome de um concelho ou de uma localidade grande («Lisb», «Carcav») devolve o próprio lugar primeiro. Se o resultado só apareceu depois de corrigir uma gralha («rua agusta» → Rua Augusta) ou o tipo de via («avenida augusta lisboa» → Rua Augusta), a sugestão traz "corrected": true em data.

GET /resolve?art=132467&numero=10        (art_id of "Rua das Adelas, Lisboa" in a fresh /suggest)

{ "resolved": { "value": "Rua das Adelas, Lisboa",
                "data": { "art_id": 132467, "kind": "street", "street": "Rua das Adelas",
                          "localidade": "Lisboa", "concelho": "Lisboa", "distrito": "Lisboa",
                          "cp7": "1200-008", "nseg": 2 } },
  "segments": [ { "cp7": "1200-007", "label": "Impares de 3 a 17A" },
                { "cp7": "1200-008", "label": "Pares de 2 a 28" } ] }

Sem numero, ou com um número que não decide um único código, resolved vem null e segments continua a listar os troços, para o cliente escolher. Um art_id que já não existe devolve 404 ({"error":"unknown artery"}): volte a chamar o /suggest.

GET /cp/{cp7}

Ficha de um código postal — localidade, concelho, distrito e as ruas que abrange.

GET /cp/1000-098

{ "cp7": "1000-098", "cp4": "1000", "cp3": "098",
  "distrito": "Lisboa", "concelho": "Lisboa", "localidade": "Lisboa",
  "arterias": [ { "art_id": 130446, "street": "Praça do Chile",
                  "troco": null, "porta": null, "cliente": null } ] }

As ruas estão em arterias[].street. troco é o intervalo de números de porta que o código cobre (por exemplo Pares de 2 a 28), porta um número de porta concreto e cliente a organização que tem o código só para si; os três vêm null quando não se aplicam. Um código sem ruas (uma localidade inteira) tem arterias vazio.

Quando não há resposta, o 404 traz o cabeçalho X-Moradas-Hint com o motivo em inglês; o corpo não muda. Exemplos: /cp/4700-000 → 4700-000 is not an assigned postal code; /cp/4700 lists the postal codes that start with 4700; /cp/1100-413%20LISBOA → Use only the postal code, without locality or other text: /cp/1100-413. O cabeçalho é legível a partir do browser (Access-Control-Expose-Headers).

GET /cp/{cp4} — todos os códigos de uma zona

Com só os quatro primeiros dígitos, a resposta é a lista de todos os CP7 dessa zona, por ordem, cada um com a sua localidade, concelho e distrito (os mesmos que /cp/{cp7} devolve). cliente traz o nome da organização quando o código é só dela; senão, null. Uma zona sem códigos devolve 404. Zonas grandes têm perto de mil códigos: guarde a lista em cache.

GET /cp/4700        (shortened here to the first three codes)

{ "cp4": "4700",
  "codigos": [
    { "cp7": "4700-001", "localidade": "Braga", "concelho": "Braga", "distrito": "Braga", "cliente": null },
    { "cp7": "4700-002", "localidade": "Braga", "concelho": "Braga", "distrito": "Braga", "cliente": null },
    { "cp7": "4700-003", "localidade": "Braga", "concelho": "Braga", "distrito": "Braga", "cliente": null }
  ] }

Caminhos e campos que não existem

POST /batch

Para programas que têm uma lista de moradas — importação de encomendas, CRM, limpeza de uma base de clientes. Até 100 moradas num só pedido, cada uma passada pela mesma lógica do /suggest (um número de porta no texto escolhe o CP7 exato; um código postal é procurado como tal). A resposta vem pela ordem de entrada, uma linha por morada, com um veredicto: ok — código postal determinado, em cp7; ambiguous — sem resposta única (vários candidatos sem nada que os distinga, uma rua com vários códigos postais e sem número de porta, ou só uma localidade); not_found — nada encontrado. suggestion é a primeira sugestão tal como o /suggest a devolve (com resolved_cp7 quando o número de porta decidiu, corrected: true depois de corrigir uma gralha); em ambiguous é o melhor candidato, para alguém confirmar; em not_found é null.

POST /batch
Content-Type: application/json

{ "items": [
  { "id": "o-1001", "q": "Avenida da Liberdade 196, Lisboa" },
  { "id": "o-1002", "q": "Rua Augusta 100 Lisboa" },
  { "id": "o-1003", "q": "xyzxyz qqq" },
  { "id": "o-1004", "q": "rua das flores" }
] }
{ "results": [
  { "id": "o-1001", "q": "Avenida da Liberdade 196, Lisboa",
    "status": "ok", "cp7": "1250-147",
    "suggestion": { "value": "Avenida da Liberdade, Lisboa",
      "data": { "art_id": 129534, "kind": "street",
                "street": "Avenida da Liberdade", "localidade": "Lisboa",
                "concelho": "Lisboa", "distrito": "Lisboa", "cp7": "1250-147",
                "nseg": 28, "numero": "196", "resolved_cp7": "1250-147" } } },
  { "id": "o-1002", "q": "Rua Augusta 100 Lisboa",
    "status": "ok", "cp7": "1100-053",
    "suggestion": { "value": "Rua Augusta, Lisboa",
      "data": { "art_id": 130802, "kind": "street", "street": "Rua Augusta",
                "localidade": "Lisboa", "concelho": "Lisboa", "distrito": "Lisboa",
                "cp7": "1100-053", "nseg": 12, "numero": "100",
                "resolved_cp7": "1100-053" } } },
  { "id": "o-1003", "q": "xyzxyz qqq",
    "status": "not_found", "cp7": null,
    "suggestion": null },
  { "id": "o-1004", "q": "rua das flores",
    "status": "ambiguous", "cp7": null,
    "suggestion": { "value": "Rua das Flores, Lisboa",
      "data": { "art_id": 132486, "kind": "street", "street": "Rua das Flores",
                "localidade": "Lisboa", "concelho": "Lisboa", "distrito": "Lisboa",
                "cp7": null, "nseg": 5 } } }
] }

Resposta real de 02.10.2026 (os art_id mudam a cada atualização dos dados). A primeira linha tem rua, número e localidade: fica ok. A quarta não diz a localidade e «Rua das Flores» existe em várias — fica ambiguous, com a melhor candidata para alguém decidir. Uma morada só fica ok quando a primeira sugestão tem código postal e é líder clara: é a única; todas as candidatas dão o mesmo código; o número de porta só correspondeu a ela; ou cobre mais palavras do pedido do que qualquer outra («rua das flores dona maria» → Dona Maria, não Lisboa).

camposignificado
items[].qa morada em texto livre, como q no /suggest: rua, número de porta e localidade, ou um código postal. Obrigatório.
items[].idqualquer texto ou número seu (número da encomenda, id do registo), devolvido tal e qual. Opcional; na resposta vem null quando falta.
results[].statusok, ambiguous ou not_found.
results[].cp7o código postal quando ok; senão null.
results[].suggestiona primeira sugestão, no formato do /suggest; null em not_found.

Limites. Até 100 moradas e 64 KB por pedido. Um pedido com N moradas conta como N pedidos no limite geral (cerca de 50 por 10 segundos por IP): um pacote maior do que o que ainda cabe é recusado inteiro com 429 e Retry-After, sem processar nenhuma linha — na prática, envie até 50 moradas de cada vez e, num 429, espere os segundos do cabeçalho. Mais de 100 moradas → 400 com hint; corpo maior → 413; JSON inválido → 400; GET /batch → 405 com X-Moradas-Hint. As respostas não ficam em cache. CORS aberto, como no /suggest.

curl -s -X POST "https://moradas.dev/batch" -H "Content-Type: application/json" \
  -d '{"items":[{"id":"o-1001","q":"Avenida da Liberdade 196, Lisboa"},
             {"id":"o-1003","q":"xyzxyz qqq"}]}'
# {"results":[{"id":"o-1001","q":"Avenida da Liberdade 196, Lisboa","status":"ok",
#              "cp7":"1250-147","suggestion":{…}},
#             {"id":"o-1003","q":"xyzxyz qqq","status":"not_found",
#              "cp7":null,"suggestion":null}]}
# Python 3.8+ with requests (pip install requests)
import time

import requests


def moradas_batch(items):
    """items: [{"id": ..., "q": "..."}], up to 50 per call."""
    for attempt in range(3):
        res = requests.post("https://moradas.dev/batch",
                            json={"items": items}, timeout=60)
        if res.status_code == 429:              # the batch counts as len(items) requests
            wait = res.headers.get("Retry-After", "10")
            time.sleep(int(wait) if wait.isdigit() else 10)
            continue
        res.raise_for_status()                  # 400 / 413: the body has "error" and "hint"
        return res.json()["results"]
    raise RuntimeError("Moradas: still rate limited after 3 attempts")


rows = [{"id": "o-1001", "q": "Avenida da Liberdade 196, Lisboa"},
        {"id": "o-1003", "q": "xyzxyz qqq"}]
for start in range(0, len(rows), 50):           # 50 at a time stays inside the rate limit
    for r in moradas_batch(rows[start:start + 50]):
        print(r["id"], r["status"], r["cp7"])   # o-1001 ok 1250-147  /  o-1003 not_found None

POST /feedback

Uma morada não apareceu? Envie-a aqui.

POST /feedback
Content-Type: application/json

{ "query": "rua que não apareceu, localidade", "note": "optional details" }

Integrar sem o widget

Já tem o seu formulário — código postal, rua, número de porta, localidade — e prefere o seu próprio código ao widget? Três receitas cobrem o que o widget faz, em JavaScript do browser e só com fetch; cp, rua, porta, form.*, aviso, ruas e escolha são os seus elementos. As respostas são reais, de 21.10.2026 (os art_id mudam a cada atualização dos dados). No servidor (Node.js, PHP, Python, C#) as mesmas chamadas estão no Quickstart.

1. Código postal → localidade, concelho, distrito

Quando o cliente escreve o código postal, GET /cp/{cp7} devolve a ficha: localidade, concelho, distrito e as ruas que o código abrange. Normalize primeiro para 0000-000 e valide com ^\d{4}-\d{3}$ — assim não gasta pedidos com códigos a meio. Num 404 (código que não existe) limpe os campos que tinha preenchido e diga-o ao cliente; o cabeçalho X-Moradas-Hint explica o motivo em inglês. Num 429 ou numa falha, não apague nada: o cliente continua a escrever.

cp.oninput = async () => {                                                   // cp = your postal-code <input>
  const cp7 = cp.value.trim().replace(/^(\d{4})[\s-]?(\d{3})$/, '$1-$2');    // "1000098", "1000 098" → "1000-098"
  if (!/^\d{4}-\d{3}$/.test(cp7)) return;                                    // not a full code yet: wait for more digits
  const res = await fetch('https://moradas.dev/cp/' + cp7);
  if (res.status === 404) {                                                  // unknown code: clear the fields and say so
    form.localidade.value = form.concelho.value = form.distrito.value = '';
    aviso.textContent = 'Código postal não encontrado';                      // res.headers.get('X-Moradas-Hint') says why (in English)
    return;
  }
  if (!res.ok) return;                                                       // 429 or outage: leave the fields as they are
  const card = await res.json();                                             // {cp7, cp4, cp3, distrito, concelho, localidade, arterias: [{art_id, street, troco, porta, cliente}]}
  cp.value = cp7; aviso.textContent = '';
  [form.localidade.value, form.concelho.value, form.distrito.value] = [card.localidade, card.concelho ?? '', card.distrito ?? ''];
  ruas.replaceChildren(...card.arterias.map((a) => new Option(a.street, a.art_id)));  // ruas = a <select> or <datalist>; art_id feeds /resolve (3)
};

Campos da resposta, com os valores de GET /cp/1250-147 (resposta real):

GET /cp/1250-147

{ "cp7": "1250-147", "cp4": "1250", "cp3": "147",
  "distrito": "Lisboa", "concelho": "Lisboa", "localidade": "Lisboa",
  "arterias": [ { "art_id": 129608, "street": "Avenida da Liberdade",
                  "troco": "Pares de 190 a 220A", "porta": null, "cliente": null } ] }
campovalor no exemplosignificado
localidadeLisboalocalidade postal — o campo «Localidade» do seu formulário
concelhoLisboaconcelho (município); pode vir null
distritoLisboadistrito; pode vir null
cp4, cp31250, 147as duas partes do código, já separadas
arterias[].streetAvenida da Liberdadenome da rua, para um <select> ou <datalist> de ruas (não existe ruas[].nome); lista vazia num código sem ruas
arterias[].trocoPares de 190 a 220Anúmeros de porta que este código cobre nessa rua; null quando cobre a rua toda
arterias[].portanullum número de porta concreto, quando o código é só dele
arterias[].art_id129608id da rua para o /resolve (receita 3); efémero — não o guarde
arterias[].clientenullorganização que tem o código só para si

2. Rua → sugestões enquanto o cliente escreve

Um pedido a GET /suggest?q= por pausa na escrita, não por tecla: espere 150–250 ms depois da última tecla e ignore a resposta se o texto entretanto mudou. Cada linha da lista é value (rua e localidade); data traz os campos para o formulário. Trate o kind: uma linha com "kind": "loc" e "art_id": 0 é um lugar, não uma morada — ao escolhê-la, deixe o nome no campo e peça a rua; não a envie ao /resolve (404) nem a guarde como morada. "corrected": true significa que a rua foi encontrada depois de corrigir uma gralha ou o tipo de via e "by_cp7": true que veio do código postal escrito na linha — mostre-as como «Queria dizer…». Num 429 ou numa falha, mantenha a lista como está.

let timer, picked = null;                                                    // picked: data of the chosen suggestion, used in (3)
rua.oninput = () => {                                                        // rua = your street <input>
  clearTimeout(timer); picked = null;
  timer = setTimeout(async () => {
    const q = rua.value.trim(); if (q.length < 2) return render([]);
    const res = await fetch(`https://moradas.dev/suggest?q=${encodeURIComponent(q)}&count=8`).catch(() => null);
    if (res?.ok && q === rua.value.trim()) render((await res.json()).suggestions); // 429, outage or an older keystroke: keep the list as it is
  }, 200);
};
function pick({ value, data: d }) {                                          // the user chose a row; render(list) is yours: one row per value
  if (d.kind === 'loc' && d.art_id === 0) { render([]); rua.value = d.localidade + ' '; return rua.focus(); } // a whole locality or municipality, no street: let them keep typing
  picked = d; rua.value = value; render([]);
  [form.localidade.value, form.concelho.value, form.distrito.value] = [d.localidade, d.concelho ?? '', d.distrito ?? ''];
  form.cp7.value = d.resolved_cp7 || d.cp7 || '';                            // '' = the street spans nseg postal codes: ask for the door number (3)
}

3. Número de porta → CP7 exato

Uma rua com vários códigos postais vem com "cp7": null e nseg > 1. Quando o cliente escreve o número de porta, GET /resolve?art={art_id}&numero= escolhe o código pelo número (paridade e intervalos). resolved é a rua com o cp7 certo, ou null quando o número não decide um único código; segments lista sempre todos os códigos da rua com a regra de cada um, para o cliente escolher. Um 404 significa que o art_id é de antes da última atualização dos dados: repita o /suggest.

porta.onchange = async () => {                                               // porta = your door-number <input>
  if (!picked || picked.nseg < 2 || !porta.value.trim()) return;             // nothing chosen in (2), or the street has a single postal code
  const res = await fetch(`https://moradas.dev/resolve?art=${picked.art_id}&numero=${encodeURIComponent(porta.value.trim())}`);
  if (!res.ok) return;                                                       // 404: art_id older than the last data refresh — run /suggest again
  const { resolved, segments } = await res.json();                           // segments: every postal code of the street, with its door-number rule
  form.cp7.value = resolved ? resolved.data.cp7 : '';                        // null: that number decides no single code — let them choose below
  escolha.replaceChildren(...(resolved ? [] : segments.map((s) => new Option(`${s.cp7} — ${s.label}`, s.cp7)))); // escolha = a <select>
};
escolha.onchange = () => { form.cp7.value = escolha.value; };

Resposta real quando o número não decide (GET /resolve?art=132541&numero=10 dá 1200-008; com numero=1000):

GET /resolve?art=132541&numero=1000        (art_id of "Rua das Adelas, Lisboa" in a fresh /suggest)

{ "resolved": null,
  "segments": [ { "cp7": "1200-007", "label": "Impares de 3 a 17A" },
                { "cp7": "1200-008", "label": "Pares de 2 a 28" } ] }

Widget (qualquer formulário)

Duas linhas: carregar o script e ligá-lo ao campo da morada. As sugestões aparecem enquanto se escreve; os campos indicados em fill recebem código postal, localidade, concelho e distrito. Sem build, sem dependências.

<script src="https://moradas.dev/widget.js"></script>
<script>
  PTAddress.attach(document.querySelector('#morada'), {
    fill: { postal: '#cp7', city: '#localidade', municipality: '#concelho', district: '#distrito' },
    lang: 'pt'
  });
</script>

Carregue o script sem async e chame attach depois de o campo existir na página (por exemplo, no fim do <body>). Um CP7 que o cliente já escreveu não é apagado quando a rua escolhida tem vários códigos postais: o widget preenche o CP7 exato quando o cliente escreve o número de porta. Se o serviço não responder (limite de pedidos ou falha), a lista avisa que está temporariamente indisponível e o cliente continua a escrever normalmente.

Quando o código postal e a rua são campos separados — o caso mais comum —, ligue o widget ao campo da rua e passe o campo do código em fill.postal: o widget escreve lá o CP7 assim que o conhece (na escolha ou, numa rua com vários códigos, depois do número de porta); um código que o cliente já tinha escrito só é substituído quando o exato fica conhecido. Não ligue o widget ao campo do código postal. Para preencher a localidade a partir de um código escrito pelo cliente, sem widget, veja Integrar sem o widget.

Opções do widget

opçãosignificado
fillCampos a preencher: { postal, city, municipality, district }, cada um um seletor CSS ou um elemento, para o CP7, a localidade, o concelho e o distrito. Todos opcionais.
onSelect(data)Chamado quando o cliente escolhe uma sugestão; data é o objeto data dessa sugestão no /suggest (street, localidade, concelho, distrito, cp7…).
onResolve(cp7)Chamado quando o CP7 exato fica conhecido: na escolha ou, numa rua com vários códigos postais, quando o cliente escreve o número de porta e sai do campo.
lang'pt' (por defeito) ou 'en': língua das mensagens da lista.
minCharsCaracteres escritos antes do primeiro pedido; 2 por defeito.
debouncePausa depois da última tecla, em milissegundos; 160 por defeito.
countMáximo de sugestões na lista; 8 por defeito, limite 20.
endpointURL base da API; https://moradas.dev por defeito.
beacontrue por defeito: envia um relatório de erro mínimo quando o serviço falha (ver abaixo). false desliga-o.
sourceNome e versão da integração (por exemplo 'wp-woo/0.3.1'; 'widget/0.3.1' por defeito), enviados nos pedidos a /suggest e /resolve no parâmetro from — letras latinas, algarismos e . - /, até 32 caracteres — para contarmos em quantos sites o widget e os nossos plugins estão em uso; não leva dados pessoais.

Relatório de erros: quando o serviço não responde como devia (limite de pedidos 429, falha 5xx, erro de rede ou resposta inesperada), o widget envia com navigator.sendBeacon um pequeno POST para {endpoint}/widget-error, por exemplo {"kind": "429", "widget_version": "0.3.1", "http_status": 429} — no máximo um por tipo de erro e por carregamento da página. Não leva morada, texto escrito nem o endereço da página; o browser junta a origem do site, como em qualquer pedido. Contamos estes relatórios por hora e por site para ver avarias que de outra forma não veríamos. O pedido aparece no separador Network do DevTools; desligue-o com beacon: false. Mais em Privacidade.

PTAddress.attach(input, options) devolve { destroy() }, que remove a lista e os listeners do campo.

React, Vue e outras SPA

Ligue o widget quando o campo já existe no DOM e desligue-o quando o componente sai: attach no useEffect ou no onMounted, destroy() na limpeza. Os campos de fill são preenchidos como se o cliente os escrevesse (eventos input e change), por isso onChange e v-model recebem os valores. Para escrever os valores no estado diretamente, use onSelect e onResolve, como no exemplo React.

// React 18+. Load the widget once, e.g. in index.html:
//   <script src="https://moradas.dev/widget.js"></script>
import { useEffect, useRef, useState } from 'react';

const EMPTY = { morada: '', cp7: '', localidade: '', concelho: '' };

export function AddressForm() {
  const [form, setForm] = useState(EMPTY);
  const moradaRef = useRef(null);

  useEffect(() => {
    const widget = window.PTAddress.attach(moradaRef.current, {
      onSelect: (d) => setForm((f) => ({
        ...f, localidade: d.localidade, concelho: d.concelho,
      })),
      onResolve: (cp7) => setForm((f) => ({ ...f, cp7 })),
    });
    return () => widget.destroy(); // cleanup on unmount
  }, []);

  const field = (name) => ({
    name,
    value: form[name],
    onChange: (e) => setForm((f) => ({ ...f, [name]: e.target.value })),
  });

  return (
    <form>
      <input ref={moradaRef} {...field('morada')} placeholder="Morada" />
      <input {...field('cp7')} placeholder="Código postal" />
      <input {...field('localidade')} placeholder="Localidade" />
    </form>
  );
}
<!-- Vue 3. Load https://moradas.dev/widget.js once, e.g. in index.html -->
<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';

const form = ref({ morada: '', cp7: '', localidade: '' });
const moradaInput = ref(null);
let widget = null;

onMounted(() => {
  widget = window.PTAddress.attach(moradaInput.value, {
    // filled in like typing, so v-model picks up the values
    fill: { postal: '#cp7', city: '#localidade' },
  });
});
onBeforeUnmount(() => widget?.destroy());
</script>

<template>
  <input ref="moradaInput" v-model="form.morada" placeholder="Morada">
  <input id="cp7" v-model="form.cp7" placeholder="Código postal">
  <input id="localidade" v-model="form.localidade" placeholder="Localidade">
</template>

Plugins prontos: WooCommerce e PrestaShop

WooCommerce — plugin 0.3.1, para instalar a partir do ficheiro: ZIP (SHA-256) › Plugins › Adicionar novo › Carregar plugin › Instalar agora › Ativar. Checkout em blocos e clássico; WordPress 6.5+, PHP 7.4+, WooCommerce 9.9+ para o checkout em blocos. Publicado no wordpress.org — instale-o pelo painel (Plugins › Adicionar novo › «Moradas») para receber atualizações automáticas. Passos e notas no guia WooCommerce.

PrestaShop — módulo 0.2.2 para 1.7.1 a 9: ZIP (SHA-256) › Módulos › Gestor de módulos › Carregar um módulo. Carrega o widget.js e liga-o aos campos address1, postcode e city no checkout e na área de cliente, só com Portugal como país; não testado numa loja real. Código e notas no guia PrestaShop.

MCP (agentes de IA)

Servidor MCP remoto — nada para instalar, sem chave. Qualquer agente compatível com MCP (Claude, Cursor, ChatGPT e outros) pode autocompletar moradas portuguesas, consultar códigos postais e verificar listas inteiras de moradas através dele.

Endpoint:   https://moradas.dev/mcp   (Streamable HTTP, stateless)
Tools:      suggest_address · resolve_postal_code · postal_code_info · verify_addresses

Claude Code:
  claude mcp add --transport http moradas https://moradas.dev/mcp

Cursor / Windsurf / others (mcp.json):
  { "mcpServers": { "moradas": { "url": "https://moradas.dev/mcp" } } }

Ferramentas

Exemplo de tools/call para verify_addresses e resposta real de 06.10.2026 (os art_id mudam a cada atualização dos dados). structuredContent é o JSON; content[0].text traz o mesmo JSON em texto, para clientes sem saída estruturada.

POST /mcp
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "verify_addresses", "arguments": { "items": [
    { "id": "o-1001", "q": "Avenida da Liberdade 196, Lisboa" },
    { "id": 2, "q": "rua das flores" },
    { "q": "xyzxyz qqq" }
  ] } } }
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\":[{\"id\":\"o-1001\",\"q\":\"Avenida da Liberdade 196, Lisboa\",\"status\":\"ok\",\"cp7\":\"1250-147\",\"suggestion\":{\"value\":\"Avenida da Liberdade, Lisboa\",\"data\":{\"art_id\":129377,\"kind\":\"street\",\"street\":\"Avenida da Liberdade\",\"localidade\":\"Lisboa\",\"concelho\":\"Lisboa\",\"distrito\":\"Lisboa\",\"cp7\":\"1250-147\",\"nseg\":28,\"numero\":\"196\",\"resolved_cp7\":\"1250-147\"}}},{\"id\":2,\"q\":\"rua das flores\",\"status\":\"ambiguous\",\"cp7\":null,\"suggestion\":{\"value\":\"Rua das Flores, Lisboa\",\"data\":{\"art_id\":132329,\"kind\":\"street\",\"street\":\"Rua das Flores\",\"localidade\":\"Lisboa\",\"concelho\":\"Lisboa\",\"distrito\":\"Lisboa\",\"cp7\":null,\"nseg\":5}}},{\"id\":null,\"q\":\"xyzxyz qqq\",\"status\":\"not_found\",\"cp7\":null,\"suggestion\":null}]}"
      }
    ],
    "structuredContent": {
      "results": [
        {
          "id": "o-1001",
          "q": "Avenida da Liberdade 196, Lisboa",
          "status": "ok",
          "cp7": "1250-147",
          "suggestion": {
            "value": "Avenida da Liberdade, Lisboa",
            "data": {
              "art_id": 129377,
              "kind": "street",
              "street": "Avenida da Liberdade",
              "localidade": "Lisboa",
              "concelho": "Lisboa",
              "distrito": "Lisboa",
              "cp7": "1250-147",
              "nseg": 28,
              "numero": "196",
              "resolved_cp7": "1250-147"
            }
          }
        },
        {
          "id": 2,
          "q": "rua das flores",
          "status": "ambiguous",
          "cp7": null,
          "suggestion": {
            "value": "Rua das Flores, Lisboa",
            "data": {
              "art_id": 132329,
              "kind": "street",
              "street": "Rua das Flores",
              "localidade": "Lisboa",
              "concelho": "Lisboa",
              "distrito": "Lisboa",
              "cp7": null,
              "nseg": 5
            }
          }
        },
        {
          "id": null,
          "q": "xyzxyz qqq",
          "status": "not_found",
          "cp7": null,
          "suggestion": null
        }
      ]
    },
    "isError": false
  }
}

Utilização

Beta. URL base: https://moradas.dev. Feedback: dev@moradas.dev