nepgeo

TypeScript-first geospatial and administrative toolkit for Nepal 🇳🇵 Accurate, structured data and utilities for Nepal's 7 Provinces, 77 Districts, 753 Local Levels, and 6,743+ Wards. Built for Node.js, React, Next.js, Vue, Svelte, and TypeScript applications.

Features

• Official Federal Structure: 7 Provinces, 77 Districts, 753 Local Levels (Metros, Sub-Metros, Municipalities, Rural Municipalities), and 6,743+ Wards.
• Bilingual Support: Official English names and accurate Nepali (Devanagari) spellings with automatic zero-width space and diacritic normalization.
• Geographic Centroids: Exact coordinates (WGS84) for spatial queries and mapping.
• Standard GeoJSON: RFC 7946 compliant GeoJSON Polygons and Points for Leaflet, Mapbox, OpenLayers, etc.
• Fast Fuzzy Search: Search across provinces, districts, and local levels in English or Devanagari with Levenshtein fuzzy ranking.
• Geospatial Distance: Find the nearest district or local level from latitude & longitude using Haversine calculation.
• Postal Codes: 5-digit postal codes for all 77 districts and general/area post offices.
• 100% Type-Safe: Zero runtime dependencies, pre-compiled static lookups with $O(1)$ indexing.

Installation

npm install nepgeo

Or using yarn / pnpm / bun:

# Yarn
yarn add nepgeo

# pnpm
pnpm add nepgeo

# Bun
bun add nepgeo

Quick Start

import { Nepal } from 'nepgeo';

// 1. Get all 7 provinces
const provinces = Nepal.provinces();

// 2. Get districts in a specific province
const bagmatiDistricts = Nepal.districts('Bagmati');

// 3. Get all metropolitan cities
const metros = Nepal.localLevels({ type: 'metropolitan' });

// 4. Resolve a specific entity
const kathmandu = Nepal.getDistrict('Kathmandu');
const tokha = Nepal.getMunicipality('Tokha');
const ward5 = Nepal.getWard('Tokha', 5);

// 5. Bilingual search (English or Devanagari)
const searchResults = Nepal.search('पोखरा');

// 6. Find nearest district from GPS coordinates
const nearest = Nepal.findNearest({
  latitude: 27.7172,
  longitude: 85.3240,
});

API Reference

Provinces

Nepal.provinces()

Returns all 7 provinces of Nepal.

const provinces = Nepal.provinces();

Nepal.getProvince(identifier)

Retrieves a single province by its numerical ID (1 to 7), English name, Nepali name, or code slug.

Nepal.getProvince(3);
Nepal.getProvince('Bagmati');
Nepal.getProvince('बागमती प्रदेश');

Districts

Nepal.districts(provinceFilter?)

Returns all 77 districts, optionally filtered by parent province.

const allDistricts = Nepal.districts();
const gandakiDistricts = Nepal.districts('Gandaki');

Nepal.getDistrict(identifier)

Retrieves a district by ID (1 to 77), English name, Nepali name, or slug.

Nepal.getDistrict('Kathmandu');
Nepal.getDistrict('काठमाडौँ');
Nepal.getDistrict(30);

Local Levels (Municipalities & Rural Municipalities)

Nepal.localLevels(filter?)

Returns local levels matching the optional filter criteria.

Nepal.localLevels(); // All 753 local levels
Nepal.localLevels({ district: 'Kathmandu' });
Nepal.localLevels({ type: 'metropolitan' });

Nepal.getLocalLevel(identifier, districtNameOrId?)

Finds any local level by name, code, or ID.

Nepal.getLocalLevel('Tokha');
Nepal.getLocalLevel('टोखा', 'Kathmandu');

Nepal.getMunicipality(name, district?)

Helper for finding a municipality, sub-metropolitan, or metropolitan city.

Nepal.getRuralMunicipality(name, district?)

Helper for finding a rural municipality (गाउँपालिका).

Wards

Nepal.getWard(localLevel, wardNumber)

Retrieves a specific ward with complete local level and district hierarchy.

const ward = Nepal.getWard('Tokha', 5);

Nepal.getWards(localLevel)

Returns all wards for a given local level.

const wards = Nepal.getWards('Kathmandu'); // Array of 32 wards

Search & Fuzzy Matching

Nepal.search(query, options?)

Bilingual search across all administrative levels with fuzzy matching and relevancy scoring.

// English search
const r1 = Nepal.search('Kathmandu');

// Nepali Devanagari search
const r2 = Nepal.search('काठमाडौँ');

// Search restricted to districts
const r3 = Nepal.search('Lumbini', { level: 'district' });

Geospatial & Nearest Entity

Nepal.findNearest(coords, options?)

Calculates great-circle distance using Haversine algorithm (WGS84) to locate the closest district or local level.

const nearest = Nepal.findNearest({
  latitude: 27.7172,
  longitude: 85.3240,
});
// Returns: { item: District, level: 'district', distanceKm: 0.82 }

Postal Codes

Nepal.postalCodes(district?)

Returns 5-digit postal codes for post offices in Nepal.

Nepal.getPostalCode(code)

Looks up a postal code by code or post office name.

GeoJSON Support

RFC 7946 compliant GeoJSON generators:

const countryGeoJSON = Nepal.getNepalGeoJSON();
const provincesGeoJSON = Nepal.getProvincesGeoJSON();
const bagmatiGeoJSON = Nepal.getProvinceGeoJSON('Bagmati');
const districtsGeoJSON = Nepal.getDistrictsGeoJSON();

Data Integrity & Sources

All data in nepgeo has been verified against primary official publications:

1. Ministry of Federal Affairs and General Administration (MoFAGA): Nepal Gazette notification 2073-11-27 BS and subsequent administrative adjustments.
2. National Statistics Office (NSO) / Central Bureau of Statistics (CBS): National Population and Housing Census 2021 (NPHC 2021 / 2078 BS).
3. Survey Department of Nepal: Official boundary references and WGS84 datum.
4. General Post Office (GPO) Nepal: Postal Code Directory.

License

MIT (c) Ankit Khatri KC