MV Geo Data

Typed, framework-neutral geographic reference data for websites, portals, forms, and backend validation.

The package currently includes:

• 195 countries with ISO alpha-2/alpha-3 codes, dialing codes, regions, and English nationality labels
• 195 nationality records linked to ISO alpha-2 country codes
• 23 corrected Maldives administrative-atoll/city zones containing 1,073 islands, resorts, industrial locations, and city districts
• 981 source-attributed coordinate points with confidence, verification, match-method, and cross-check metadata
• 1,025 Dhivehi island/location names and localized metadata for 22 of 23 zones
• 20 location-linked land aerodromes with searchable ICAO/IATA codes and separate aerodrome reference-point coordinates
• TypeScript types, arrays, and constant-time lookup maps
• Generated JSON files for non-TypeScript consumers

Install

npm install @boolean.mv/geo-data

The package is also available directly from its GitHub repository.

TypeScript and JavaScript

import {
  COUNTRIES,
  COUNTRY_BY_ISO2,
  MV_ZONE_BY_CODE,
  NATIONALITIES,
  getLocations,
  searchLocations,
} from "@boolean.mv/geo-data";

const maldives = COUNTRY_BY_ISO2.MV;
const ariAtollLocations = MV_ZONE_BY_CODE.AA.locations;
const nationalityOptions = NATIONALITIES.map(({ countryCode, name }) => ({
  value: countryCode,
  label: name,
}));

const resorts = getLocations({ zone: "AA", use: "resort" });
const matches = searchLocations("dhangethi");
const dhivehiMatches = searchLocations("މާޅޮސް");
const confidence = matches[0]?.coordinates?.confidence;
const velana = searchLocations("VRMM")[0]?.aerodrome;
const airportPoint = velana?.arpCoordinates;

Smaller entry points are available when an application needs only one dataset:

import { COUNTRIES } from "@boolean.mv/geo-data/countries";
import { NATIONALITIES } from "@boolean.mv/geo-data/nationalities";
import { MV_ZONES } from "@boolean.mv/geo-data/maldives";

Maldives zones also have isolated entry points, so browser applications can load one zone without bundling all 1,073 locations:

import { MV_ZONE, MV_LOCATIONS } from "@boolean.mv/geo-data/maldives/zones/aa";
import ADH_ZONE from "@boolean.mv/geo-data/maldives/zones/adh";

Zone paths use the stable zone-ID suffix, such as aa, adh, addu-city, male-city, and fuvahmulah-city.

Review status can be loaded independently as well:

import { DATASET_METADATA } from "@boolean.mv/geo-data/metadata";

const nextCoordinatesReview = DATASET_METADATA.review.datasets.coordinates.nextReviewDue;

CommonJS

Every JavaScript entry point also supports require() on supported Node.js versions:

const { COUNTRY_BY_ISO2, queryLocations } = require("@boolean.mv/geo-data");
const { MV_LOCATIONS } = require("@boolean.mv/geo-data/maldives/zones/aa");

Advanced location queries

queryLocations combines the existing zone, use, kind, coordinate, and deprecation filters with fuzzy search, spatial filtering, distance ordering, and pagination:

import { queryLocations } from "@boolean.mv/geo-data/query";

const typoTolerant = queryLocations({
  search: "dangeti",
  fuzzy: true,
  minScore: 0.72,
  limit: 10,
});

const nearbyResorts = queryLocations({
  use: "resort",
  near: { latitude: 4.1755, longitude: 73.5093 },
  radiusKm: 50,
  offset: 0,
  limit: 25,
});

const visibleMapPoints = queryLocations({
  bounds: { south: 3.8, west: 72.8, north: 4.5, east: 73.8 },
  hasCoordinates: true,
  limit: 1000,
});

Results contain location, an optional fuzzy-match score, and an optional distanceKm. The response also includes total, offset, limit, and hasMore. Limits must be between 1 and 1,000. Spatial queries exclude records without coordinates.

JSON

The build emits framework-neutral files at:

• "@boolean.mv/geo-data/data/countries.json"
• "@boolean.mv/geo-data/data/nationalities.json"
• "@boolean.mv/geo-data/data/maldives.json"
• "@boolean.mv/geo-data/data/maldives-locations.json"
• "@boolean.mv/geo-data/data/maldives.geojson"
• "@boolean.mv/geo-data/data/coordinate-coverage.json"
• "@boolean.mv/geo-data/data/dhivehi-coverage.json"
• "@boolean.mv/geo-data/data/metadata.json"

CSV equivalents are emitted for countries, nationalities, and flattened Maldives locations.

These files can be consumed by Node.js, copied into another stack, or served as static assets. They are generated from canonical source snapshots so the formats cannot drift independently.

Coordinates expose confidence, verificationStatus, verificationSourceIds, matchMethod, and an optional crossCheckDistanceKm. A conflicting status is published rather than hidden when independently matched sources differ by more than one kilometre. Dhivehi names use the optional nameDv field; zone records may include codeDv and officialNameDv.

Locations with a land airport expose an optional aerodrome object containing the official facility name, operator where published, aerodrome code, ICAO/IATA identifiers, source metadata, and an optional arpCoordinates point. The aerodrome reference point is deliberately separate from the island-level coordinates field.

Accuracy and scope

This is reference data, not an official government service. Names, classifications, resort branding, and administrative arrangements can change. Applications should pin a package version, and corrections should include a source in the pull request.

See data provenance for ownership, redistribution terms, and contribution guidance. The data maintenance policy defines quarterly reviews, stable-ID rename handling, and deprecation behavior. Deprecation and replacement metadata is preserved in typed objects, JSON, CSV, and GeoJSON outputs. The API stability policy defines compatibility guarantees from version 0.3.0 and the gates for reaching 1.0.

Development

Requires Node.js 22 or newer.

npm install
npm test

"npm test" compiles the package, generates the JSON distributions, and checks record counts, keys, lookups, and allowed location statuses.

License

Software and documentation use the MIT License. Boolean-owned datasets use CC BY 4.0. OneMap-derived fields retain the attribution and reuse terms stated in the OneMap Data Usage License.