@some19ice/nigeria-geo-logistics

Comprehensive logistics utilities for Nigerian e-commerce - shipping zones, LGA classifications, and postal codes for all 774 Local Government Areas.

Installation

npm install @some19ice/nigeria-geo-logistics @some19ice/nigeria-geo-core
# or
pnpm add @some19ice/nigeria-geo-logistics @some19ice/nigeria-geo-core

Features

• ✅ Complete LGA Classifications - Urban, semi-urban, rural, and riverine classifications for all 774 LGAs
• ✅ Full Postal Code Coverage - NIPOST postal codes for all Nigerian LGAs
• ✅ Smart Shipping Zones - 5-zone shipping calculation based on origin, destination, and terrain
• ✅ Special Handling Detection - Automatic identification of riverine areas requiring water transport
• ✅ Type-Safe - Full TypeScript support with comprehensive types

Usage

LGA Classifications

import {
  getLGAClassification,
  isUrban,
  isSemiUrban,
  isRural,
  isRiverine,
  getLGAsByClassification,
  getClassificationCounts,
  requiresSpecialHandling,
} from '@some19ice/nigeria-geo-logistics';

// Get classification for any LGA
getLGAClassification('ikeja');    // 'urban'
getLGAClassification('ikorodu');  // 'semi-urban'
getLGAClassification('kuje');     // 'rural'
getLGAClassification('bonny');    // 'riverine'

// Boolean helpers
isUrban('ikeja');       // true
isSemiUrban('ikorodu'); // true
isRural('kuje');        // true
isRiverine('bonny');    // true

// Check if special handling is required (water transport)
requiresSpecialHandling('bonny'); // true
requiresSpecialHandling('ikeja'); // false

// Get all LGAs by classification
const urbanLGAs = getLGAsByClassification('urban');
// ['ikeja', 'lagos-island', 'kano-municipal', ...]

const riverineLGAs = getLGAsByClassification('riverine');
// ['bonny', 'brass', 'degema', 'southern-ijaw', ...]

// Get counts per classification
const counts = getClassificationCounts();
// { urban: 45, 'semi-urban': 180, rural: 520, riverine: 29 }

Postal Codes

import {
  getPostalCode,
  getStatePostalPrefix,
  isValidPostalCodeFormat,
  getLGAByPostalCode,
  getPostalCodesByState,
  getLGAsWithPostalCodes,
  getPostalCodesCount,
} from '@some19ice/nigeria-geo-logistics';

// Get postal code for any LGA
getPostalCode('ikeja');                   // '100001'
getPostalCode('municipal-area-council');  // '900001' (Abuja)
getPostalCode('kano-municipal');          // '700001'
getPostalCode('port-harcourt');           // '500001'

// Get state postal prefix
getStatePostalPrefix('lagos'); // '100'
getStatePostalPrefix('kano');  // '700'
getStatePostalPrefix('fct');   // '900'

// Validate postal code format (6 digits)
isValidPostalCodeFormat('100001'); // true
isValidPostalCodeFormat('12345');  // false (5 digits)

// Find LGA by postal code
getLGAByPostalCode('100001'); // 'ikeja'

// Get all postal codes in a state
const lagosPostalCodes = getPostalCodesByState('lagos');
// { ikeja: '100001', 'lagos-island': '101001', ... }

// Get coverage stats
getPostalCodesCount(); // 774

Shipping Zones

import {
  getShippingZone,
  getSimpleZone,
} from '@some19ice/nigeria-geo-logistics';

// Full shipping zone calculation
const zone = getShippingZone('lagos', 'ikeja', 'rivers', 'bonny');
// {
//   zone: 5,
//   originClassification: 'urban',
//   destinationClassification: 'riverine',
//   specialHandling: true,
//   reason: 'Distant region, riverine destination - maximum zone'
// }

// Same state delivery
const local = getShippingZone('lagos', 'ikeja', 'lagos', 'eti-osa');
// { zone: 1, specialHandling: false, reason: 'Same state delivery' }

// Same state but riverine
const riverine = getShippingZone('rivers', 'port-harcourt', 'rivers', 'bonny');
// { zone: 3, specialHandling: true, reason: 'Same state, but riverine destination requires water transport' }

// Simple zone calculation (by states only)
getSimpleZone('lagos', 'lagos'); // 1 (same state)
getSimpleZone('lagos', 'ogun');  // 2 (same region)
getSimpleZone('lagos', 'edo');   // 3 (adjacent region)
getSimpleZone('lagos', 'borno'); // 4 (distant region)

API Reference

Classifications

| Function | Description | |----------|-------------| | getLGAClassification(lgaId) | Returns 'urban', 'semi-urban', 'rural', or 'riverine' | | isUrban(lgaId) | Check if LGA is urban | | isSemiUrban(lgaId) | Check if LGA is semi-urban | | isRural(lgaId) | Check if LGA is rural | | isRiverine(lgaId) | Check if LGA is riverine (water transport required) | | getLGAsByClassification(type) | Get all LGA IDs with given classification | | getClassificationCounts() | Get count of LGAs per classification | | requiresSpecialHandling(lgaId) | Check if special handling is needed | | getClassifiedCount() | Get total number of classified LGAs |

Postal Codes

| Function | Description | |----------|-------------| | getPostalCode(lgaId) | Get 6-digit NIPOST postal code | | getStatePostalPrefix(stateId) | Get 3-digit state prefix | | isValidPostalCodeFormat(code) | Validate postal code format | | getLGAByPostalCode(code) | Find LGA by postal code | | getPostalCodesByState(stateId) | Get all postal codes in a state | | getLGAsWithPostalCodes() | Get all LGA IDs with postal codes | | getPostalCodesCount() | Get total postal codes count |

Shipping Zones

| Function | Description | |----------|-------------| | getShippingZone(originState, originLGA, destState, destLGA) | Full zone calculation with details | | getSimpleZone(originState, destState) | Simple zone by states only |

Shipping Zone Guide

| Zone | Description | Examples | |------|-------------|----------| | 1 | Same state, urban | Lagos → Lagos | | 2 | Same state rural, OR same region urban | Lagos → Ogun | | 3 | Same region rural, OR adjacent region urban, OR same state riverine | Lagos → Edo | | 4 | Adjacent region rural, OR distant region urban | Lagos → Rivers | | 5 | Distant region rural/riverine | Lagos → Borno, Any → Bonny |

Classification Criteria

| Type | Description | Characteristics | |------|-------------|-----------------| | Urban | Major cities | State capitals, commercial centers, full logistics infrastructure | | Semi-urban | Secondary cities | Growing suburbs, university towns, moderate infrastructure | | Rural | Agricultural areas | Remote areas, limited road access, extended delivery times | | Riverine | Water-access areas | Niger Delta, islands, requires boat/water transport |

State Postal Prefixes

| Prefix | States | |--------|--------| | 100-109 | Lagos | | 110-119 | Ogun | | 200-209 | Oyo | | 300-319 | Edo | | 400-419 | Enugu | | 500-519 | Rivers | | 700-719 | Kano | | 800-819 | Kaduna | | 900-909 | FCT (Abuja) |

Data Sources

Classification and postal code data are derived from:

• NIPOST (Nigerian Postal Service) official postal codes
• National Population Commission urbanization data
• National Bureau of Statistics demographic classifications
• Geographic research on riverine/coastal areas in Niger Delta

License

MIT