Mavenge Localities

A comprehensive NestJS library providing global access to Geoapify localities data for geographic location services. This library enables developers to easily search, filter, and retrieve location data from 186,892 localities across all 217 countries worldwide.

🌍 Global Coverage Achieved!

Version 3.0.0 represents the world's most comprehensive locality dataset:

• ✅ All 217 Countries Covered - Complete global reach
• 🌟 186,892 Total Localities - Massive scale from cities to villages
• 🏆 Enterprise Grade - Production-ready for global applications
• 📊 Top Countries: China (5,114), USA (4,211), India (2,587), Russia (2,368), Brazil (2,352)

Table of Contents

• 🌍 Global Coverage Achieved!
• Features
• Installation
• Quick Start
• API Reference
• Types and Interfaces
• Examples
• 📊 Data Coverage & Statistics
• Data Source
• Contributing
• License
• Support

Features

• 🌍 Comprehensive Locality Data: Access to cities, towns, regions, and administrative divisions worldwide
• 🔍 Advanced Search: Search by name, country, region, coordinates, and more
• 📍 Geospatial Queries: Find localities within bounding boxes or near specific points
• 🚀 NestJS Integration: Seamlessly integrates with NestJS applications
• 📊 TypeScript Support: Full TypeScript support with comprehensive type definitions
• ⚡ High Performance: Optimized for fast searches and efficient data access
• 🧪 Well Tested: Comprehensive test suite included

Installation

npm install mavenge-localities

Quick Start

1. Import the Module

import { Module } from '@nestjs/common';
import { LocalitiesModule } from 'mavenge-localities';

@Module({
  imports: [LocalitiesModule],
})
export class AppModule {}

2. Inject the Service

import { Injectable } from '@nestjs/common';
import { LocalitiesService } from 'mavenge-localities';

@Injectable()
export class LocationService {
  constructor(private readonly localitiesService: LocalitiesService) {}

  async findCities(searchTerm: string) {
    return await this.localitiesService.searchLocalities({
      name: searchTerm,
      type: LocalityType.CITY,
      limit: 10
    });
  }
}

API Reference

LocalitiesService

searchLocalities(options: LocalitySearchOptions): Promise<LocalitySearchResult>

Search for localities based on various criteria.

Parameters:

• options.name - Search by locality name (partial match)
• options.country - Filter by country name
• options.countryCode - Filter by ISO country code (e.g., 'US', 'GB')
• options.type - Filter by locality type (city, town, village, etc.)
• options.region - Filter by region/state
• options.state - Filter by state/province
• options.limit - Maximum number of results (default: 100)
• options.offset - Pagination offset (default: 0)

Example:

const results = await localitiesService.searchLocalities({
  name: 'London',
  countryCode: 'GB',
  type: LocalityType.CITY,
  limit: 5
});

getLocalityById(id: string): Promise<Locality | null>

Get a specific locality by its unique ID.

const locality = await localitiesService.getLocalityById('us-ny-nyc');

getLocalitiesByCountryCode(countryCode: string): Promise<Locality[]>

Get all localities for a specific country.

const usLocalities = await localitiesService.getLocalitiesByCountryCode('US');

getLocalitiesInBoundingBox(minLat, maxLat, minLon, maxLon): Promise<Locality[]>

Find localities within a geographic bounding box.

const localities = await localitiesService.getLocalitiesInBoundingBox(
  40.0, 41.0, // Latitude range
  -75.0, -73.0 // Longitude range
);

getLocalitiesNearPoint(latitude, longitude, radiusKm): Promise<Locality[]>

Find localities within a specific radius of a point.

const nearbyLocalities = await localitiesService.getLocalitiesNearPoint(
  40.7128, -74.0060, // New York City coordinates
  50 // 50km radius
);

getAvailableCountryCodes(): string[]

Get all available country codes in the dataset.

const countryCodes = localitiesService.getAvailableCountryCodes();
// ['US', 'GB', 'FR', 'DE', ...]

getLocalitiesCountByType(): Record<LocalityType, number>

Get statistics on locality counts by type.

const stats = localitiesService.getLocalitiesCountByType();
// { city: 1500, town: 3200, village: 5600, ... }

Bounding Box Methods

getBoundingBoxForLocalities(localities: Locality[]): BoundingBox | null

Calculate the bounding box that encompasses a set of localities.

const localities = await localitiesService.getLocalitiesByCountryCode('US');
const boundingBox = localitiesService.getBoundingBoxForLocalities(localities);
// { minLat: 25.7617, maxLat: 71.5388, minLon: -179.1489, maxLon: 179.7789 }

getBoundingBoxForCountry(countryCode: string): Promise<BoundingBox | null>

Get the bounding box for all localities in a specific country.

const usBoundingBox = await localitiesService.getBoundingBoxForCountry('US');

getBoundingBoxForRegion(countryCode: string, region: string): Promise<BoundingBox | null>

Get the bounding box for localities in a specific region within a country.

const californiaBBox = await localitiesService.getBoundingBoxForRegion('US', 'California');

searchLocalitiesWithBoundingBox(options: LocalitySearchOptions): Promise<LocalitySearchResult>

Search for localities and include the bounding box of the results.

const result = await localitiesService.searchLocalitiesWithBoundingBox({
  type: LocalityType.CITY,
  countryCode: 'FR'
});
// result.boundingBox contains the bounding box for all French cities

