sl-address

TypeScript utilities for exploring Sri Lanka provinces, districts, cities, and postal codes. Ship a single package and unlock lookups, fuzzy search, and readable formatting for any Sri Lankan address workflow.

Features

• Complete dataset covering every Sri Lankan postal code with its city, district, and province
• Friendly lookup helpers for provinces, districts, cities, and postal codes
• JSON-first responses that drop straight into APIs, CLIs, or UIs
• Fuzzy search, auto-complete, and normalization helpers to tidy user input

Install

npm install sl-address

Quick Start

import postalService, { p } from 'sl-address';

// `p` and the default export reference the same PostalService instance.
console.log(p.getProvinces());
console.log(p.getInfoByPostal('10280'));
console.log(postalService.toReadable('10280')); // "Maharagama, Colombo, Western Province"

CommonJS usage:

const { p } = require('sl-address');

console.log(p.getDistrictsByProvince('Western Province'));

All methods return JSON-friendly data (arrays, objects, or strings) so they can be serialized or sent over the wire without extra work.

API Overview

• getProvinces() – every province ("Western Province", "Central Province", ...)
• getDistricts() – every district name
• getCities() – every city name
• getPostals() – full dataset of postal records
• getDistrictsByProvince(province) – districts within a province
• getCitiesByDistrict(district) – cities in a district
• getCitiesByProvince(province) – cities in a province
• getPostalsByDistrict(district) – postal records for a district
• getPostalsByProvince(province) – postal records grouped by district
• getPostalsByCity(city) – postal records for a city
• getInfoByPostal(code) – full record for a code
• getInfoByCity(city) – all records matching a city (handles multiple codes)
• getDistrictByPostal(code) / getProvinceByPostal(code) / getCityByPostal(code) – individual fields
• isValidPostal(code) – boolean existence check
• searchCity(query, limit?) – fuzzy matches with scores
• autocompleteCity(prefix, limit?) – suggestion list for partial input
• normalize(input) – best-guess canonical city name
• toReadable(code) – formatted string "City, District, Province"

Inputs ignore case, spacing, and whether "Province" is appended (e.g., "Western" works).

Fuzzy helpers

p.normalize('maha ragama'); // "Maharagama"
p.searchCity('galleo');     // close matches with similarity scores
p.autocompleteCity('kan');  // ["Kandy", "Kananke Bazaar", ...]

License

MIT © Sumudu Kulathunga