naija-address-normalizer

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

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