Moradas API beta

Free suggestions & lookup for Portuguese postal addresses. Data: CTT «todos_cp» (all 192,894 CP7 codes, updated daily at source). Best effort, no SLA. No cookies, no personal data — only aggregate usage counts. Live demo →

GET /suggest

One endpoint for everything the checkout needs. Digits are treated as a postal code, text as a street/locality query. A trailing number is understood as the door number and picks the exact CP7 when possible.

GET /suggest?q=estrada malveira da serra 920&count=8

{ "suggestions": [ {
    "value": "Estrada Malveira da Serra, Malveira da Serra",
    "data": {
      "art_id": 125340, "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 Juzo",
    "data": {
      "art_id": 125968, "kind": "street",
      "street": "Estrada Malveira da Serra", "localidade": "Aldeia de Juzo",
      "concelho": "Cascais", "distrito": "Lisboa",
      "cp7": "2750-834", "nseg": 11,
      "numero": "920", "resolved_cp7": "2750-834"
  } }, … ] }

The same street name can span several postal localities (here Malveira da Serra vs Aldeia de Juzo). nseg is the number of CTT segments on that street; with nseg > 1 a resolved_cp7 means the door number matched an explicit segment (e.g. «Pares de 484 a 1144»).

Matching is forgiving: accents optional (sao joao), abbreviations (av → Avenida), prepositions ignored where CTT omits them (rua das flores finds «Rua Flores»). Bigger cities rank first.

GET /resolve

When a street has several postal codes ("cp7": null, "nseg": > 1), resolve by door number — parity and ranges come from CTT data.

GET /resolve?art=129377&numero=196

{ "resolved": { "value": "Avenida da Liberdade, Lisboa",
                "data": { ..., "cp7": "1250-147" } },
  "segments": [ { "cp7": "1250-139", "label": "Impares de 1 a 57" }, ... ] }

GET /cp/{cp7}

Card for one postal code — locality, municipality, district and the streets it covers. Handy replacement for the discontinued GeoAPI.pt lookup.

GET /cp/1000-098

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

POST /feedback

An address didn't come up? Tell us — reports feed the correction layer.

POST /feedback
Content-Type: application/json

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

Fair use

• Free for any use, including commercial checkouts. CORS is open.
• Soft limit ~50 requests / 10 s per IP — plenty for typing; batch scraping will hit 429.
• Best effort: no SLA, no guarantees, cache what you need.