BASE APIv2.1

Basic Address Search Engine

Enable seamless address lookup in your applications. Users input a loccode, you retrieve all associated addresses. Simple integration, powerful results.

Instant Lookup

Retrieve all addresses associated with a loccode in milliseconds.

Verified Addresses

Link users to existing, validated addresses in the Maiaddy database.

Simplified UX

Reduce address entry from minutes to seconds for your users.

How it works

Your user enters a loccode (e.g. LA8A 1FU) in your application's address field. The BASE API returns all registered addresses at that location—residential units, businesses, points of interest. The user selects their specific address from the list, eliminating manual entry errors and ensuring data accuracy.

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 KeyView Pricing