CoordConversion

A robust TypeScript library for converting between different geographic coordinate formats: Decimal Degrees (DD), Degrees-Minutes (DM), and Degrees-Minutes-Seconds (DMS). Features comprehensive parsing, validation, and formatting with support for hemisphere indicators.

You can see a demo on CodePen.

Features

🔄 Bidirectional Conversions: DD ↔ DM ↔ DMS
🌍 Smart Parsing: Handles various input formats with automatic hemisphere detection
✅ Robust Validation: Range checking and format validation
🎯 Type Safety: Full TypeScript support with comprehensive type definitions
📐 Precision Control: Configurable decimal precision for output formatting
🤝 Pair Functions: Work with latitude/longitude pairs together
🎨 Rich Formatting: Multiple formatting options for all coordinate types
🧪 Well Tested: Comprehensive test suite with round-trip validation
📦 Zero Dependencies: Lightweight with no external dependencies
🚀 Modern Build: ES modules and CommonJS support

Installation

NPM Installation

npm install coordconversion

CDN Usage (Browser)

For quick browser usage without a build step, you can use CDN links:

Global Script (Easy):

<script src="https://unpkg.com/coordconversion@latest/dist/index.global.js"></script>
<script>
  const { parseToDD, CoordinateType } = CoordConversion;
  // Use the library functions directly
</script>

ES Modules:

<script type="module">
  import {
    parseToDD,
    CoordinateType,
  } from "https://unpkg.com/coordconversion@latest/dist/index.js";
  // Use the library functions
</script>

Alternative CDNs:

unpkg: https://unpkg.com/coordconversion@latest/dist/
jsDelivr: https://cdn.jsdelivr.net/npm/coordconversion@latest/dist/

API Reference

Core Type

enum CoordinateType {
  LAT = "lat", // Latitude
  LON = "lon", // Longitude
}

Available Functions

These are the available imports from the library.

import {
  // For individual coordinates
  parseToDD, // Parse values to Decimal Degrees (DD)
  ddToDM, // Convert DD to Degrees-Minutes (DM)
  ddToDMS, // Convert DD to Degrees-Minutes-Seconds (DMS)
  dmToDD, // Convert DM to DD
  dmsToDD, // Convert DMS to DD
  formatDD, // Format DD for display
  formatDM, // Format DM for display
  formatDMS, // Format DMS for display
  // For coordinate pairs
  parsePairToDD, // Parse a pair of values to Decimal Degrees (DD)
  ddPairToDM, // Convert a pair of DD values to Degrees-Minutes (DM)
  ddPairToDMS, // Convert a pair of DD values to Degrees-Minutes-Seconds (DMS)
  dmPairToDD, // Convert a pair of DM values to DD
  dmsPairToDD, // Convert a pair of DMS values to DD
  formatDDPair, // Format a pair of DD values for display
  formatDMPair, // Format a pair of DM values for display
  formatDMSPair, // Format a pair of DMS values for display
  // Coordinate type for type safety
  CoordinateType,
} from "coordconversion";

Quick Start

Single Coordinate Conversion

Functions follow a parse -> convert -> format flow.

Start by parsing a coordinate.

const dd = parseToDD("45° 7' 22.8\" N", CoordinateType.LAT);

Convert the result to another format.

const dm = ddToDM(dd);

Format the restult into a readable string.

const formatted = formatDM(dm);
console.log(formatted); // e.g. "45° 7.38000' N"

This can be accomplished in a single line.

const formatted = formatDM(
  ddToDM(parseToDD("45° 7' 22.8\" N", CoordinateType.LAT)),
);
console.log(formatted); // e.g. "45° 7.38000' N"

Coordinate Pairs

Parse a coordinate pair

const [lat, lon] = parsePairToDD("48.8544° N", "123.5005° W");

Convert the result to another format

const [latDM, lonDM] = ddPairToDM(lat, lon);

Format the result into a readable string

const [latStr, lonStr] = formatDMPair(latDM, lonDM);
console.log(latStr, lonStr); // e.g. "48° 51.26400' N", "123° 30.03000' W"

This can also be accomplished in a single line

const [latStr, lonStr] = formatDMPair(
  ...ddPairToDM(...parsePairToDD("48.8544° N", "123.5005° W")),
);
console.log(latStr, lonStr); // e.g. "48° 51.26' N", "123° 30.03' W"

