coordinate-format

CoordinateFormat

A simple and flexible TypeScript library to format decimal latitude/longitude coordinates into degrees/minutes/seconds (DMS) and other coordinate formats.

Install

npm install coordinate-format

Usage

import { CoordinateFormat } from "coordinate-format";

const formatter = new CoordinateFormat();
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149° 7.721′ E" "35° 16.920′ S"

API

Creating a Format Instance

const formatter = new CoordinateFormat(format, options);

Parameters:

• format (optional, default: "minutes"): A format string or alias
• options (optional):
  • precision: Number of decimal places (default: 3)
  • labels: Custom labels for degrees, minutes, seconds, and directions

Format Aliases

Alias	Output	Example
"seconds"	Full DMS with direction (default)	35° 16′ 55.200″ N 149° 7′ 43.262″ E
"minutes"	Degrees and decimal minutes with direction	35° 16.920′ N 149° 7.721′ E
"degrees"	Decimal degrees with direction	35.282° N 149.129° E

Format Tokens

You can create custom format strings using the following tokens:

Token	Output	Example
D	Integer degrees	35
DD	Integer degrees with symbol	35°
d	Decimal degrees	35.282
dd	Decimal degrees with symbol	35.282°
M	Integer minutes	16
MM	Integer minutes with symbol	16′
m	Decimal minutes	16.920
mm	Decimal minutes with symbol	16.920′
s	Decimal seconds	55.200
ss	Decimal seconds with symbol	55.200″
X	Direction (N/S for latitude, E/W for longitude)	N, S, E, W
-	Negative sign (for negative values)	-

Methods

format(longitude, latitude) or format([longitude, latitude])

Formats a coordinate pair and returns [longitudeString, latitudeString].

const formatter = new CoordinateFormat("minutes");

// Arguments form
const [lon, lat] = formatter.format(149.128684, -35.282);

// Array form
const [lon, lat] = formatter.format([149.128684, -35.282]);

longitude(value)

Formats a single longitude value.

const formatter = new CoordinateFormat("degrees");
console.log(formatter.longitude(149.128684)); // "149.129° E"

latitude(value)

Formats a single latitude value.

const formatter = new CoordinateFormat("degrees");
console.log(formatter.latitude(-35.282)); // "35.282° S"

parse(longitudeString, latitudeString)

Parses formatted coordinate strings back into decimal degree numbers. Returns [longitude, latitude] or null if parsing fails.

const formatter = new CoordinateFormat("minutes");
const coords = formatter.parse("149° 7.721′ E", "35° 16.920′ S");
// coords: [149.128683, -35.282]

The parse method supports all formats that can be generated by the format method:

// Parse DMS (seconds format)
formatter.parse("149° 7′ 43.262″ E", "35° 16′ 55.200″ S");

// Parse decimal degrees
formatter.parse("149.129° E", "35.282° S");

// Parse with negative signs
formatter.parse("-149 7 43.262", "-35 16 55.200");

Examples

Basic Usage

import { CoordinateFormat } from "coordinate-format";

const formatter = new CoordinateFormat();
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149° 7.721′ E" "35° 16.920′ S"

Custom Format String

const formatter = new CoordinateFormat("-D M s");
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149 7 43.262" "-35 16 55.200"

Custom Precision

const formatter = new CoordinateFormat("seconds", { precision: 0 });
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149° 7′ 43″ E" "35° 16′ 55″ S"

Custom Labels

const formatter = new CoordinateFormat("DD MM ss X", {
  labels: {
    latitude: ["Norte", "Sur"],
    longitude: ["Este", "Oeste"],
    degrees: "d",
    minutes: "m",
    seconds: "s",
  },
});
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149d 7m 43.262s Este" "35d 16m 55.200s Sur"

Parsing Coordinates

const formatter = new CoordinateFormat("minutes");

// Parse formatted strings back to decimal
const coords = formatter.parse("149° 7.721′ E", "35° 16.920′ S");
console.log(coords); // [149.128683, -35.282]

// Round-trip formatting and parsing
const [lonStr, latStr] = formatter.format(149.128684, -35.282);
const [lon, lat] = formatter.parse(lonStr, latStr)!;
console.log(lon, lat); // 149.128684, -35.282

License

This project is licensed under the MIT License. It is a fork of formatcoords by @nerik.