API Documentation

Introduction

Welcome to the Address Data API. Our RESTful API provides robust endpoints for Nigerian address validation, lookup, autocompletion, and access to structured geographical and real estate data. Empower your applications with accurate and verified information.

All API requests must be authenticated. Please refer to the Authentication section below.

Authentication

To authenticate your API requests, include your Public Key in the X-Public-Key header and your Private Key in the X-Private-Key header. You can generate your API keys from the developer portal.

Authentication Example:

// Example: Fetching data with authentication headers
fetch('https://api.addressdata.ng/v1/address/lookup-by-code/ADC123XYZ', {
  method: 'GET',
  headers: {
    'X-Public-Key': 'YOUR_PUBLIC_KEY',
    'X-Private-Key': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Rate Limits & Pricing

Get started with 500 free address lookups per day. This daily limit applies to endpoints like/autocomplete and /lookup-by-code.

Our standard pricing plan is designed to be simple and scalable:

• ₦20 per verified lookup after your free daily limit.
• Access to geographical data endpoints (/states, etc.) is generally not counted towards lookup limits but may be subject to fair use policies.

Note: Detailed standard pricing plans and billing information will be available soon.

API Base URL

All API endpoints are relative to the following base URL:

https://api.addressdata.ng/v1

Address Endpoints

$ https://api.addressdata.ng/v1/autocomplete?query=123 Allen Ave Ikeja

$ [
  {
    "adc": "ADC123XYZ",
    "formattedAddress": "123 Allen Avenue, Ikeja, Lagos",
    "streetAddress": "123 Allen Avenue",
    "city": "Ikeja",
    "lga": "Ikeja",
    "state": "Lagos"
  },
  // ... other suggestions
]

$ https://api.addressdata.ng/v1/lookup-by-code/ADC789ABC

$ {
  "adc": "ADC12345XYZ", // Address Data Code
  "streetAddress": "123 Main Street, XYZ Layout",
  "areaDistrict": "Ikeja GRA",
  "city": "Ikeja",
  "lga": "Ikeja",
  "state": "Lagos",
  "zipCode": "100001",
  "country": "Nigeria",
  "latitude": 6.5244,
  "longitude": 3.3792,
  "status": "verified",
  "googleMapsSuggestion": "123 Main St, Ikeja GRA, Ikeja, Lagos 100001, Nigeria"
}

Estates Endpoints

$ https://api.addressdata.ng/v1/estates

$ [
  { 
    "estateCode": "LAG-ETI-BNN01", 
    "name": "Banana Island Estate",
    "location": { "state": "Lagos", "lga": "Eti Osa" }
  },
  // ... other estates
]

$ https://api.addressdata.ng/v1/estates/LAG-ETI-PRV02

$ {
  "estateCode": "LAG-ETI-BNN01", // Unique Estate Code
  "name": "Banana Island Estate",
  "location": {
    "state": "Lagos",
    "lga": "Eti Osa",
    "area": "Ikoyi"
  },
  "googleMapLink": "https://maps.app.goo.gl/u5B1gY8Jz9W7xXaP7",
  "status": "approved"
}

Geography Endpoints

$ https://api.addressdata.ng/v1/states

$ [
  { "name": "Abia", "capital": "Umuahia" },
  { "name": "Lagos", "capital": "Ikeja" },
  // ... other states
]

$ https://api.addressdata.ng/v1/states/Lagos/lgas

$ [
  { "name": "Agege" },
  { "name": "Ikeja" },
  // ... other LGAs in Lagos
]

$ https://api.addressdata.ng/v1/states/Lagos/lga/Ikeja/cities

$ [
  { "name": "Ikeja" },
  { "name": "Oregun" },
  // ... other cities/towns in Ikeja LGA
]

Data Object Structures

Our API returns data in a structured JSON format. Developers are encouraged to replicate this structure for maximum compatibility.

Address Object

$ {
  "adc": "ADC12345XYZ", // Address Data Code
  "streetAddress": "123 Main Street, XYZ Layout",
  "areaDistrict": "Ikeja GRA",
  "city": "Ikeja",
  "lga": "Ikeja",
  "state": "Lagos",
  "zipCode": "100001",
  "country": "Nigeria",
  "latitude": 6.5244,
  "longitude": 3.3792,
  "status": "verified",
  "googleMapsSuggestion": "123 Main St, Ikeja GRA, Ikeja, Lagos 100001, Nigeria"
}

Estate Object

$ {
  "estateCode": "LAG-ETI-BNN01", // Unique Estate Code
  "name": "Banana Island Estate",
  "location": {
    "state": "Lagos",
    "lga": "Eti Osa",
    "area": "Ikoyi"
  },
  "googleMapLink": "https://maps.app.goo.gl/u5B1gY8Jz9W7xXaP7",
  "status": "approved"
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request.

• 200 OK: Request was successful.
• 400 Bad Request: The request was malformed (e.g., missing required parameters). The response body may contain more details.
• 401 Unauthorized: API key is missing or invalid.
• 403 Forbidden: API key is valid but does not have permission for the requested resource.
• 404 Not Found: The requested resource does not exist.
• 429 Too Many Requests: You have exceeded your rate limit.
• 500 Internal Server Error: Something went wrong on our end. Please try again later.

Error responses will typically include a JSON body with a message field explaining the error.