Skip to content

🛸 takes geolocations of different formats and outputs a standardized version

License

Notifications You must be signed in to change notification settings

blakek/standardize-geolocation

Repository files navigation

standardize-geolocation

takes geolocations of different formats and outputs a standardized version

There are several ways of representing geolocations:

  • latitude and longitude
  • latitude, longitude, and elevation
  • longitude vs. lon vs. long vs. lng
  • GeoJSON
  • ...and more

This module just takes in a geolocation and tries to parse it to a standardized format everyone can use and rely on: an object with keys of latitude, longitude, and elevation.

Install

Using Yarn:

$ yarn add standardize-geolocation

…or using [npm]:

$ npm i --save standardize-geolocation

Usage

import { standardizeGeolocation } from 'standardize-geolocation';

const location = standardizeGeolocation({
  lat: 12.3456,
  lng: -65.4321
});
//» { latitude: 12.3456, longitude: -65.4321, elevation: undefined }

const points = [
  { lat: 85.238749, lng: 12.923587, elevation: 982 },
  { lat: 85.238749, lng: 12.923587, elevation: 982 },
  { lat: 85.238749, lng: 12.923587, elevation: 982 },
  [85.238749, 12.923587, 982],
  { lat: 85.238749, lng: 12.923587 }
];

const locations = points.map(standardizeGeolocation);
// [
//   { elevation: 982, latitude: 85.238749, longitude: 12.923587 },
//   { elevation: 982, latitude: 85.238749, longitude: 12.923587 },
//   { elevation: 982, latitude: 85.238749, longitude: 12.923587 },
//   { elevation: 982, latitude: 85.238749, longitude: 12.923587 },
//   { elevation: undefined, latitude: 85.238749, longitude: 12.923587 }
// ]

API

standardizeGeolocation

function standardizeGeolocation(
  point: GeolocationInput
): StandardizedGeolocation;

Attempts to create an object in this format from any known format:

{
  elevation: number | undefined;
  latitude: number;
  longitude: number;
}

Here's a (non-exhaustive) list of formats this will standardize:

Arrays:

  • [latitude, longitude]
  • [latitude, longitude, elevation]

If an array is detected to be in a GeoJSON object, latitude and longitude will be reversed:

{ coordinates: [longitude, latitude]; }

Objects:

Latitude keys:

  • lat
  • latitude

Longitude keys:

  • lng
  • lon
  • long
  • longitude

Elevation keys:

  • alt
  • altitude
  • elev
  • elevation

Nested objects:

If the passed object has one of these properties at the top level, it will attempt to convert it to a geolocation:

  • geometry
  • location
  • position

Contributing

Node.js and Yarn are required to work with this project.

To install all dependencies, run:

yarn

Useful Commands

yarn build Builds the project to ./dist
yarn format Format the source following the Prettier styles
yarn test Run project tests
yarn test --watch Run project tests, watching for file changes

See Also

  • blakek/geo2zip - translates latitude / longitude geolocations to the nearest corresponding U.S. zip code
  • blakek/us-zips - a list of US ZIP codes and their geolocations

License

MIT