@accelint/geo

Geographic coordinate parsing, conversion, and formatting for multiple coordinate systems.

Features

• 5 Coordinate Systems: Parse and format coordinates in multiple notation systems

  • Decimal Degrees (DD): 40.7128° N / 74.0060° W
  • Degrees Decimal Minutes (DDM): 40° 42.768' N / 74° 0.36' W
  • Degrees Minutes Seconds (DMS): 40° 42' 46.08" N / 74° 0' 21.6" W
  • Military Grid Reference System (MGRS): 18T WL 80000 00000
  • Universal Transverse Mercator (UTM): 18N 585628 4511644

• Flexible Format Ordering: Convert between LATLON and LONLAT formats

• Input Validation: Detailed error messages for invalid coordinates

• Performance Optimized: Immutable coordinate objects with intelligent caching

• Type Safe: Full TypeScript support with complete type definitions

Installation

npm install @accelint/geo

Quick Start

import { createCoordinate, coordinateSystems } from '@accelint/geo';

// Create a coordinate parser for Decimal Degrees
const create = createCoordinate(coordinateSystems.dd, 'LATLON');
const coord = create('40.7128 / -74.0060');

// Or use numeric input
const coord2 = create([40.7128, -74.0060]);

// Access different formats
coord.dd();    // '40.7128 N / 74.006 W'
coord.ddm();   // '40 42.768 N / 74 0.36 W'
coord.dms();   // '40 42 46.08 N / 74 0 21.6 W'
coord.mgrs();  // '18T WL 80000 00000'
coord.utm();   // '18N 585628 4511644'

// Change format order
coord.dms('LONLAT'); // '74 0 21.6 W / 40 42 46.08 N'

Usage Examples

Parsing Different Coordinate Systems

import { createCoordinate, coordinateSystems } from '@accelint/geo';

// Parse Decimal Degrees
const parseDD = createCoordinate(coordinateSystems.dd);
const coordDD = parseDD('40.7128 / -74.0060');

// Parse Degrees Minutes Seconds
const parseDMS = createCoordinate(coordinateSystems.dms);
const coordDMS = parseDMS('40° 42\' 46.08" N / 74° 0\' 21.6" W');

// Parse UTM coordinates
const parseUTM = createCoordinate(coordinateSystems.utm);
const coordUTM = parseUTM('18N 585628 4511644');

// Parse MGRS coordinates
const parseMGRS = createCoordinate(coordinateSystems.mgrs);
const coordMGRS = parseMGRS('18T WL 80000 00000');

Numeric Input

import { createCoordinate, coordinateSystems } from '@accelint/geo';
import type { LatLonTuple, LonLatTuple } from '@accelint/geo';

// Using typed tuple input (order follows format parameter)
const create = createCoordinate(coordinateSystems.dd, 'LATLON');
const latlon: LatLonTuple = [40.7128, -74.0060];
const coordTuple = create(latlon);

// LONLAT order (GeoJSON convention)
const createLonLat = createCoordinate(coordinateSystems.dd, 'LONLAT');
const lonlat: LonLatTuple = [-74.0060, 40.7128];
const coordLonLat = createLonLat(lonlat);

// Using object input
const coordObj = create({ lat: 40.7128, lon: -74.0060 });

// Object aliases also work
const coordAlt = create({ latitude: 40.7128, longitude: -74.0060 });

Converting Between Formats

const create = createCoordinate(coordinateSystems.dd, 'LATLON');
const coord = create('40.7128 / -74.0060');

// Convert to different coordinate systems
coord.dd();    // '40.7128 N / 74.006 W'
coord.ddm();   // '40 42.768 N / 74 0.36 W'
coord.dms();   // '40 42 46.08 N / 74 0 21.6 W'
coord.mgrs();  // '18T WL 80000 00000'
coord.utm();   // '18N 585628 4511644'

// Change coordinate order (LATLON to LONLAT)
coord.dd('LONLAT');  // '74.006 W / 40.7128 N'
coord.dms('LONLAT'); // '74 0 21.6 W / 40 42 46.08 N'

