@conveyal/lonlat

lonlat

Lon/lat normalization cause...sigh.

No one has agreed on a standard way of representing lon/lat. This is a small normalization library. Use this to convert all outside input before processing internally and convert to an external format right when it's being output.

API

Table of Contents

• lonlat.types.input
• lonlat.types.InvalidCoordinateException
• conveyal/lonlat
  • fromCoordinates
  • fromLatlng
  • fromPoint
  • fromString
  • fromLatFirstString
  • isEqual
  • print
  • toCoordinates
  • toLeaflet
  • toPoint
  • toString
  • toLatFirstString
• lonlat.types.output

lonlat.types.input

(type)

An unknown type of input. Must be one of the following:

• array: An array with 2 elements. The first is longitude, the second is latitude.
• string: A string in the format longitude,latitude
• Object (x, y coordinates): An object with x and y properties. x represents longitude and y represents latitude.
• Object (lat, lon): An object with latitude and longitude properties. The properties can be named various things. For longitude any of the following are valid: lon, lng or longitude For latitude any of the following are valid: lat or latitude

Type: (Array | string | Object)

Parameters

• unknown

lonlat.types.InvalidCoordinateException

(exception type)

An error that is thrown upon providing invalid coordinates.

Type: Error

Parameters

• unknown

conveyal/lonlat

Parse an unknown type of input.

Parameters

• unknown lonlat.types.input

Examples

var lonlat = require('@conveyal/lonlat')

// Object with lon/lat-ish attributes
var position = lonlat({ lon: 12, lat: 34 })         // { lon: 12, lat: 34 }
position = lonlat({ lng: 12, lat: 34 })             // { lon: 12, lat: 34 }
position = lonlat({ longitude: 12, latitude: 34 })  // { lon: 12, lat: 34 }
position = lonlat({ lng: 12, latitude: 34 })        // { lon: 12, lat: 34 }

// coordinate array
position = lonlat([12, 34])   // { lon: 12, lat: 34 }

// string
position = lonlat('12,34')   // { lon: 12, lat: 34 }

// object with x and y attributes
position = lonlat({ x: 12, y: 34 })   // { lon: 12, lat: 34 }

// the following will throw errors
position = lonlat({ lon: 999, lat: 34 })   // Error: Invalid longitude value: 999
position = lonlat({ lon: 12, lat: 999 })   // Error: Invalid latitude value: 999
position = lonlat({})                      // Error: Invalid latitude value: undefined
position = lonlat(null)                    // Error: Value must not be null or undefined

• Throws lonlat.types.InvalidCoordinateException

Returns lonlat.types.output

fromCoordinates

aliases: fromGeoJSON

Tries to parse from an array of coordinates.

Parameters

• coordinates Array An array in the format: [longitude, latitude]

Examples

var lonlat = require('@conveyal/lonlat')

var position = lonlat.fromCoordinates([12, 34])   // { lon: 12, lat: 34 }
position = lonlat.fromGeoJSON([12, 34])           // { lon: 12, lat: 34 }

• Throws lonlat.types.InvalidCoordinateException

Returns lonlat.types.output

fromLatlng

aliases: fromLeaflet

Tries to parse from an object.

Parameters

• lonlat Object An object with a lon, lng or longitude attribute and a lat or latitude attribute

Examples

var lonlat = require('@conveyal/lonlat')

var position = lonlat.fromLatlng({ longitude: 12, latitude: 34 })   // { lon: 12, lat: 34 }
position = lonlat.fromLeaflet({ lng: 12, lat: 34 })                 // { lon: 12, lat: 34 }

• Throws lonlat.types.InvalidCoordinateException

Returns lonlat.types.output

fromPoint

Tries to parse from an object.

Parameters

• point Object An object with a x attribute representing longitude and a y attribute representing latitude

Examples

var lonlat = require('@conveyal/lonlat')

var position = lonlat.fromPoint({ x: 12, y: 34 })   // { lon: 12, lat: 34 }

