Maptoolz is a WGS84 map utility library. Its core functionality is to convert between DMS, DEC and DDM coordinate formats. Given a group of coordinates it can calculate distance, order by distance, and find the center point.

npm install maptoolz --save

const maptoolz = require('maptoolz');

import {toDEC, toDMS, toDDM, getDistance, orderByDistance, getCenterPoint } from 'maptoolz';

All functions can be accessed via window.MapToolz

<script src="/dist/maptoolz.js"></script>
<script>
  window.Maptoolz.toDEC([`S43°38'19.39`, `W116°14'28.86"`])
</script>

OR

<script src="https://unpkg.com/maptoolz/dist/maptoolz.js"></script>

Accepted Input

• Whitespace is acceptable in Latitude and Longitude
• Negative values for Latitude are assumed to be S
• Negative values for Longitude are assumed to be W
• Single digits in number format are acceptable
• degree, minutes, and seconds signs may be included or ommitted

Degrees Minutes Seconds (DMS)

Latitude	Longitude
Ndd°mm'ss.ss"	Wddd°mm's.ss"
dd mm ' ss " S	dd mm ' s W
-d mm ss	-d

Decimal Degrees (DEC)

Latitude	Longitude
-dd.ddddd	ddd.ddddd
-d	d

Degrees Decimal Minutes (DDM)

Latitude	Longitude
dd°mm.mmmm'	Wddd°mm.mmmm'
dd mm.mmmm S	dd mm
-d mm.mmmm	-d

Accepts an array of strings or numbers as per the accepted format. Returns an object with the converted latitude and longitude pair(s).

Even length array of lat and long pairs

• lat – latitude in Accepted format, either string or number
• long – longitude in Accepted format, either string or number
• precision - toDEC only - Optional number of decimal places, default is 5

[{ "lat": "latitude", "long": "longitude" }]

• Latitude is of type string
• Longitude is of type string

const pointA = toDEC([`S43°38'19.39`, `W116°14'28.86"`])
// [{ lat: -43.63872, long: -116.24135 }]
const pointB = toDMS([-43.63872, -116.24135])
// [{ lat: S43°38'19.39", long: W116°14'28.86" }]
const pointC = toDDM([`32° 18.385' N`, `122° 36.875' W`])
// [{ lat: N32°18.385', long: W122°36.875' }]

Uses the Harvesine Formula to calculate the distance between two pairs of coordinates. The spherical radius is calculated using the average latitude between the two points. The distance between points [A, B, C, D] is the sum of: (A + B) + (B + C) + (C + D). The unit of measurement is optional with the default as km. The precision is also option with the default as 2 decimal places. Precision must be used in combination with the format argument.

Array of at least 2 pairs of coordinates in object form

• points - Array of {"lat": lat, "long": long} pairs

• format - unit of measurement for output, default is 'km'

  Symbol	Unit of Measurement
  m	Meters
  km	Kilometers
  nm	Nautical miles
  mi	Miles

• precision - number of decimal places, default is 2. Must be used in combination with format.

{"distance": distance, "format": format }

• distance is of type number
• format is of type string

const points = toDEC([
    `N53°27'-18.85"`, `W113°32'-23.09"`,
    `N53°30'-14.91"`, `W113°23'-8.08"`,
    `N53°30'22.8"`, `W113°13'-28.44"`,
    `N53°35'-15.29"`, `W113°11'-8.45"`,
    `N53°35'1.61"`, `W112°60'-5.29"`,
    ]);
const distanceKM = getDistance(points);
// { distance: 42.96, format: "km" }
const distanceNM = getDistance(points, 'nm', 4);
// { distance: 23.1982, format: "nm" }

Accepts an origin point of {"lat": lat, "long": long} type and an array of {"lat": lat, "long": long} objects. Returns an array of objects ordered from nearest to farthest. Iterates over the array and uses the getDistance() function under the hood.

An origin point and array of coordinate pairs

• origin – {"lat": lat, "long": long} pair in DEC format

• points – Array of {"lat": lat, "long": long} pairs in DEC format

• format - unit of measurement for output, default is 'km'

  Symbol	Unit of Measurement
  m	Meters
  km	Kilometers
  nm	Nautical miles
  mi	Miles

{from: { "lat": lat, "long": long }, to: { "lat": lat, "long": long }, "distance": distance, "format": format }

• from is a { "lat": lat, "long": long } object
• to is a { "lat": lat, "long": long } object
• distance is of type number
• format is of type string

const points = orderByDistance(
  {lat: 56.495000228117775, long:-88.26338679703304}, 
  toDEC([
      61.46659628870247, -93.86230787510061,
      63.32600658563838, -85.55269557039314,
      60.26988668328659, -77.2462962114008,
      55.46098932075369, -77.3115710914306,     
    ])
/* [
      {
        from: { lat: 56.495000228117775, long: -88.26338679703304},
        to: { lat: '61.46660', long: '-93.86231' },
        distance: 637.8,
        format: 'km'
      },
      {
        from: { lat: 56.495000228117775, long: -88.26338679703304},
        to: { lat: '55.46099', long: '-77.31157' },
        distance: 689.41,
        format: 'km'
      },
      {
        from: { lat: 56.495000228117775, long: -88.26338679703304},
        to: { lat: '60.26989', long: '-77.24630' },
        distance: 764.76,
        format: 'km'
},
      {
        from: { lat: 56.495000228117775, long: -88.26338679703304},
        to: { lat: '63.32601', long: '-85.55270' },
        distance: 773.21,
        format: 'km'
      },
    ]
*/

Accepts an array of {"lat": lat, "long": long} objects. Iterates over the array, converting the pairs of Geodetic coordinates into their respective Cartesian coordinates. The height is assumed to be 0. Sums and averages to find the center point.

Array of pairs of coordinates in object form

• points - Array of {"lat": lat, "long": long} pairs

{"lat": lat, "long": long }

• Latitude is of type string in DEC format
• Longitude is of type string in DEC format

const center = getCenterPoint(
       toDEC([
          -21.0781885,
          130.2679653,
          -22.0304073,
          133.3797261,
          -20.1017191,
          133.3017134,
          -20.1017192,
          133.3017126,
        ])
// { lat: "-20.83315", long: "132.56395" }

Errors can be handled with a try-catch block.

try {
  const distanceKM = getDistance({lat: -43.63872, long: -116.24135});
} catch (e) {
  console.log(e.message)
}
// "At least 2 points are needed to calculate the distance"