Overview

The Basic Address Search Engine (Base API) resolves Nigerian addresses in a single request. Send it a loccode, a street name, or a GPS coordinate pair, 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 address from a Maiaddy loccode.
Search for streets that match a full or partial street name.
Convert GPS coordinates (latitude/longitude) into a verified Nigerian address.

How it works

1
You send input
A loccode, a street name, or a latitude/longitude pair.
2
The API resolves it
Exact match for loccodes, text search for streets, nearest-neighbour lookup for coordinates.
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 header

Authorization: Bearer YOUR_API_KEY

Keep 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.

GET

Loccode search

/api/v1/addresses/search/loccode/:loccode

Request

curl https://base-api.maiaddy.com/api/v1/addresses/search/loccode/EN4A1DQ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example response

200 OK

Success

{
  "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"
}

GET

Search by loccode

/api/v1/addresses/search/loccode/:loccode

Resolve a single address from a Maiaddy loccode. Loccodes are exact identifiers — one loccode maps to one address record.

Path parameters

loccoderequired

string

The Maiaddy loccode (e.g. EN4A 1DQ). URL-encode the space when passing it in the path.

Request

curl https://base-api.maiaddy.com/api/v1/addresses/search/loccode/EN4A1DQ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example response

200 OK

Success

{
  "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

loccodeoptional

string

Maiaddy loccode for the resolved location.

streetNameoptional

string

Primary street name for the segment.

addressesoptional

string[]

Address strings associated with the result.

lgaoptional

string

Local government area.

stateoptional

string

State or territory.

streetInfooptional

object

OSM-backed street metadata: name, highwayType, length (metres), osmId.

countryoptional

string

ISO 3166-1 alpha-2 country code.

GET

Search by coordinates

/api/v1/addresses/search/coordinates

Look up the closest verified address for a latitude/longitude pair. Useful for reverse-geocoding a tap on a map or a device GPS fix.

Query parameters

latituderequired

number

WGS-84 latitude in decimal degrees.

longituderequired

number

WGS-84 longitude in decimal degrees.

Request

curl "https://base-api.maiaddy.com/api/v1/addresses/search/coordinates?latitude=9.0579&longitude=7.4951" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

200 OK

Success

{
  "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"
}

GET

Search by street

/api/v1/addresses/search/street

Resolve loccode and address data by street name. Accepts full or partial street names.

Query parameters

streetNamerequired

string

Street name to resolve. URL-encode the value when passing it in the query string.

Request

curl "https://base-api.maiaddy.com/api/v1/addresses/search/street?streetName=Udoji%20Street" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

200 OK

Success

{
  "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"
}

SDKs

Official SDKs for JavaScript, Python, Java, and Go wrap every endpoint, handle auth, and ship typed response models. See the quickstart above for raw HTTP examples and the SDK pages for installation.

Browse SDKs

Recommended 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

AddressLookup.tsx

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://base-api.maiaddy.com/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.

Fewer failed deliveriesFaster checkout

KYC & identity

User provides a loccode during onboarding. Financial institutions retrieve a verified address linked to the location.

Fraud preventionCompliance

Logistics & delivery

Drivers enter a recipient's loccode to retrieve every delivery point at that location — residential, business, or pickup.

Precise routingDelivery confirmation

Service provision

Utility companies, ISPs, and home-services use loccodes to identify service locations and plan installations.

Accurate planningService verification