Exposing new methods getAddressById and getPostcodeArea

Some improvements to documentation and examples

.eslintignore

@@ -0,0 +1,2 @@
+# Disable checking index, because it is only a export wrapper
+index.js

README.md

@@ -7,9 +7,11 @@ Simply grap the module from npm by doing `npm install --save postcode-nl`. After
 ## Methods
 This module exposes various methods globally:
 
-- getSingleAddress - To receive information about a postcode/number combination
-- getSinglePostcode - To receive information about a postcode
-- helpers - Some additional helper functions to validate postcodes
+- [getSingleAddress](https://joostdebruijn.github.io/node-postcode-nl/docs/global.html#getSingleAddress) - To receive information about a postcode/number combination
+- [getSinglePostcode](https://joostdebruijn.github.io/node-postcode-nl/docs/global.html#getSinglePostcode) - To receive information about a postcode
+- [getAddressById](https://joostdebruijn.github.io/node-postcode-nl/docs/global.html#getAddressById) - To receive the details of an object based on it's BAG identifier
+- [getPostcodeArea](https://joostdebruijn.github.io/node-postcode-nl/docs/global.html#getPostcodeArea) - Receive all information about a particular postcode area.
+- [helpers](https://joostdebruijn.github.io/node-postcode-nl/docs/module-helpers.html) - Some additional helper functions to validate postcodes
 
 The [documentation](https://joostdebruijn.github.io/node-postcode-nl) contains a full explaination of all the parameters and provide some examples. The documentation could be accessed by web or could be build from source by using jsdoc.
 

index.js

@@ -2,5 +2,7 @@
 module.exports = {
   getSingleAddress: require('./lib/getSingleAddress.js'),
   getSinglePostcode: require('./lib/getSinglePostcode.js'),
+  getAddressById: require('./lib/getAddressById.js'),
+  getPostcodeArea: require('./lib/getPostcodeArea.js'),
   helpers: require('./lib/helpers.js')
 };

lib/getAddressById.js

@@ -0,0 +1,49 @@
+/**
+ * To search for an address based on the BAG identifier of the object. Instance of GET /addresses.
+ * @name getAddressById
+ * @method
+ * @static
+ * @since 1.1.0
+ * @param {Object} options - Options for performing the API call and influencing the callback.
+ * @param {String} options.apiKey - The API-token to access the API.
+ * @param {Boolean} [options.returnRateLimit] - If set to true, the callback will be invoked with an extra result containing an object with the limit and the remaining amount of API calls.
+ * @param {String} id - The BAG identifier of the object.
+ * @param {Function} callback - A callback which is called when the API-request is finished.
+ * @param {Error} callback.error - May contain an instance of Error, if no error occured null is responded.
+ * @param {Object} callback.result - Contains the response as a json in exactly the same format as provided by the API. If no results are found, null is responded.
+ * @param {Object} [callback.rateLimit] - If requested in options, an object with information about the API limits is returned. Otherwise, it will return undefined.
+ * @example
+ * const postcodeApi = require('postcode-nl');
+ *
+ * let options = {
+ *   apiKey : 'abcdefghijklmnopQRSTUVWXYZ123',
+ *   returnRateLimit : true
+ * };
+ * let id = '0268200000075156';
+ *
+ * postcodeApi.getAddressById(options, id, (error, result, rateLimit) => {
+ *   if (!error) {
+ *     console.log(result); // Shows the output of the API directy in the console
+ *     console.log(rateLimit); // Shows the rateLimit information in the console
+ *   }
+ * });
+ */
+
+const api = require('./doApiCall.js');
+
+module.exports = (options, id, callback) => {
+
+  // Check if postcode is correctly formatted for this API-call
+  if (!id == null || typeof(id) !== 'string') {
+    return callback(new Error('The BAG identifier is a required parameter and must be formatted as a string'), null);
+  }
+
+  // Preparing options for request
+  options.url = 'https://postcode-api.apiwise.nl/v2/addresses/' + id;
+  options.headers = {
+    'X-Api-Key' : options.apiKey
+  };
+
+  // Executing API-request
+  return api(options, callback);
+};

lib/getPostcodeArea.js

@@ -0,0 +1,51 @@
+/**
+ * Query for the summarized information of a whole postcode area
+ * @name getPostcodeArea
+ * @method
+ * @static
+ * @since 1.1.0
+ * @param {Object} options - Options for performing the API call and influencing the callback.
+ * @param {String} options.apiKey - The API-token to access the API.
+ * @param {Boolean} [options.returnRateLimit] - If set to true, the callback will be invoked with an extra result containing an object with the limit and the remaining amount of API calls.
+ * @param {String} postcodeArea - The postcode area to be queried, formatted as P4.
+ * @param {Function} callback - A callback which is called when the API-request is finished.
+ * @param {Error} callback.error - May contain an instance of Error, if no error occured null is responded.
+ * @param {Object} callback.result - Contains the response as a json in exactly the same format as provided by the API. If no results are found, null is responded.
+ * @param {Object} [callback.rateLimit] - If requested in options, an object with information about the API limits is returned. Otherwise, it will return undefined.
+ * @todo Support for pagination
+ * @example
+ * const postcodeApi = require('postcode-nl');
+ *
+ * let options = {
+ *   apiKey : 'abcdefghijklmnopQRSTUVWXYZ123',
+ *   returnRateLimit : true
+ * };
+ * let postcodeArea = '1234';
+ *
+ * postcodeApi.getPostcodeArea(options, id, (error, result, rateLimit) => {
+ *   if (!error) {
+ *     console.log(result); // Shows the output of the API directy in the console
+ *     console.log(rateLimit); // Shows the rateLimit information in the console
+ *   }
+ * });
+ */
+
+const helpers = require('./helpers.js');
+const api = require('./doApiCall.js');
+
+module.exports = (options, postcodeArea, callback) => {
+
+  // Check if postcode is correctly formatted for this API-call
+  if (!postcodeArea == null || typeof(postcodeArea) !== 'string' || !helpers.validatePostcodeP4(postcodeArea)) {
+    return callback(new Error('A postcode formatted in P4 is a required for this API'), null);
+  }
+
+  // Preparing options for request
+  options.url = 'https://postcode-api.apiwise.nl/v2/postcodes/?postcodeArea=' + postcodeArea;
+  options.headers = {
+    'X-Api-Key' : options.apiKey
+  };
+
+  // Executing API-request
+  return api(options, callback);
+};

lib/getSingleAddress.js

@@ -1,32 +1,30 @@
 /**
- * To search for an address based on a postcode and number. Instance of GET /address.
+ * To search for an address based on a postcode and number. Instance of GET /addresses.
  * @name getSingleAddress
  * @method
  * @static
  * @since 1.0.0
- * @param {Object} options - Options for performing the API call and influencing the callback
- * @param {String} options.apiKey - The API-token to access the API
- * @param {Boolean} [options.returnRateLimit] - If set to true, the callback will be invoked with an extra result containing an object with the limit and the remaining amount of API calls
- * @param {Object} query - Containing the query for calling the API
- * @param {String} query.postcode - Must contain the keys postcode (P6-formatted)
- * @param {Number} query.number - The streetnumber of the address that must be queried
+ * @param {Object} options - Options for performing the API call and influencing the callback.
+ * @param {String} options.apiKey - The API-token to access the API.
+ * @param {Boolean} [options.returnRateLimit] - If set to true, the callback will be invoked with an extra result containing an object with the limit and the remaining amount of API calls.
+ * @param {Object} query - Containing the query for calling the API.
+ * @param {String} query.postcode - Must contain the keys postcode (P6-formatted).
+ * @param {Number} query.number - The streetnumber of the address that must be queried.
  * @param {Function} callback - A callback which is called when the API-request is finished.
  * @param {Error} callback.error - May contain an instance of Error, if no error occured null is responded.
- * @param {Object} callback.result - Contains the response as a json. If no results are found, null is responded.
+ * @param {Object} callback.result - Contains the response as a json in exactly the same format as provided by the API. If no results are found, null is responded.
  * @param {Object} [callback.rateLimit] - If requested in options, an object with information about the API limits is returned. Otherwise, it will return undefined.
  * @example
  * const postcodeApi = require('postcode-nl');
  *
  * let options = {
  *   apiKey : 'abcdefghijklmnopQRSTUVWXYZ123',
  *   returnRateLimit : true
- * }
+ * };
  * let query = {
  *   postcode: '1234AB',
  *   number: 10
- * }
- *
- * console.log(postcodeApi.getSingleAddress);
+ * };
  *
  * postcodeApi.getSingleAddress(options, query, (error, result, rateLimit) => {
  *   if (!error) {
@@ -52,11 +50,9 @@ module.exports = (options, query, callback) => {
   }
 
   // Preparing options for request
-  options.url = 'https://postcode-api.apiwise.nl/v2/addresses';
+  options.url = 'https://postcode-api.apiwise.nl/v2/addresses/?postcode=' + query.postcode + '&number=' + query.number;
   options.headers = {
-    'X-Api-Key' : options.apiKey,
-    'postcode' : query.postcode,
-    'number' : query.number
+    'X-Api-Key' : options.apiKey
   };
 
   // Executing API-request

lib/getSinglePostcode.js

@@ -1,24 +1,24 @@
 /**
- * To search for an address based on a postcode and number. Instance of GET /postcode.
+ * To search for an address based on a postcode and number. Instance of GET /postcodes.
  * @name getSinglePostcode
  * @method
  * @static
  * @since 1.0.0
- * @param {Object} options - Options for performing the API call and influencing the callback
- * @param {String} options.apiKey - The API-token to access the API
- * @param {Boolean} [options.returnRateLimit] - If set to true, the callback will be invoked with an extra result containing an object with the limit and the remaining amount of API calls
- * @param {String} postcode - Must contain the keys postcode (P6-formatted) as a string
+ * @param {Object} options - Options for performing the API call and influencing the callback.
+ * @param {String} options.apiKey - The API-token to access the API.
+ * @param {Boolean} [options.returnRateLimit] - If set to true, the callback will be invoked with an extra result containing an object with the limit and the remaining amount of API calls.
+ * @param {String} postcode - The postcode to query, formatted in P6.
  * @param {Function} callback - A callback which is called when the API-request is finished.
  * @param {Error} callback.error - May contain an instance of Error, if no error occured null is responded.
- * @param {Object} callback.result - Contains the response as a json. If no results are found, null is responded.
+ * @param {Object} callback.result - Contains the response as a json in exactly the same format as provided by the API. If no results are found, null is responded.
  * @param {Object} [callback.rateLimit] - If requested in options, an object with information about the API limits is returned. Otherwise, it will return undefined.
  * @example
  * const postcodeApi = require('postcode-nl');
  *
  * let options = {
  *    apiKey : 'abcdefghijklmnopQRSTUVWXYZ123'
- *  }
- * let postcode = '1234AB'
+ * };
+ * let postcode = '1234AB';
  *
  * postcodeApi.getSinglePostcode(options, postcode, (error, result) => {
  *  if (!error) {