Nigerian Zip Code and Geolocation Plugin

A powerful Node.js package for handling Nigerian zip codes, Local Government Areas (LGAs), towns, cities, streets, and associated geographic information. This plugin provides functionalities for searching locations, retrieving latitude and longitude, calculating distances, and more—all without relying on paid third-party services like Google Maps.

Features

• Search Nigerian Locations: Find states, LGAs, towns/cities, streets, and zip codes.
• Geocoding: Automatically retrieve and store latitude and longitude for addresses.
• Distance Calculation: Calculate distances between two geographic points.
• Efficient Caching: Caches latitude and longitude results to minimize repeated lookups.
• Address Matching: Matches input addresses to known locations for quick retrieval.

Installation

• **To install the package, use npm:

npm install ngzipcode

Installation To install the package, use npm:

• After installing, you can require the plugin in your project: const ngZipCode = require('ngzipcode');

Here are some basic usage examples to get you started.

1. Searching for Available Streets by Location Retrieve available streets by searching with a state, LGA, town/city, or zip code.

 const streets = ngZipCode.getStreetsByLocation({
  state: 'Lagos',
  lga: 'Ikeja',
  town: 'Ikeja',
  zipCode: '101233'
});

console.log(streets);

2. Retrieving Coordinates of a Zip Code Automatically retrieve the latitude and longitude of a selected zip code. const coordinates = ngZipCode.getCoordinates('101233'); console.log(coordinates); // { lat: 6.5244, lng: 3.3792 }

3. Caching Coordinates on First Search When searching for a zip code, the plugin will cache the result for faster retrieval in subsequent searches.

ngZipCode.getCoordinates('101233'); // First call, retrieves and caches
ngZipCode.getCoordinates('101233'); // Subsequent call, fetches from cache

4. Address Matching and Geolocation Match addresses to known locations and get coordinates.

const address = "12 Allen Avenue, Ikeja, Lagos";
const matchedCoordinates = ngZipCode.matchAddressToCoordinates(address);
console.log(matchedCoordinates); // { lat: 6.5244, lng: 3.3792 }

5. Calculating Distance Between Two Locations Calculate distance in kilometers between two coordinates.

const coords1 = { lat: 6.5244, lng: 3.3792 };
const coords2 = { lat: 4.8151, lng: 7.0495 };
const distance = ngZipCode.calculateDistance(coords1, coords2);
console.log(`Distance: ${distance} km`);

API Documentation getStreetsByLocation(location) Description: Retrieve a list of streets by searching with location details.

Parameters:

location (Object): An object that may contain any combination of state, lga, town, or zipCode. Returns:

(Array): A list of streets matching the specified location. Example:

javascript Copy code ngZipCode.getStreetsByLocation({ state: 'Lagos', lga: 'Ikeja' }); getCoordinates(zipCode) Description: Retrieves the latitude and longitude of a specified zip code, caching the result for faster subsequent searches.

Parameters:

zipCode (String): A valid 6-digit Nigerian zip code. Returns:

(Object): An object containing lat and lng values. Example:

ngZipCode.getCoordinates('101233'); matchAddressToCoordinates(address) Description: Matches an address to known locations and retrieves corresponding latitude and longitude.

Parameters:

address (String): A full or partial address. Returns:

(Object): An object containing lat and lng values. Example:

javascript Copy code ngZipCode.matchAddressToCoordinates("12 Allen Avenue, Ikeja, Lagos"); calculateDistance(coords1, coords2) Description: Calculates the distance between two geographic points.

Parameters:

coords1 (Object): Starting coordinates, with lat and lng properties. coords2 (Object): Ending coordinates, with lat and lng properties. Returns:

(Number): The distance in kilometers between the two points. Example:

javascript Copy code const distance = ngZipCode.calculateDistance({ lat: 6.5244, lng: 3.3792 }, { lat: 4.8151, lng: 7.0495 }); Data Caching This plugin caches coordinates for each zip code on the first lookup to improve performance on subsequent calls. The cache is reset when the application restarts.

Error Handling All methods perform basic validation, but incorrect input formats (e.g., an invalid zip code) may return null or an error message. Always validate input data before calling these methods.

Contributing If you’d like to contribute to this package, feel free to fork the repository, make your changes, and submit a pull request. Contributions to add more locations, refine algorithms, or improve caching are welcome!

License This package is licensed under the MIT License. See LICENSE for details.