Added extra examples to readme documentation

Author: swiftcomplete-public

README.md

@@ -1,4 +1,4 @@
-# reverse-geocode
+# Swiftcomplete Reverse Geocoding
 ## Description
 This package provides reverse geocoding using the **[Swiftcomplete Places API](https://www.swiftcomplete.com/places/address-autocomplete/)**.
 
@@ -21,22 +21,97 @@ const swiftcompleteReverseGeocoder = require('@swiftcomplete/reverse-geocode');
 
 swiftcompleteReverseGeocoder.setAPIKey('INSERT-KEY-HERE');
 
-swiftcompleteReverseGeocoder.reverseGeocode('52.955771,-1.142881').then(function(results) {
+swiftcompleteReverseGeocoder.reverseGeocode('51.499403,-0.127362').then(function(results) {
+    console.log(results);
+});
+```
+
+## Response
+```json
+[
+  {
+    "primary":{
+      "text":"Westminster Abbey",
+      "highlights":[]
+    },
+    "secondary":{
+      "text":"London",
+      "highlights":[]
+    },
+    "type":"address.residential.building.data.emptyroad",
+    "isContainer":false,
+    "geometry":{
+      "centre":{
+        "lat":51.499462,
+        "lon":-0.127448,
+        "type":"address"
+      }
+    },
+    "distance":{
+      "units":"m",
+      "measurement":9,
+      "type":"biasTowards",
+      "geometry":{
+        "centre":{
+          "lat":51.499403,
+          "lon":-0.127362
+        }
+      }
+    },
+    "populatedRecord":{
+      "lines":[
+        "Westminster Abbey",
+        "",
+        "London",
+        "SW1P 3PA",
+        "United Kingdom"
+      ],
+      "label":"Westminster Abbey\nLondon\nSW1P 3PA\nUnited Kingdom"
+    }
+  }
+]
+```
+
+## Response field descriptions
+
+- primary.text - A simple description of the address, usually the building & street
+- secondary.text - A simple description of the location, usually the city
+- geometry.centre - The coordinates of the address
+- geometry.centre.type - The accuracy of the coordinates, either "address", "street" or "postcode"
+- distance - How far the address is from your coordinates
+- distance.geometry.centre - Your original coordinates
+- populatedRecord.lines - The fully formatted postal address, line by line
+- populatedRecord.label - The fully formatted postal address, in a simple label format
+
+## Customising the response
+
+It's possible to pass in an optional options object to customise the response. Each field is optional within the object:
+
+- maxResults - Max number of results to return (up to 5, default: 1). Note that you are billed per result, so 4 results = 4 charges.
+- distanceUnits - Unit of measurement to display how far away the address is from your coordinate ("metric", "imperial", "m", "km", "ft", "mi", default: "metric")
+
+```js
+const swiftcompleteReverseGeocoder = require('@swiftcomplete/reverse-geocode');
+
+swiftcompleteReverseGeocoder.setAPIKey('INSERT-KEY-HERE');
+
+swiftcompleteReverseGeocoder.reverseGeocode('51.499403,-0.127362', {
+    maxResults: 5,
+    distanceUnits: "ft"
+}).then(function(results) {
     console.log(results);
 });
 ```
 
 ## Data coverage
 
-Swiftcomplete reverse geocoding is currently available in the following countries:
+Swiftcomplete reverse geocoding is currently available in the United Kingdom. We'll be adding the following countries shortly:
 
 - Denmark
 - France
 - Liechtenstein
 - Luxembourg
 - Norway
-- United Kingdom
-
 
 We regularly update and expand our data coverage - **[contact us](https://www.swiftcomplete.com/contact-us/)** if there's a country or dataset that isn't listed and we'll let you know where it is on our priority list.
 

index.js

@@ -25,6 +25,34 @@ async function makeRequest(url) {
     });
 }
 
+function parseDistanceUnits(str) {
+    let result = '';
+    let parsedStr = str.toLowerCase().trim();
+
+    switch (parsedStr) {
+        case 'metric':
+            result = 'metric';
+            break;
+        case 'imperial':
+            result = 'imperial';
+            break;
+        case 'km':
+            result = 'km';
+            break;
+        case 'm':
+            result = 'm';
+            break;
+        case 'mi':
+            result = 'mi';
+            break;
+        case 'ft':
+            result = 'ft';
+            break;
+    }
+
+    return result;
+}
+
 /**
  * Sets the API key to authenticate your request to the Swiftcomplete API. You can obtain an API key at https://www.swiftcomplete.com
  * @param key
@@ -39,29 +67,33 @@ exports.setAPIKey = function (key) {
 
 /**
  * Returns the nearest address, street or places to a coordinate
- * @param {String} coordinate A WGS84 coordinate, in the format "latitude,longitude"
+ * @param {string} coordinate A WGS84 coordinate, in the format "latitude,longitude"
  * @param {Object} options Optional options object
- * @param {Integer} options.maxResults Max number of results to return (up to 5). Note that you are billed per result, so 4 results = 4 charges.
+ * @param {("metric"|"imperial"|"m"|"km"|"ft"|"mi")} [options.distanceUnits="metric"] Unit of measurement to display how far away the address is from your coordinate
+ * @param {number} [options.maxResults=1] Max number of results to return (up to 5). Note that you are billed per result, so 4 results = 4 charges.
  * @returns {Promise} Array of matching results
  */
 exports.reverseGeocode = function (coordinate, options) {
     if (apiKey.length == 0)
         throw 'You must set your API key first by calling setAPIKey(key)';
 
-    let requestOptions = {
-        maxResults: 1
-    };
+    let url = `https://api.swiftcomplete.com/v1/places/?key=${apiKey}&searchMode=reverseGeocode&biasTowards=${coordinate}`;
 
     if (options) {
+        if ('distanceUnits' in options) {
+            let parsedDistanceUnits = parseDistanceUnits(options.distanceUnits);
+
+            if (parsedDistanceUnits.length > 0)
+                url += `&distanceUnits=${parsedDistanceUnits}`;
+        }
+
         if ('maxResults' in options) {
             let parsedMaxResults = parseInt(options.maxResults);
 
             if (!isNaN(parsedMaxResults) && parsedMaxResults >= 1 && parsedMaxResults <= 5)
-                requestOptions.maxResults = options.maxResults;
+                url += `&maxResults=${parsedMaxResults}`;
         }
     }
 
-    let url = `https://api.swiftcomplete.com/v1/places/?key=${apiKey}&biasTowards=${coordinate}&maxResults=${requestOptions.maxResults}&populateIndex=0`;
-
     return makeRequest(url);
 }