Base API v1.0

Basic Address Search Engine

Version

v1.0

Base URL

https://base-api.maiaddy.com/api

Protocol

REST / JSON

Auth

Bearer Token (API Key)

Coverage

Nigeria

Response

JSON

Get API Key

Overview

The Basic Address Search Engine (BASE) API is how you resolve addresses in Nigeria programmatically. Send it a loccode, a street name, or a GPS coordinate pair, and it responds with a structured, verified address that is clean, consistent, and ready for your application.

What this API does

  • Looks up a full address from a loccode — the Maiaddy location identifier.
  • Searches for streets that match a full or partial street name.
  • Converts GPS coordinates (latitude/longitude) into a verified Nigerian address.

How it works: the 3-step flow

Every request to the BASE API follows the same pattern:

  1. You send input: a Loccode, a street name, or lat/lng coordinates.
  2. The API resolves it: an exact match for loccode, a text search for street name, and a nearest-neighbour lookup for coordinates.
  3. You get back structured data: street name, LGA, state, country, and road metadata all in consistent JSON.

Note

All results are drawn from validated records in the Maiaddy database, cross-referenced against OpenStreetMap road data. You are never working with unverified free-text addresses.

Authentication

All API requests require authentication using your API key. Include it in the Authorization header.

Authorization Header
Authorization: Bearer YOUR_API_KEY

Security Note

Never expose your API key in client-side code. Use backend proxies or our SDKs with token exchange for frontend implementations.

Quickstart

Make your first API call in under 5 minutes.

GET

Location Code Search

Request
curl https://base-api.maiaddy.com/api/v1/addresses/search/loccode/:loccode \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"loccode": "EN4A 1DQ",
"include_metadata": true
}'

Expected Response

200 OK
Success
{
  "loccode": "EN4A 1DQ",
  "Udoji Street": "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

Street search

Look up loccode and address data by street name. Use the query parameter streetName (replace the placeholder in the URL below).

https://base-api.maiaddy.com/api/v1/addresses/search/street?streetName=:streetName

Query Parameters

streetNamerequired
string

Street name to resolve (URL-encoded when passed in the query string).

Request
curl "https://base-api.maiaddy.com/api/v1/addresses/search/street?streetName=Udoji Street" \
-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"
}

SDK Implementation

Use our official SDKs for JavaScript, Python, Java, and Go to integrate the BASE API with minimal boilerplate. See Quickstart for examples.

UI Integration

Implement the loccode search field in your application interface.

Recommended Flow

1
Input Field

User types loccode into a dedicated field labeled "Enter Loccode" or "Location Code"

2
Validation

Real-time format validation as user types (pattern: XXXX XXX)

3
API Call

On valid input or user confirmation, call /api/v1/addresses/search/loccode/:loccode

4
Selection

Present returned addresses in a dropdown or modal for user selection

5
Auto-fill

Populate your address form fields with selected address data

React Component Example
import { useState } from 'react';

function AddressLookup() {
  const [loccode,setLoccode] = useState('');
  const [addresses,setAddresses] = useState([]);
  const handleSearch = async () => {
    setLoading(true);
    const response = await fetch('https://base-api.maiaddy.com/api/v1/addresses/search/loccode/:loccode ', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ loccode, include_metadata: true }),
    });
    const data = await response.json();
    setAddresses(data.addresses || []);
    setLoading(false);
  };
  return (
    <div>
      <input placeholder="Enter loccode" value={loccode} onChange={(e) => setLoccode(e.target.value)} />
      <button onClick={handleSearch} disabled={loading}> {loading ? 'Searching...' : 'Find Addresses'}</button>
    </div>
  );
}

Common Use Cases

E-commerce Checkout

Customer enters loccode, selects their address from dropdown. Shipping address auto-populated with verified location data.

Reduces failed deliveriesFaster checkout

KYC & Identity Verification

User provides loccode during onboarding. Financial institution retrieves verified address linked to that location.

Fraud preventionRegulatory compliance

Logistics & Delivery

Driver enters recipient's loccode to retrieve all possible delivery points at that location—residential, business, or pickup point.

Precise routingDelivery confirmation

Service Provision

Utility companies, internet providers, and home services use loccodes to identify service locations and plan installations.

Accurate planningService verification

Ready to integrate?

Get your API keys and start building with the BASE API. Free tier includes 10,000 requests per month.

Get API Key