🇳🇬 @zheeno/9ja-postal-codes

A modern, type-safe, and lightweight utility library for querying Nigerian postal codes, Local Government Areas (LGAs), and States.

🧐 The Problem

For years, developers building applications for the Nigerian market have struggled with a lack of standardized, easily accessible postal data. @zheeno/9ja-postal-codes solves this by providing:

• Centralized Data: A single source of truth for Nigeria's 36 states + FCT.
• Granular Precision: Precise street-level data for residential and commercial hubs.
• Developer Experience: A smooth, typed API that works in both ESM and CJS.

✨ Features

• 📍 Postcode Lookup: Instantly find State and LGA for any valid 6-digit Nigerian postal code.
• 🏛️ Comprehensive Coverage: Includes all 774 Local Government Areas.
• 💪 TypeScript Native: Full IntelliSense and type safety.
• ⚡️ Zero Dependencies: Ultra-fast and lightweight.

🚀 Installation

npm install @zheeno/9ja-postal-codes

🛠️ Usage

Modern JavaScript/TypeScript (ESM)

import { getLgaByPostcode, getStates, findLocationByPostcode } from '@zheeno/9ja-postal-codes';

// 1. Find LGA from a postal code
const lga = getLgaByPostcode('240104'); 
console.log(lga); // 'Asa'

// 2. Comprehensive lookup
const location = findLocationByPostcode('100275');
// { state: 'Lagos', lga: 'Lagos Island' }

// 3. List all states
const states = getStates();

📚 API Reference

getStates(): string[]

Returns a list of all Nigerian States including the FCT.

getLgasByState(state: string): string[]

Fetch all unique LGAs belonging to a specific state. Search is case-insensitive.

getStreetsByLga(state: string, lga: string): string[]

Returns an array of unique street names in a specific LGA and state.

const streets = getStreetsByLga('Lagos', 'Ikeja');
// ['Abeokuta Express Way', 'Allen Avenue', ...]

getStreetsByState(state: string): string[]

Returns an array of all unique street names in a specific state.

findLocationByPostcode(postcode: string): LocationInfo | null

Returns the State and LGA for a given 6-digit code.

const location = findLocationByPostcode('100271');
// { state: 'Lagos', lga: 'Ikeja' }

getLgaByPostcode(postcode: string): string | null

Convenience helper to get just the LGA name from a postcode.

getStateByPostcode(postcode: string): string | null

Convenience helper to get just the State name from a postcode.

📐 Data Structure (TypeScript)

export interface LocationRecord {
  state: string;
  lga: string;
  postal_codes: string[];
  streets: string[];
}

🤝 Contributing

Contributions are welcome! If you find a missing postal code or a typo in a street name, feel free to submit a Pull Request.

📄 License

Distributed under the MIT License.

Built with ❤️ for the Nigerian dev community.