Everybody appreciates the distance information between two locations in web mapping services like Google Maps, right? Do you have a similar use case within your application but want to avoid the implementation overhead of abstracting from an external API? google-distance by Edward Look helps you to do just that.
The module wraps the distance calculation functionality of the Google Distance Matrix API into an easy-to-use interface.
|
1
|
npm install google-distance |
Usage
Let’s say we want to calculate the distance between New York City and San Diego. google-distance is frugal and very intuitive to use in this regard. It asks only for two required properties: origin and destination.
The following basic usage example …
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
'use strict';var distance = require('google-distance');var options = { origin: 'New York City, USA', destination: 'San Diego, USA'};function onDistance (err, result) { if (err) { return console.error(err); } console.log(result);}distance.get(options, onDistance); |
will result in:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
{ index: null, distance: '4,447 km', distanceValue: 4447040, duration: '1 day 17 hours', durationValue: 146399, // in seconds origin: 'New York, NY, USA', destination: 'San Diego, CA, USA', mode: 'driving', units: 'metric', language: 'en', avoid: null, sensor: false} |
Calculating the distance between cities is cool, isn’t it? But you know what’s even cooler? Determining the distance between two tupels of latitude and longitude values.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
'use strict';var distance = require('google-distance');var options = { origin: '40.759011,-73.984472', destination: '37.810848,-122.267448'};function onDistance (err, result) { if (err) { return console.error(err); } console.log(result);}distance.get(options, onDistance); |
Fantastico! Beside the distance of the two points, you also see a reverse geocoded origin and destination. Woot!
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
{ index: null, distance: '4,447 km', distanceValue: 4447040, duration: '1 day 17 hours', durationValue: 146399, // in seconds origin: 'New York, NY, USA', destination: 'San Diego, CA, USA', mode: 'driving', units: 'metric', language: 'en', avoid: null, sensor: false} |
Fine tuning
If you’re crazy enough to cycle all the way down from Oakland to San Diego for instance and want to check how far it really is, you can measure this as well as switching to imperial units or add other additional parameters.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
'use strict';var distance = require('google-distance');var options = { origin: 'Oakland, USA', destination: 'San Diego, USA', mode: 'bicycling', units: 'imperial'};distance.get(options, onDistance (err, result) { // ...}); |
Checkout this runnable example to verify that cycling might be a good one-week trip. Whereas walking would be definitely a crazy idea. Do the math 🙂
API key
One last note: It is not necessary to configure an API key in order to use the google-distance module. But: To avoid exceeding Google’s quota it is highly recommended.
Follow these steps in order to obtain an API key. After that it is easy to inform the module about your key:
|
1
2
3
|
var distance = require('google-distance');distance.apiKey = 'YOUR_API_KEY'; |
You can find the usage examples in an own repository. Play with it and let me know what you think 🙂
