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.output
  • Properties
• lonlat.types.point
  • Properties
• lonlat.types.InvalidCoordinateException
• conveyal/lonlat
  • Parameters
  • Examples
  • fromCoordinates
    • Parameters
    • Examples
  • fromLatlng
    • Parameters
    • Examples
  • fromPoint
    • Parameters
    • Examples
  • fromString
    • Parameters
    • Examples
  • fromLatFirstString
    • Parameters
    • Examples
  • isEqual
    • Parameters
    • Examples
  • print
    • Parameters
    • Examples
  • toCoordinates
    • Parameters
    • Examples
  • toLeaflet
    • Parameters
    • Examples
  • toPoint
    • Parameters
    • Examples
  • toString
    • Parameters
    • Examples
  • toLatFirstString
    • Parameters
    • Examples
  • toPixel
    • Parameters
    • Examples
  • fromPixel
    • Parameters
    • Examples
• PIXELS_PER_TILE
• PIXELS_PER_TILE
• longitudeToPixel
  • Parameters
  • Examples
• latitudeToPixel
  • Parameters
  • Examples
• MAX_LAT
• pixelToLongitude
  • Parameters
  • Examples
• pixelToLatitude
  • Parameters
  • Examples

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)

lonlat.types.output

(type)

Standardized lon/lat object.

Type: Object

Properties

• lat number
• lon number

lonlat.types.point

(type)

Object with x/y number values.

Type: Object

Properties

• x number
• y number

lonlat.types.InvalidCoordinateException

(exception type)

An error that is thrown upon providing invalid coordinates.

Type: Error

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 lonlat.types.input
• lonlat2 lonlat.types.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 lonlat.types.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'

toPixel

Convert a coordinate to a pixel.

Parameters

• input lonlat.types.input
• zoom number

Examples

var pixel = lonlat.toPixel({lon: -70, lat: 40}, 9) //= {x: 40049.77777777778, y:49621.12736343896}

• Throws lonlat.types.InvalidCoordinateException
• Throws Error If latitude is above or below MAX_LAT
• Throws Error If zoom is undefined.

Returns Object An object with x and y attributes representing pixel coordinates

fromPixel

From pixel.

Parameters

• pixel lonlat.types.point
• zoom Number

Examples

var ll = lonlat.fromPixel({x: 40000, y: 50000}, 9) //= {lon: -70.13671875, lat: 39.1982053488948}

Returns lonlat.types.output

PIXELS_PER_TILE

Pixel conversions and constants taken from https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Implementations

PIXELS_PER_TILE

Pixels per tile.

longitudeToPixel

Convert a longitude to it's pixel value given a zoom level.

Parameters

• longitude number
• zoom number

Examples

var xPixel = lonlat.longitudeToPixel(-70, 9) //= 40049.77777777778

Returns number pixel

latitudeToPixel

Convert a latitude to it's pixel value given a zoom level.

Parameters

• latitude number
• zoom number

Examples

var yPixel = lonlat.latitudeToPixel(40, 9) //= 49621.12736343896

Returns number pixel

MAX_LAT

Maximum Latitude for valid Mercator projection conversion.

pixelToLongitude

Convert a pixel to it's longitude value given a zoom level.

Parameters

• x number
• zoom number

Examples

var lon = lonlat.pixelToLongitude(40000, 9) //= -70.13671875

Returns number longitude

pixelToLatitude

Convert a pixel to it's latitude value given a zoom level.

Parameters

• y number
• zoom number

Examples

var lat = lonlat.pixelToLatitude(50000, 9) //= 39.1982053488948

Returns number latitude