reservemedia / geo-tools

fork from tims geo-tools repo

#geo-tools

A simple library used to geocode an address, reverse geocode coordinates, and calculate the distance between two locations. The default distance used is KM. Unit conversion methods are provided and can be seen below. The Google Maps API service is used for geocoding and reverse geocoding.

Installation

npm install geo-tools

Require

At the top of your app:

var geoTools = require('geo-tools');

Methods

Latitude and longitude shoud be inputted as lat/lng and will be returned as lat/lng.

geocode(address, callback, options)

Returns the latitude and longitude of a given address.

geocode('717 California Street, San Francisco, CA', function(coordinates){
  console.log(coordinates)
})

//Displays to the console:

{ lat: 37.79221, lng: -122.406141 }

Options(not required):

{key: 'YOUR_GOOGLE_API_KEY'}

reverseGeocode(object[lat], [lng], callback)

Takes 2 or 3 arguments. It can accept either an object with the lat/lng (ex. reverseGeocode({lat: 51.515400, lng: 7.455185}, callback)) or two numbers and the callback (ex. reverseGeocode(51.515400, 7.455185, callback)). If you use the latter format, order matters. Latitude must go first and longitude second.

reverseGeocode({lat: 37.79221, lng: -122.406141}, function(address){
	console.log(address)
})

//Displays to the console:

{ full_address: '717 California Street, San Francisco, CA 94108, USA',
  street_number: '717',
  street: 'California Street',
  neighborhood: 'Chinatown',
  city: 'San Francisco',
  county: 'San Francisco County',
  state: 'California',
  country: 'United States',
  postal_code: '94108' }

distance(object1, object2[lat1], [lng1], [lat2], [lng2])

Calculates the distance between two sets of coordinates. Returns the distance in Km. Accepts either 2 object arguments (ex. distance({lat: 37.79221, lng: -122.406141}, {lat: 37.774514, lng: -122.418079})), or 4 number arguments (ex. distance(37.79221, -122.406141, 37.774514, -122.418079)). If you choose the latter method, order matters and should be as follows: distance(lat1, lng1, lat2, lng2). Passing in objects is reccomended.

distance({lat: 37.79221, lng: -122.406141}, {lat: 37.774514, lng: -122.418079})

//Returns:

2.2299158844532245

toMiles(distance)

Converts Km into miles. The argument passed must be in Km which is the default unit used in geo-tools.

var length = distance({lat: 37.79221, lng: -122.406141}, {lat: 37.774514, lng: -122.418079});

toMiles(length) //Returns

1.3856050630385846

toMeters(distance)

Converts Km into meters. The argument passed must be in Km which is the default unit used in geo-tools.

toYards(distance)

Converts Km into yards. The argument passed must be in Km which is the default unit used in geo-tools.

toFeet(distance)

Converts Km into feet. The argument passed must be in Km which is the default unit used in geo-tools.

Tests

To run tests, type mocha into your terminal

mocha

Notes

• Sexagesimal format is not supported
• Google Maps API will allow for up to 2500 API calls in 24 hours. For additional calls, a business API key is required.

Sources

• To calculate distance, the Haversine formula is used. The formula comes from the following source:
• http://www.movable-type.co.uk/scripts/latlong.html

Any and all feedback/suggestions is appreciated and should be sent to: [email protected]

Enjoy!