Continue reading for detailed descriptions of functions including return data types/shapes and function options.

Parsing Functions

`parseToDD` - Smart Coordinate Parser

Takes any coordinate string or number and converts it to decimal degrees format. Automatically detects and handles different input formats including hemisphere indicators.

Supported formats:

Decimal degrees, eg "45.123"
Degrees-minutes, eg "45° 7.38'" or "45 7.38 N"
Degrees-minutes-seconds, eg "45° 7' 22.8\" N" or "45 7 22.8"

const dd = parseToDD("45° 7' 22.8\" N", CoordinateType.LAT);

// returns
//  {
//    kind: "lat",
//    degrees: 45.123
//  }

`parsePairToDD` - Parse Coordinate Pairs

What it does: Takes latitude and longitude inputs (strings or numbers) and converts both to decimal degrees format in one function call.

const [lat, lon] = parsePairToDD("48.8544° N", "123.5005° W");

// returns
//  [
//    {
//      kind: "lat",
//      degrees: 48.8544
//    },
//    {
//      kind: "lon",
//      degrees: -123.5005
//    }
//  ]

Conversion Functions (Single Coordinates)

`ddToDM` - Decimal Degrees to Degrees-Minutes

Converts decimal degrees to degrees and minutes format.
Includes options for precision control and range clamping.

const dm = ddToDM({ kind: "lat", degrees: 45.123 });

// returns
//  {
//    kind: "lat",
//    degrees: 45,
//    minutes: 7.38,
//    hemi: "N"
//  }

`ddToDMS` - Decimal Degrees to Degrees-Minutes-Seconds

What it does: Converts decimal degrees to degrees, minutes, and seconds format. Provides the highest precision breakdown of coordinates.

const dms = ddToDMS({ kind: "lat", degrees: 45.123 });

// returns
//  {
//    kind: "lat",
//    degrees: 45,
//    minutes: 7,
//    seconds: 22.80,
//    hemi: "N"
//  }

`dmToDD` - Degrees-Minutes to Decimal Degrees

What it does: Converts degrees-minutes format back to decimal degrees. Validates that minutes are within valid range (0-60).

const dd = dmToDD({ kind: "lat", degrees: 45, minutes: 7.38, hemi: "N" });
// returns
//  {
//    kind: "lat",
//    degrees: 45.123
//  }

`dmsToDD` - Degrees-Minutes-Seconds to Decimal Degrees

What it does: Converts degrees-minutes-seconds format back to decimal degrees. Validates that minutes and seconds are within valid ranges.

const dd = dmsToDD({
  kind: "lat",
  degrees: 45,
  minutes: 7,
  seconds: 22.8,
  hemi: "N",
});

// returns
//  {
//    kind: "lat",
//    degrees: 45.123
//  }

Conversion Functions (Coordinate Pairs)

`ddPairToDM` - Convert DD Pair to DM Pair

What it does: Converts both latitude and longitude from decimal degrees to degrees-minutes format in one function call.

const [latDM, lonDM] = ddPairToDM(latDD, lonDD);

// returns
//  [
//    {
//      kind: "lat",
//      degrees: 48,
//      minutes: 51.26,
//      hemi: "N"
//    },
//    {
//      kind: "lon",
//      degrees: 123,
//      minutes: 30.03,
//      hemi: "W"
//  }
//  ]

`ddPairToDMS` - Convert DD Pair to DMS Pair

What it does: Converts both latitude and longitude from decimal degrees to degrees-minutes-seconds format in one function call.

const [latDMS, lonDMS] = ddPairToDMS(latDD, lonDD);

// returns
//  [
//    {
//      kind: "lat",
//      degrees: 48,
//      minutes: 51,
//      seconds: 15.84,
//      hemi: "N"
//    },
//    {
//      kind: "lon",
//      degrees: 123,
//      minutes: 30,
//      seconds: 1.8,
//      hemi: "W"
//    }
//  ]

`dmPairToDD` - Convert DM Pair to DD Pair

What it does: Converts both latitude and longitude from degrees-minutes format back to decimal degrees in one function call.

const [latDD, lonDD] = dmPairToDD(latDM, lonDM);