getOverallBoundingBox(): BoundingBox | null

Get the overall bounding box that encompasses all localities in the dataset.

const overallBbox = localitiesService.getOverallBoundingBox();

expandBoundingBox(boundingBox: BoundingBox, marginDegrees: number): BoundingBox

Expand a bounding box by a specified margin in degrees.

const expandedBbox = localitiesService.expandBoundingBox(originalBbox, 1.0);
// Adds 1 degree margin on all sides

isPointInBoundingBox(latitude: number, longitude: number, boundingBox: BoundingBox): boolean

Check if a coordinate point falls within a bounding box.

const isInside = localitiesService.isPointInBoundingBox(51.5074, -0.1278, europeBbox);

getBoundingBoxArea(boundingBox: BoundingBox): number

Calculate the area of a bounding box in square degrees.

const area = localitiesService.getBoundingBoxArea(boundingBox);
// Returns area in square degrees

Types and Interfaces

Locality

interface Locality {
  id: string;
  name: string;
  country: string;
  countryCode: string;
  region?: string;
  state?: string;
  county?: string;
  municipality?: string;
  city?: string;
  latitude: number;
  longitude: number;
  population?: number;
  timezone?: string;
  elevation?: number;
  postcodes?: string[];
  type: LocalityType;
}

LocalityType

enum LocalityType {
  COUNTRY = 'country',
  STATE = 'state',
  REGION = 'region',
  COUNTY = 'county',
  MUNICIPALITY = 'municipality',
  CITY = 'city',
  TOWN = 'town',
  VILLAGE = 'village',
  HAMLET = 'hamlet',
  NEIGHBOURHOOD = 'neighbourhood',
  SUBURB = 'suburb'
}

LocalitySearchOptions

interface LocalitySearchOptions {
  name?: string;
  country?: string;
  countryCode?: string;
  type?: LocalityType;
  region?: string;
  state?: string;
  limit?: number;
  offset?: number;
}

LocalitySearchResult

interface LocalitySearchResult {
  localities: Locality[];
  total: number;
  limit: number;
  offset: number;
}

Examples

Find Major Cities

const majorCities = await localitiesService.searchLocalities({
  type: LocalityType.CITY,
  limit: 20
});

Search Cities in a Specific State

const californiaCities = await localitiesService.searchLocalities({
  state: 'California',
  countryCode: 'US',
  type: LocalityType.CITY
});

Find European Capitals

const europeanCapitals = await localitiesService.searchLocalities({
  name: 'capital',
  type: LocalityType.CITY
});

Geospatial Search

// Find localities near London
const nearLondon = await localitiesService.getLocalitiesNearPoint(
  51.5074, -0.1278, 100
);

// Find localities in the UK
const ukBoundingBox = await localitiesService.getLocalitiesInBoundingBox(
  49.9, 60.9, // Latitude range
  -8.2, 1.8   // Longitude range
);

Bounding Box Operations

// Get bounding box for a country
const usBoundingBox = await localitiesService.getBoundingBoxForCountry('US');
console.log(`US spans from ${usBoundingBox.minLat} to ${usBoundingBox.maxLat} latitude`);

// Search with bounding box included
const results = await localitiesService.searchLocalitiesWithBoundingBox({
  countryCode: 'FR',
  type: LocalityType.CITY
});
console.log(`French cities span ${results.boundingBox.minLat} to ${results.boundingBox.maxLat}`);

// Check if a point is within a region
const europeBbox = { minLat: 35, maxLat: 70, minLon: -10, maxLon: 40 };
const isInEurope = localitiesService.isPointInBoundingBox(48.8566, 2.3522, europeBbox);

// Expand a bounding box for buffer zones
const expandedBbox = localitiesService.expandBoundingBox(usBoundingBox, 2.0);

📊 Data Coverage & Statistics

Geographic Coverage

• 🌍 Global Reach: All 217 countries and territories worldwide
• 🌎 Continental Coverage: Complete coverage across all continents
• 📍 186,892 Total Localities: From major cities to small villages

Top Countries by Locality Count

| Rank | Country | Localities | Flag | |------|---------|------------|------| | 1 | China | 5,114 | 🇨🇳 | | 2 | United States | 4,211 | 🇺🇸 | | 3 | India | 2,587 | 🇮🇳 | | 4 | Russia | 2,368 | 🇷🇺 | | 5 | Brazil | 2,352 | 🇧🇷 | | 6 | Mexico | 2,172 | 🇲🇽 | | 7 | Canada | 2,130 | 🇨🇦 | | 8 | Germany | 2,101 | 🇩🇪 |

Data Quality

• ✅ Verified Coordinates: Accurate latitude/longitude for all entries
• 🏷️ Rich Metadata: Population, timezones, postal codes where available
• 🌐 Multilingual Support: Native language names and Unicode characters
• 📈 Regular Updates: Data sourced from Geoapify's open data initiative

Data Source

This library uses locality data sourced from Geoapify's open data initiative, providing comprehensive and up-to-date geographic information from all 217 countries worldwide.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

For issues and questions, please visit our GitHub repository.

🚀 Ready to explore the world's localities? Get started today!

Made with ❤️ for the NestJS community by Takudzwa Mabenge