Error Handling

const create = createCoordinate(coordinateSystems.dd);
const coord = create('invalid input');

if (!coord.valid) {
  console.log(coord.errors);
  // ['[ERROR] No input.']
}

// Access raw coordinate values
if (coord.valid) {
  console.log(coord.raw.LAT); // 40.7128
  console.log(coord.raw.LON); // -74.0060
}

API Reference

createCoordinate(system?, format?)

Creates a coordinate parser function.

Parameters:

• system (CoordinateSystem, optional): Coordinate system to use for parsing. Defaults to coordinateSystems.dd
• format (Format, optional): Coordinate order format ('LATLON' or 'LONLAT'). Defaults to 'LATLON'

Returns: Function that accepts a coordinate input and returns a Coordinate object

Input types:

• String: Coordinate string in the specified system's format (e.g., '40.7128 / -74.0060')
• Tuple: LatLonTuple or LonLatTuple — a readonly [number, number] with named elements, where order follows the format parameter (e.g., [40.7128, -74.0060] for LATLON)
• Object: Object with lat/lon properties. Accepts case-insensitive keys:
  • lat / lon
  • latitude / longitude

Example:

const create = createCoordinate(coordinateSystems.dd, 'LATLON');
const coord = create('40.7128 / -74.0060');

coordinateSystems

Object containing available coordinate system implementations.

Properties:

• dd - Decimal Degrees system
• ddm - Degrees Decimal Minutes system
• dms - Degrees Minutes Seconds system
• mgrs - Military Grid Reference System
• utm - Universal Transverse Mercator system

Coordinate Object

The object returned by calling the function from createCoordinate().

Properties:

• valid (boolean): Whether the coordinate was successfully parsed
• errors (string[]): Array of error messages (empty if valid)
• raw (object): Raw coordinate values with LAT and LON properties

Methods:

• dd(format?): Format as Decimal Degrees
• ddm(format?): Format as Degrees Decimal Minutes
• dms(format?): Format as Degrees Minutes Seconds
• mgrs(format?): Format as MGRS
• utm(format?): Format as UTM

Each method accepts an optional format parameter ('LATLON' or 'LONLAT') to override the default format order.

TypeScript Types

The package exports named tuple types for type-safe coordinate handling:

• LatLonTuple — readonly [latitude: number, longitude: number] — tuple in lat/lon order
• LonLatTuple — readonly [longitude: number, latitude: number] — tuple in lon/lat order (GeoJSON convention)
• CoordinateTuple — LatLonTuple | LonLatTuple — union of both orderings
• CoordinateObject — Record<string, number> — object with string keys (e.g., { lat, lon })
• CoordinateInput — string | CoordinateTuple | CoordinateObject — all accepted input types

Named tuple elements provide IDE hints for element order, preventing lat/lon mix-ups:

import type { LatLonTuple, LonLatTuple } from '@accelint/geo';

const latlon: LatLonTuple = [40.7128, -74.0060]; // [latitude, longitude]
const lonlat: LonLatTuple = [-74.0060, 40.7128]; // [longitude, latitude]

Coordinate System Formats

Decimal Degrees (DD)

• Format: ±DD.DDDD°
• Example: 40.7128° N / 74.0060° W

Degrees Decimal Minutes (DDM)

• Format: ±DD° MM.MMMM'
• Example: 40° 42.768' N / 74° 0.36' W

Degrees Minutes Seconds (DMS)

• Format: ±DD° MM' SS.SSSS"
• Example: 40° 42' 46.08" N / 74° 0' 21.6" W

Military Grid Reference System (MGRS)

• Format: ZZ[A-Z] [A-Z][A-Z] EEEEE NNNNN
• Example: 18T WL 80000 00000

Universal Transverse Mercator (UTM)

• Format: ZZ[N|S] EEEEEE NNNNNNN
• Example: 18N 585628 4511644

License

Apache-2.0

Copyright 2024-2026 Hypergiant Galactic Systems Inc.