Naija Address Normalizer

Converts informal, landmark-based Nigerian addresses into structured JSON.

In Nigeria (and much of Africa) people locate places by landmarks and relative directions rather than street numbers — "opposite Chicken Republic, after Mobil, Lekki Phase 1". Standard geocoders (Google, Nominatim, Pelias) are built for structured addresses and stumble on these. This model handles the first step: turning the messy text into clean fields a geocoder can work with.

Scope: this model does not predict coordinates. It outputs structured fields; pass them to a geocoder (Nominatim / Photon / Pelias) for lat-long.

Example

Input

Opposite Chicken Republic after Mobil filling station, Lekki Phase 1

Output

{
  "landmarks": [
    {"name": "Chicken Republic", "relation": "opposite", "qualifier": null},
    {"name": "Mobil Filling Station", "relation": "after", "qualifier": null}
  ],
  "area": "Lekki Phase 1",
  "city": "Lagos",
  "state": "Lagos",
  "country": "Nigeria"
}

Output schema

field	type	notes
`landmarks`	list of objects	each has `name`, `relation`, `qualifier`
`landmarks[].name`	string	canonical landmark name
`landmarks[].relation`	string \| null	`opposite`, `beside`, `behind`, `before`, `after`, `near`, `under`, `inside`, `at`
`landmarks[].qualifier`	string \| null	e.g. `"blue gate"`, `"second gate"`, `"the junction"`
`area`	string \| null	neighbourhood / district
`city`	string \| null	inferred from area
`state`	string \| null	inferred from area
`country`	string	always `"Nigeria"` for this model

Usage

from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
import json

mid = "sobowalebukola/naija-address-normalizer"
tok = AutoTokenizer.from_pretrained(mid)
model = AutoModelForSeq2SeqLM.from_pretrained(mid)

PREFIX = "normalize nigerian address to json: "
text = "blue gate beside zenith bank, close to ajah roundabout"
enc = tok(PREFIX + text, return_tensors="pt")
out = model.generate(**enc, max_length=192, num_beams=4)
print(json.loads(tok.decode(out[0], skip_special_tokens=True)))

Training data

Synthetically generated which deliberately models how Nigerians actually write addresses: relation variants and abbreviations (opp, b/4), shortened names (GTB), qualifiers (blue gate, second gate), light Pidgin connectors, casing noise, dropped commas, and typos. Landmark/area pools cover Lagos heavily plus Abuja, Port Harcourt, Ibadan, Kano, Enugu and more.

~20,000 examples, split 80/10/10 (train/val/test)
relations constrained to be physically sensible per landmark category

Limitations

Synthetic data ceiling. Real user input will contain phrasings the generator never produced. Replace/augment with real labelled addresses as soon as you can collect them — that is the highest-leverage improvement.
Closed landmark vocabulary. Landmarks outside the generation pool may be mis-segmented. Expand the pools (e.g. from OpenStreetMap POIs) to broaden coverage.
No coordinates. Geocoding is a separate, harder stage; structured output here does not guarantee a downstream geocoder can resolve the landmark.
under is rare in the data (bridges only), so expect weaker performance there.

Reproduce

pip install -r requirements.txt
python generate_dataset.py --n 8000 --out data
python train.py --model google/flan-t5-base --epochs 5 --bs 16 --fp16
python evaluate.py --model checkpoints --data data

Loading…