Merge pull request #11 from AddSearch/field-stats

Add field statistics

Author: anttiai

README.md

@@ -1,15 +1,15 @@
 # AddSearch Search API Client for JavaScript
 
-[AddSearch](https://www.addsearch.com) is a hosted search platform for all your web content. This API 
-Client lets you easily use the [AddSearch Search API](https://www.addsearch.com/support/api-reference/) 
-from your JavaScript code on web browsers or with Node.js.
+[AddSearch](https://www.addsearch.com) is a Search-as-a-Service for all your search needs. This API 
+Client lets you easily use the [AddSearch Search API](https://www.addsearch.com/docs/api/) 
+with JavaScript on web browsers or from Node.js.
 
 ## Quick Start
-The library is available on the global CDN [jsDelivr:](https://www.jsdelivr.com/)
+The library is available on the global CDN [jsDelivr:](https://www.jsdelivr.com/package/npm/addsearch-js-client)
 ```html
 <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/addsearch-js-client.min.js"></script>
 ```
-To install the library locally or to use it with Node.js:
+Or install the library locally to use it with Node.js:
 ```sh
 npm install addsearch-js-client --save
 ```
@@ -209,10 +209,11 @@ Use the following function to get more or less facets.
 client.setNumberOfFacets(20);
 ```
 
-#### Numeric range facets
+#### Numerical range facets
 Group numerical custom fields into range buckets.
 ```js
-// Define ranges. E.g. products with price $0-$100, $100-$200, and over $200 (from value is inclusive, to value is exclusive)
+// Define ranges. E.g. products with price $0-$100, $100-$200, and over $200.
+// From value is inclusive, to value is exclusive
 var ranges = [
   {'to': 100},
   {'from': 100, 'to': 200},
@@ -223,6 +224,15 @@ var ranges = [
 client.addRangeFacet('custom_fields.price', ranges);
 ```
 
+### Field statistics
+Get minimum, maximum, and average values of a numerical or date-based custom field. The information
+is handy for applications like range filtering.
+```js
+// Search response will have a fieldStats element with information like 
+// custom_fields.price: {min: 1230, max: 1590, avg: 1382}
+client.addStatsField('custom_fields.price');
+```
+
 ### Search analytics
 #### Send search event to analytics
 When search is executed, send the event to your AddSearch Analytics Dashboard.

src/apifetch.js

@@ -101,6 +101,14 @@ var executeApiFetch = function(sitekey, type, settings, cb, fuzzyRetry) {
       }
 
 
+      // Stats fields
+      if (settings.statsFields) {
+        for (var i = 0; i<settings.statsFields.length; i++) {
+          qs = qs + '&fieldStat=' + settings.statsFields[i];
+        }
+      }
+
+
       // Personalization events
       if (settings.personalizationEvents && Array.isArray(settings.personalizationEvents)) {
         for (var i = 0; i<settings.personalizationEvents.length; i++) {

src/index.js

@@ -110,6 +110,7 @@ var client = function(sitekey) {
   this.setAutocompleteSize = function(size) { this.settings.setAutocompleteSize(size); }
   this.addFacetField = function(fieldName) { this.settings.addFacetField(fieldName); }
   this.addRangeFacet = function(field, ranges) { this.settings.addRangeFacet(field, ranges); }
+  this.addStatsField = function(field) { this.settings.addStatsField(field); }
   this.setNumberOfFacets = function(numFacets) { this.settings.setNumberOfFacets(numFacets); }
   this.setResultType = function(type) { this.settings.setResultType(type); }
   this.setPersonalizationEvents = function(events) { this.settings.setPersonalizationEvents(events); }

src/settings.js

@@ -154,6 +154,15 @@ var settings = function() {
     });
   }
 
+  this.addStatsField = function(field) {
+    if (!this.settings.statsFields) {
+      this.settings.statsFields = [];
+    }
+    if (this.settings.statsFields.indexOf(field) === -1) {
+      this.settings.statsFields.push(field);
+    }
+  }
+
   this.setNumberOfFacets = function(numFacets) {
     this.settings.numFacets = numFacets;
   }