// returns
//  [
//    {
//      kind: "lat",
//      degrees: 48.8544
//    },
//    {
//      kind: "lon",
//      degrees: -123.5005
//    }
//  ]

`dmsPairToDD` - Convert DMS Pair to DD Pair

What it does: Converts both latitude and longitude from degrees-minutes-seconds format back to decimal degrees in one function call.

const [latDD, lonDD] = dmsPairToDD(latDMS, lonDMS);

// returns
//  [
//    {
//      kind: "lat",
//      degrees: 48.8544
//    },
//    {
//      kind: "lon",
//      degrees: -123.5005
//    }
//  ]

Formatting Functions (Single Coordinates)

`formatDD` - Format Decimal Degrees for Display

What it does: Takes a decimal degrees object and formats it as a human-readable string with hemisphere indicator. Default precision is 5 decimal places.

const formatted = formatDD({ kind: "lat", degrees: 45.123 });

// returns "45.12300° N"

`formatDM` - Format Degrees-Minutes for Display

What it does: Takes a degrees-minutes object and formats it as a human-readable string with degree and minute symbols. Default precision is 2 decimal places for minutes.

const formatted = formatDM({
  kind: "lat",
  degrees: 45,
  minutes: 7.38,
  hemi: "N",
});

// returns "45° 7.38' N"

`formatDMS` - Format Degrees-Minutes-Seconds for Display

What it does: Takes a degrees-minutes-seconds object and formats it as a human-readable string with all symbols. Default precision is 2 decimal places for seconds.

const formatted = formatDMS({
  kind: "lat",
  degrees: 45,
  minutes: 7,
  seconds: 22.8,
  hemi: "N",
});

// returns "45° 7' 22.80\" N"

Formatting Functions (Coordinate Pairs)

`formatDDPair` - Format DD Pair for Display

What it does: Formats both latitude and longitude decimal degrees as human-readable strings in one function call.

const [latStr, lonStr] = formatDDPair(latDD, lonDD);

// returns
//  [
//    "48.85440° N",
//    "123.50050° W"
//  ]

`formatDMPair` - Format DM Pair for Display

What it does: Formats both latitude and longitude degrees-minutes as human-readable strings in one function call.

const [latStr, lonStr] = formatDMPair(latDM, lonDM);

// returns
//  [
//    "48° 51.26' N",
//    "123° 30.03' W"
//  ]

`formatDMSPair` - Format DMS Pair for Display

What it does: Formats both latitude and longitude degrees-minutes-seconds as human-readable strings in one function call.

const [latStr, lonStr] = formatDMSPair(latDMS, lonDMS);

// returns
//  [
//    "48° 51' 15.84\" N",
//    "123° 30' 1.80\" W"
//  ]

Function Options

Conversion Options

Most conversion functions accept an optional opts parameter:

decimals: Number of decimal places for the output (varies by function)
clamp: Whether to clamp degrees to valid ranges (default: false)

// Custom precision
const dm = ddToDM(dd, { decimals: 4 }); // 4 decimal places for minutes
const dms = ddToDMS(dd, { decimals: 3 }); // 3 decimal places for seconds

// Range clamping
const safeDM = ddToDM(dd, { clamp: true }); // Clamps to valid lat/lon ranges

Formatting Options

All formatting functions accept an optional decimals parameter:

const formatted = formatDD(dd, 3); // 3 decimal places instead of default 5
const formatted2 = formatDM(dm, 4); // 4 decimal places for minutes instead of default 5

Validation and Error Handling

The library includes comprehensive validation:

Range Validation: Latitude (-90° to +90°), Longitude (-180° to +180°)
Format Validation: Minutes (0-60), Seconds (0-60)
Input Validation: Finite number checking, format recognition
Error Messages: Descriptive error messages for debugging

Common Errors:

// Range errors
parseToDD("91", CoordinateType.LAT); // Error: LAT degrees out of range: 91

// Format errors
parseToDD("45° 65' N", CoordinateType.LAT); // Error: Minutes must be < 60

// Invalid input
parseToDD("invalid", CoordinateType.LAT); // Error: Unrecognized coordinate format

Advanced Usage

Custom Precision

// Parse and convert with custom precision
const dd = parseToDD("45.123456789", CoordinateType.LAT);

