Somalia Geo 🇸🇴

A lightweight JavaScript library and CLI tool for Somalia's administrative divisions and geographic data. Get regions, districts, cities, and their relationships with a simple API.

Features

• 🗺️ Complete coverage: 18 regions, 100+ districts and cities
• 🔍 Smart search: Find places by name or aliases with fuzzy matching
• 🎯 Advanced filtering: Filter by type, region, population, area, and more
• 🏗️ Hierarchical data: Navigate parent-child relationships
• 📍 Distance calculations: Find nearest places (when coordinates available)
• 📊 Data statistics: Get insights about regions, populations, and coverage
• 🖥️ Enhanced CLI: Powerful command-line interface with advanced features
• 📦 Lightweight: Minimal dependencies, fast loading
• 🔧 TypeScript support: Full type definitions included
• 🚀 Fuzzy search: Typo-tolerant search powered by Fuse.js

Installation

npm install somali-geo

Or use globally for CLI access:

npm install -g somali-geo

Quick Start

JavaScript API

const { 
  listRegions, 
  search, 
  fuzzySearch, 
  filter, 
  getByCode, 
  listChildren,
  getStats,
  getLargestByPopulation 
} = require("somali-geo");

// Get all regions
const regions = listRegions();
console.log(regions.length); // 18

// Search for places (exact match)
const results = search("Bosaso");
console.log(results[0].name); // "Bosaso"

// Fuzzy search (typo-tolerant)
const fuzzyResults = fuzzySearch("Bosasso", 5); // Finds "Bosaso"
console.log(fuzzyResults[0].name); // "Bosaso"

// Advanced filtering
const districts = filter({
  type: 'district',
  region: 'SO-BN',
  limit: 5
});

// Get place by code
const awdal = getByCode("SO-AW");
console.log(awdal.name); // "Awdal"

// Get statistics
const stats = getStats();
console.log(`Total places: ${stats.total}`); // 135

CLI Usage

# Basic commands
somaligeo regions                    # List all regions
somaligeo search Mogadishu          # Search for places
somaligeo code SO-BN                # Get place by code
somaligeo children SO-AW            # List districts in a region

# Enhanced commands
somaligeo fuzzy "Mogadisho" 5       # Fuzzy search (finds "Mogadishu")
somaligeo filter --type=district --region=SO-BN --limit=5
somaligeo stats                     # Get data statistics
somaligeo largest population 10    # Top 10 by population
somaligeo near 2.05 45.32 city 5 100  # Find nearest places

API Reference

Core Functions

listRegions()

Returns all 18 regions of Somalia.

const regions = listRegions();
// Returns: Array of region objects

search(query, options)

Search places by name or aliases (case-insensitive).

const results = search("Bosaso");
// Returns: Array of matching places

// With options
const results = search("Bosaso", { fuzzy: true, limit: 5 });

fuzzySearch(query, limit)

Typo-tolerant search powered by Fuse.js.

const results = fuzzySearch("Bosasso", 5); // Finds "Bosaso"
// Returns: Array of places with relevance scores

filter(criteria)

Advanced filtering with multiple criteria.

const districts = filter({
  type: ['district', 'city'],
  region: 'SO-BN',
  hasCoordinates: true,
  sortBy: 'name',
  sortOrder: 'asc',
  limit: 10
});
// Returns: Filtered and sorted array of places

getByCode(code)

Get a specific place by its code (case-insensitive).

const place = getByCode("SO-AW");
// Returns: Place object or null

listChildren(parentCode)

Get all child places (districts/cities) of a parent region.

const districts = listChildren("SO-BN");
// Returns: Array of child places

getStats()

Get comprehensive statistics about the dataset.

const stats = getStats();
// Returns: Object with totals, breakdowns by type/region, etc.

getLargestByPopulation(limit)

Get places sorted by population (when available).

const largest = getLargestByPopulation(10);
// Returns: Top 10 places by population

getLargestByArea(limit)

Get places sorted by area (when available).

const largest = getLargestByArea(5);
// Returns: Top 5 places by area