• Throws lonlat.types.InvalidCoordinateException

Returns lonlat.types.output

fromString

aliases: fromLonFirstString

Tries to parse from a string where the longitude appears before the latitude.

Parameters

• str string A string in the format: longitude,latitude

Examples

var lonlat = require('@conveyal/lonlat')

var position = lonlat.fromString('12,34')          // { lon: 12, lat: 34 }
var position = lonlat.fromLonFirstString('12,34')  // { lon: 12, lat: 34 }

• Throws lonlat.types.InvalidCoordinateException

Returns lonlat.types.output

fromLatFirstString

Tries to parse from a string where the latitude appears before the longitude.

Parameters

• str string A string in the format: latitude,longitude

Examples

var lonlat = require('@conveyal/lonlat')

var position = lonlat.fromLatFirstString('12,34') // { lon: 34, lat: 12 }

• Throws lonlat.types.InvalidCoordinateException

Returns lonlat.types.output

isEqual

Determine if two inputs are equal to each other

Parameters

• lonlat1 input
• lonlat2 input
• epsilon number? The maximum acceptable deviation to be considered equal. (optional, default 0)

Examples

var lonlat = require('@conveyal/lonlat')

var isEqual = lonlat.isEqual('12,34', [12, 34])   // true

• Throws lonlat.types.InvalidCoordinateException

Returns boolean

print

Parameters

• input input
• fixed number? The number of decimal places to round to. (optional, default 5)

Examples

var lonlat = require('@conveyal/lonlat')

var pretty = lonlat.print('12.345678,34')   // '12.34568, 34.00000'

• Throws lonlat.types.InvalidCoordinateException

Returns string A string with in the format longitude,latitude rounded to the number of decimal places as specified by fixed

toCoordinates

aliases: toGeoJSON

Translates to a coordinate array.

Parameters

• input lonlat.types.input

Examples

var lonlat = require('@conveyal/lonlat')

var coords = lonlat.toCoordinates('12,34')   // [12, 34]

• Throws lonlat.types.InvalidCoordinateException

Returns Array An array in the format [longitude, latitude]

toLeaflet

Translates to Leaflet LatLng object. This function requires Leaflet to be installed as a global variable L in the window environment.

Parameters

• input lonlat.types.input

Examples

var lonlat = require('@conveyal/lonlat')

var position = lonlat.toLeaflet({ lat: 12, long: 34 })   // Leaflet LatLng object

• Throws lonlat.types.InvalidCoordinateException

Returns Object A Leaflet LatLng object

toPoint

Translates to point Object.

Parameters

• input lonlat.types.input

Examples

var lonlat = require('@conveyal/lonlat')

var point = lonlat.toPoint('12,34')   // { x: 12, y: 34 }

• Throws lonlat.types.InvalidCoordinateException

Returns Object An object with x and y attributes representing latitude and longitude respectively

toString

aliases: toLonFirstString

Translates to coordinate string where the longitude appears before latitude.

Parameters

• input lonlat.types.input

Examples

var lonlat = require('@conveyal/lonlat')

var str = lonlat.toString({ lat: 12, longitude: 34 })          // '34,12'
var str = lonlat.toLonFirstString({ lat: 12, longitude: 34 })  // '34,12'

• Throws lonlat.types.InvalidCoordinateException

Returns string A string in the format 'longitude,latitude'

toLatFirstString

Translates to coordinate string where the latitude appears before longitude.

Parameters

• input lonlat.types.input

Examples

var lonlat = require('@conveyal/lonlat')

var str = lonlat.toLatFirstString({ lat: 12, longitude: 34 })  // '12,34'

• Throws lonlat.types.InvalidCoordinateException

Returns string A string in the format 'longitude,latitude'

lonlat.types.output

(type)

Standardized lon/lat object.

Type: Object

Parameters

• unknown

Properties

• lat number
• lon number