// High precision DM
const dm = ddToDM(dd, { decimals: 4 });
console.log(formatDM(dm)); // "45° 7.4074' N"

// High precision DMS
const dms = ddToDMS(dd, { decimals: 3 });
console.log(formatDMS(dms)); // "45° 7' 24.444\" N"

Clamping Values

// Parse invalid latitude (will throw error without clamp)
// const invalidLat = parseToDD("95", CoordinateType.LAT); // Error!

// Use clamp option to handle out-of-range values during conversion
const validDD = parseToDD("89.5", CoordinateType.LAT); // Valid input
const clampedDM = ddToDM(validDD, { clamp: true });
console.log(formatDM(clampedDM)); // "89° 30.00000' N"

Batch Processing

const coordinates = ["40.7128° N", "74.0060° W", "51.5074° N", "0.1278° W"];

const parsed = coordinates.map((coord, index) =>
  parseToDD(coord, index % 2 === 0 ? CoordinateType.LAT : CoordinateType.LON),
);

Working with Coordinate Pairs

// Parse coordinate pairs from various formats
const [lat1, lon1] = parsePairToDD("48.8544° N", "123.5005° W");
const [lat2, lon2] = parsePairToDD(48.8544, -123.5005);
const [lat3, lon3] = parsePairToDD("48° 51.26' N", "123° 30.03' W");

// Convert pairs to all formats
const [latDM, lonDM] = ddPairToDM(lat1, lon1);
const [latDMS, lonDMS] = ddPairToDMS(lat1, lon1);

// Format pairs for display
const [latDDStr, lonDDStr] = formatDDPair(lat1, lon1);
const [latDMStr, lonDMStr] = formatDMPair(latDM, lonDM);
const [latDMSStr, lonDMSStr] = formatDMSPair(latDMS, lonDMS);

console.log("DD:", latDDStr, lonDDStr); // "48.85440° N" "123.50050° W"
console.log("DM:", latDMStr, lonDMStr); // "48° 51.26' N" "123° 30.03' W"
console.log("DMS:", latDMSStr, lonDMSStr); // "48° 51' 15.84\" N" "123° 30' 1.80\" W"

Complete Workflow Example

// Complete workflow: Parse → Convert → Format
const [lat, lon] = parsePairToDD("48.8544° N", "123.5005° W");

// Convert to all formats
const [latDM, lonDM] = ddPairToDM(lat, lon);
const [latDMS, lonDMS] = ddPairToDMS(lat, lon);

// Format all formats
const [latDDStr, lonDDStr] = formatDDPair(lat, lon);
const [latDMStr, lonDMStr] = formatDMPair(latDM, lonDM);
const [latDMSStr, lonDMSStr] = formatDMSPair(latDMS, lonDMS);

// Round trip validation
const [latBack, lonBack] = dmPairToDD(latDM, lonDM);
const [latBack2, lonBack2] = dmsPairToDD(latDMS, lonDMS);

console.log("Original:", lat.degrees, lon.degrees);
console.log("From DM:", latBack.degrees, lonBack.degrees);
console.log("From DMS:", latBack2.degrees, lonBack2.degrees);

Usage in Different Environments

Node.js (ES Modules)

import { parseToDD, ddToDM, formatDM, CoordinateType } from "coordconversion";

const dd = parseToDD("45° 7' 22.8\" N", CoordinateType.LAT);
const dm = ddToDM(dd);
console.log(formatDM(dm)); // "45° 7.38000' N"

Node.js (CommonJS)

const {
  parseToDD,
  ddToDM,
  formatDM,
  CoordinateType,
} = require("coordconversion");

const dd = parseToDD("45° 7' 22.8\" N", CoordinateType.LAT);
const dm = ddToDM(dd);
console.log(formatDM(dm)); // "45° 7.38000' N"

Browser (ES Modules)

<script type="module">
  import {
    parseToDD,
    ddToDM,
    formatDM,
    CoordinateType,
  } from "https://unpkg.com/coordconversion@latest/dist/index.js";

  const dd = parseToDD("45° 7' 22.8\" N", CoordinateType.LAT);
  const dm = ddToDM(dd);
  console.log(formatDM(dm)); // "45° 7.38000' N"
</script>

Browser (Script Tag with Global)

