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

``bash
npm install mavenge-localities
`

Quick Start

$3

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

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

$3

`typescript
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

$3

#### searchLocalities(options: LocalitySearchOptions): Promise

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:
`typescript
const results = await localitiesService.searchLocalities({
name: 'London',
countryCode: 'GB',
type: LocalityType.CITY,
limit: 5
});
`

#### getLocalityById(id: string): Promise

Get a specific locality by its unique ID.

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

#### getLocalitiesByCountryCode(countryCode: string): Promise

Get all localities for a specific country.

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

#### getLocalitiesInBoundingBox(minLat, maxLat, minLon, maxLon): Promise

Find localities within a geographic bounding box.

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

#### getLocalitiesNearPoint(latitude, longitude, radiusKm): Promise

Find localities within a specific radius of a point.

`typescript
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.

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

#### getLocalitiesCountByType(): Record

Get statistics on locality counts by type.

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

$3

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

Calculate the bounding box that encompasses a set of localities.

`typescript
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

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

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

#### getBoundingBoxForRegion(countryCode: string, region: string): Promise

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

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

#### searchLocalitiesWithBoundingBox(options: LocalitySearchOptions): Promise

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

`typescript
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.

`typescript
const overallBbox = localitiesService.getOverallBoundingBox();
`

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

Expand a bounding box by a specified margin in degrees.

`typescript
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.

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

#### getBoundingBoxArea(boundingBox: BoundingBox): number

Calculate the area of a bounding box in square degrees.

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

Types and Interfaces

$3

`typescript
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;
}
`

$3

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

$3

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

$3

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

Examples

$3

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

$3

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

$3

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

$3

`typescript
// 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
);
`

$3

`typescript
// 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

$3

- 🌍 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

$3

| 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 | 🇩🇪 |

$3

- ✅ 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