nearest(lat, lon, options)

Find nearest places to given coordinates.

const nearby = nearest(2.05, 45.32, {
  type: "city", // Filter by type (optional)
  limit: 5, // Max results (default: 5)
  radiusKm: 100, // Max distance in km (optional)
});
// Returns: Array of places with distance

Data Structure

Each place object contains:

interface Place {
  code: string; // Unique identifier (e.g., "SO-AW" for Awdal region)
  name: string; // Place name (e.g., "Awdal")
  type: PlaceType; // "region" | "district" | "city" | "town" | "village"
  parent: string | null; // Parent place code or null for regions
  lat?: number; // Latitude (when available)
  lon?: number; // Longitude (when available)
  aliases?: string[]; // Alternative names
}

Code Format: SO-XX-name where SO = Somalia, XX = region abbreviation, name = place name. See CODES.md for complete code explanations.

CLI Commands

Basic Commands

# Show help
somaligeo help

# List all regions
somaligeo regions

# Search places
somaligeo search <query>

# Get place by code
somaligeo code <CODE>

# List children of a place
somaligeo children <PARENT_CODE>

Advanced Commands

# Find nearest places
somaligeo near <lat> <lon> [type] [limit] [radiusKm]

# Examples
somaligeo near 2.05 45.32           # 5 nearest places
somaligeo near 2.05 45.32 city      # Nearest cities only
somaligeo near 2.05 45.32 city 3    # 3 nearest cities
somaligeo near 2.05 45.32 city 3 50 # Within 50km radius

Examples

Find all districts in Banaadir region (Mogadishu area)

const { listChildren } = require("somali-geo");

const mogadishuDistricts = listChildren("SO-BN");
console.log(`Mogadishu has ${mogadishuDistricts.length} districts:`);
mogadishuDistricts.forEach((district) => {
  console.log(`- ${district.name} (${district.code})`);
});

Search and explore hierarchy

const { search, listChildren } = require("somali-geo");

// Find a region
const results = search("Awdal");
const awdal = results[0];

// Get its districts
const districts = listChildren(awdal.code);
console.log(`${awdal.name} region has ${districts.length} districts`);

CLI workflow

# Find a region
somaligeo search Awdal

# Get its code from results: SO-AW
# List its districts
somaligeo children SO-AW

# Get details of a specific district
somaligeo code SO-AW-borama

Data Coverage

• 18 Regions: All major administrative regions
• 100+ Districts: Comprehensive district coverage
• Cities & Towns: Major urban centers
• Hierarchical: Proper parent-child relationships

📋 Need help with codes? See CODES.md for detailed explanations of all region and district codes.

Regions Included

• Awdal, Bakool, Banaadir, Bari, Bay
• Galguduud, Gedo, Hiiraan
• Jubbada Hoose, Jubbada Dhexe
• Mudug, Nugaal, Sanaag, Sool
• Shabeellaha Hoose, Shabeellaha Dhexe
• Togdheer, Woqooyi Galbeed

Development

Running Tests

# Run all tests
npm test

# Run specific test suites
npm run test:api    # API tests only
npm run test:cli    # CLI tests only

Project Structure

somali-geo/
├── src/
│   ├── index.js      # Main API
│   ├── index.d.ts    # TypeScript definitions
│   └── cli.js        # CLI tool
├── data/
│   └── places.json   # Geographic data
├── test/
│   ├── index.test.js # API tests
│   ├── cli.test.js   # CLI tests
│   └── run.js        # Test runner
└── package.json

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Adding Data

To add new places or coordinates:

1. Edit data/places.json
2. Follow the existing structure
3. Run tests to ensure data integrity
4. Submit a pull request

Code Style

• Use Node.js built-in modules when possible
• Keep dependencies minimal
• Follow existing code patterns
• Add tests for new features

License

MIT License - see LICENSE file for details.

Changelog

v0.1.0

• Initial release
• Complete administrative divisions data
• CLI tool with all basic commands
• TypeScript support
• Comprehensive test suite

Made with ❤️ for the Somali developer community