<script src="https://unpkg.com/coordconversion@latest/dist/index.global.js"></script>
<script>
  const { parseToDD, ddToDM, formatDM, CoordinateType } = CoordConversion;

  const dd = parseToDD("45° 7' 22.8\" N", CoordinateType.LAT);
  const dm = ddToDM(dd);
  console.log(formatDM(dm)); // "45° 7.38000' N"
</script>

Browser (Dynamic Import)

<script>
  (async () => {
    const { parseToDD, ddToDM, formatDM, CoordinateType } =
      await import("https://unpkg.com/coordconversion@latest/dist/index.js");

    const dd = parseToDD("45° 7' 22.8\" N", CoordinateType.LAT);
    const dm = ddToDM(dd);
    console.log(formatDM(dm)); // "45° 7.38000' N"
  })();
</script>

Complete Vanilla JavaScript Example

<!DOCTYPE html>
<html>
  <head>
    <title>Coordinate Conversion Example</title>
  </head>
  <body>
    <h1>Coordinate Conversion Demo</h1>
    <div id="output"></div>

    <script src="https://unpkg.com/coordconversion@latest/dist/index.global.js"></script>
    <script>
      const {
        parseToDD,
        ddToDM,
        ddToDMS,
        formatDD,
        formatDM,
        formatDMS,
        CoordinateType,
      } = CoordConversion;

      // Parse a coordinate
      const dd = parseToDD("48° 51' 15.84\" N", CoordinateType.LAT);

      // Convert to different formats
      const dm = ddToDM(dd);
      const dms = ddToDMS(dd);

      // Format for display
      const ddStr = formatDD(dd);
      const dmStr = formatDM(dm);
      const dmsStr = formatDMS(dms);

      // Display results
      document.getElementById("output").innerHTML = `
            <p><strong>Original:</strong> 48° 51' 15.84" N</p>
            <p><strong>DD:</strong> ${ddStr}</p>
            <p><strong>DM:</strong> ${dmStr}</p>
            <p><strong>DMS:</strong> ${dmsStr}</p>
        `;
    </script>
  </body>
</html>

Coordinate Format Reference

Format	Description	Example
DD	Decimal Degrees	`45.123° N`
DM	Degrees-Minutes	`45° 7.38' N`
DMS	Degrees-Minutes-Seconds	`45° 7' 22.8" N`

Valid Ranges

Latitude: -90° to +90° (N/S)
Longitude: -180° to +180° (E/W)
Minutes: 0 to 60 (exclusive)
Seconds: 0 to 60 (exclusive)

Name	Name	Last commit message	Last commit date
Latest commit History 48 Commits 48 Commits
.github/workflows	.github/workflows
data	data
src	src
tests	tests
types	types
.gitignore	.gitignore
.npmignore	.npmignore
.release-please-manifest.json	.release-please-manifest.json
CHANGELOG.md	CHANGELOG.md
LICENSE	LICENSE
jest.config.cjs	jest.config.cjs
package-lock.json	package-lock.json
package.json	package.json
readme.md	readme.md
release-please-config.json	release-please-config.json
tsconfig.json	tsconfig.json

Search code, repositories, users, issues, pull requests...

Folders and files

Latest commit

History

Repository files navigation

CoordConversion

Features

Installation

NPM Installation

CDN Usage (Browser)

API Reference

Core Type

Available Functions

Quick Start

Single Coordinate Conversion

Coordinate Pairs

Parsing Functions

parseToDD - Smart Coordinate Parser

parsePairToDD - Parse Coordinate Pairs

Conversion Functions (Single Coordinates)

ddToDM - Decimal Degrees to Degrees-Minutes

ddToDMS - Decimal Degrees to Degrees-Minutes-Seconds

dmToDD - Degrees-Minutes to Decimal Degrees

dmsToDD - Degrees-Minutes-Seconds to Decimal Degrees

Conversion Functions (Coordinate Pairs)

ddPairToDM - Convert DD Pair to DM Pair

ddPairToDMS - Convert DD Pair to DMS Pair

dmPairToDD - Convert DM Pair to DD Pair

dmsPairToDD - Convert DMS Pair to DD Pair

Formatting Functions (Single Coordinates)

formatDD - Format Decimal Degrees for Display

formatDM - Format Degrees-Minutes for Display

formatDMS - Format Degrees-Minutes-Seconds for Display