Skip to content
Category

Standardize Angolan addresses and query the location registry.

Address normalization and suggestion are backed by a curated Angola geo registry. The geo routes return provinces, municipalities, and commune data that can drive admin forms and autocomplete flows.

Routes

5 GET

Geo levels

Province to commune

Autocomplete

bairro + commune + municipality

Routes in this family

RoutePurposeKey query
/api/v1/address/normalizeClean and structure a free-text Angolan address.address
/api/v1/address/suggestSuggest bairros, communes, or municipalities.q, type, province, municipality
/api/v1/geo/provincesList all provinces in Angola.none
/api/v1/geo/municipalitiesList municipalities, optionally filtered by province.province
/api/v1/geo/communesList communes for a municipality.municipality, optional province

GET /api/v1/address/normalize

Use normalize to clean a free-text address before persisting it or matching it against internal records.

ParameterRequiredDescription
addressYesFree-text Angolan address. Common abbreviations such as `prov.` and `mun.` are expanded automatically.
GNU BashcURL usage
curl -s "https://utils.api.orb3x.com/api/v1/address/normalize?address=Benfica,%20Luanda"
JSON200 response
{  "input": "Benfica, Luanda",  "normalized": "Benfica, Luanda",  "components": {    "bairro": "Benfica",    "commune": "Benfica",    "municipality": "Belas",    "province": "Luanda"  },  "diagnostics": {    "provinceMatched": true,    "municipalityMatched": true,    "communeMatched": true,    "bairroMatched": true  }}
JSONError response
{  "error": {    "code": "INVALID_ADDRESS",    "message": "The \"address\" query parameter is required.",    "field": "address"  }}

GET /api/v1/address/suggest

Use suggest to drive autocomplete fields for bairros, communes, municipalities, and provinces.

ParameterRequiredDescription
qYesSearch fragment.
typeNoOptional filter: `bairro`, `commune`, `municipality`, or `province`.
provinceNoOptional province filter.
municipalityNoOptional municipality filter.
limitNoMaximum number of suggestions to return.
GNU BashcURL usage
curl -s "https://utils.api.orb3x.com/api/v1/address/suggest?q=tal&type=municipality&province=Luanda"
JSON200 response
{  "query": "tal",  "suggestions": [    {      "type": "municipality",      "label": "Talatona",      "province": "Luanda",      "municipality": "Talatona"    }  ]}
JSONError response
{  "error": {    "code": "MISSING_QUERY_PARAMETER",    "message": "The \"q\" query parameter is required.",    "field": "q"  }}

GET /api/v1/geo/provinces

Use provinces as the top-level registry feed for location selectors and administrative filtering.

ParameterRequiredDescription
GNU BashcURL usage
curl -s "https://utils.api.orb3x.com/api/v1/geo/provinces"
JSON200 response
{  "country": "AO",  "countryName": "Angola",  "provinces": [    {      "name": "Luanda",      "slug": "luanda",      "capital": "Luanda",      "municipalityCount": 16    }  ]}
JSONError response
{  "error": {    "code": "INTERNAL_SERVER_ERROR",    "message": "Unexpected error while listing provinces."  }}

GET /api/v1/geo/municipalities

Use municipalities to populate second-level location selectors, with or without a province filter.

ParameterRequiredDescription
provinceNoOptional province name used to filter the list.
GNU BashcURL usage
curl -s "https://utils.api.orb3x.com/api/v1/geo/municipalities?province=Luanda"
JSON200 response
{  "province": "Luanda",  "municipalities": [    {      "name": "Talatona",      "slug": "talatona",      "province": "Luanda",      "communeCount": 2    }  ]}
JSONError response
{  "error": {    "code": "PROVINCE_NOT_FOUND",    "message": "No Angolan province matched the supplied query.",    "field": "province",    "value": "Atlantis"  }}

GET /api/v1/geo/communes

Use communes when a municipality is already selected and you need the next administrative level.

ParameterRequiredDescription
municipalityYesMunicipality name to expand.
provinceNoOptional province name used to disambiguate repeated municipality labels.
GNU BashcURL usage
curl -s "https://utils.api.orb3x.com/api/v1/geo/communes?municipality=Talatona&province=Luanda"
JSON200 response
{  "municipality": "Talatona",  "province": "Luanda",  "coverage": "curated",  "communes": [    { "name": "Cidade Universitaria", "slug": "cidade-universitaria" },    { "name": "Talatona", "slug": "talatona" }  ]}
JSONError response
{  "error": {    "code": "MISSING_QUERY_PARAMETER",    "message": "The \"municipality\" query parameter is required.",    "field": "municipality"  }}
Some municipalities use curated commune detail, while others currently expose seat-only coverage.