Overview
The Loccode API resolves a Nigerian address from a Maiaddy loccode in a single request. Send it a loccode and it responds with a structured, verified record that is consistent enough to drop straight into a checkout, KYC, or logistics flow.
What this API does
- Look up a full, verified address from a Maiaddy loccode.
- Get structured fields in one call: loccode, street, LGA, state, and country.
- Receive OSM-backed road metadata alongside each result.
How it works
- 1
You send a loccode
A Maiaddy loccode in the pattern XXXX XXX.
- 2
The API resolves it
Exact match on the loccode to its verified address record.
- 3
You get structured data
Street, LGA, state, country, and OSM road metadata in a consistent JSON envelope.
Verified data
Results come from validated Maiaddy records cross-referenced against OpenStreetMap road data. You never work with unverified free-text addresses.
Authentication
Every request requires a Bearer token. Pass your API key in the Authorization header.
Authorization: Bearer YOUR_API_KEYKeep keys server-side
Never embed an API key in client-side code. Proxy requests through your backend or use the SDKs with token exchange for browser and mobile apps.
Quickstart
Resolve an address from a loccode in under a minute. Replace YOUR_API_KEY with a key from the console.
Loccode search
/api/v1/addresses/search/loccode/:loccodecurl https://api.maiaddy.com/loccodeapi/api/v1/addresses/search/loccode/EN4A1DQ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"Example response
{
"loccode": "EN4A 1DQ",
"streetName": "Udoji Street",
"addresses": [
"Udoji Street"
],
"lga": "Enugu North LGA",
"state": "Enugu State",
"streetInfo": {
"name": "Udoji Street",
"highwayType": "residential",
"length": 543.33,
"osmId": 174525750
},
"country": "NG"
}Search by loccode
/api/v1/addresses/search/loccode/:loccodeResolve a single address from a Maiaddy loccode. Loccodes are exact identifiers — one loccode maps to one address record.
Path parameters
loccoderequiredcurl https://api.maiaddy.com/loccodeapi/api/v1/addresses/search/loccode/EN4A1DQ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"Example response
{
"loccode": "EN4A 1DQ",
"streetName": "Udoji Street",
"addresses": [
"Udoji Street"
],
"lga": "Enugu North LGA",
"state": "Enugu State",
"streetInfo": {
"name": "Udoji Street",
"highwayType": "residential",
"length": 543.33,
"osmId": 174525750
},
"country": "NG"
}Response fields
loccodeoptionalstreetNameoptionaladdressesoptionallgaoptionalstateoptionalstreetInfooptionalname, highwayType, length (metres), osmId.countryoptionalSDKs
Official SDKs for JavaScript, Python, Java, and Go wrap every endpoint, handle auth, and provide typed response models. See the quickstart above for raw HTTP examples and the SDK pages for installation.
Browse SDKsRecommended UI flow
The shape of a good loccode entry experience — five steps from input to auto-filled address fields.
- 1
Input field
A dedicated input labelled "Enter loccode" or "Location code".
- 2
Live validation
Validate format as the user types. Loccodes follow the pattern XXXX XXX.
- 3
API call
On a valid value, call /api/v1/addresses/search/loccode/:loccode.
- 4
Selection
Render returned addresses in a dropdown or list for the user to pick from.
- 5
Auto-fill
Populate your address form with the selected address record.
React component example
import { useState } from "react";
export function AddressLookup() {
const [loccode, setLoccode] = useState("");
const [addresses, setAddresses] = useState<string[]>([]);
const [loading, setLoading] = useState(false);
const handleSearch = async () => {
setLoading(true);
const response = await fetch(
`https://api.maiaddy.com/loccodeapi/api/v1/addresses/search/loccode/${loccode}`,
{
headers: { Authorization: "Bearer YOUR_API_KEY" },
}
);
const data = await response.json();
setAddresses(data.addresses ?? []);
setLoading(false);
};
return (
<div>
<input
value={loccode}
onChange={(e) => setLoccode(e.target.value)}
placeholder="Enter loccode"
/>
<button onClick={handleSearch} disabled={loading}>
{loading ? "Searching…" : "Find addresses"}
</button>
{addresses.length > 0 && (
<ul>
{addresses.map((address) => (
<li key={address}>{address}</li>
))}
</ul>
)}
</div>
);
}Common use cases
E-commerce checkout
Customer enters a loccode and selects an address. Shipping fields auto-populate with verified location data.
KYC & identity
User provides a loccode during onboarding. Financial institutions retrieve a verified address linked to the location.
Logistics & delivery
Drivers enter a recipient's loccode to retrieve every delivery point at that location — residential, business, or pickup.
Service provision
Utility companies, ISPs, and home-services use loccodes to identify service locations and plan installations.