Add deprecation notice to Beta version

Closes pelias/pelias#118

DOCS.md

@@ -1,3 +1,14 @@
+# --- WARNING ---
+## Pelias v1.0 will be released in September 2015!!!
+## All users must obtain FREE developer keys in order to
+## continue using the Pelias service after v1.0 has been released.
+## There will be breaking changes to the API,
+## so action must be taken to upgrade client code.
+## Backwards compatibility will be maintained through November 2015,
+## after which the old service will be deprecated and taken off line.
+# ----- END -----
+
+
 ## /search
 
 The full text search endpoint that matches the name of a place to points on the planet.

helper/geojsonify.js

@@ -1,5 +1,6 @@
 
 var GeoJSON = require('geojson'),
+    extend = require('extend'),
     extent = require('geojson-extent'),
     outputGenerator = require('./outputGenerator');
 
@@ -59,8 +60,10 @@ function search( docs, params ){
     return doc;
   });
 
-  // convert to geojson
+  var geojson = buildGeocodingBlock();
-  var geojson = GeoJSON.parse( geodata, { Point: ['lat', 'lng'] });
+  // convert to geojson and merge with geocoding block
+  // (geocoding block is first so it shows up on top)
+  extend(geojson, GeoJSON.parse( geodata, { Point: ['lat', 'lng'] }));
 
   // bounding box calculations
   // @note: extent() sometimes throws Errors for unusual data
@@ -105,5 +108,25 @@ function warning( doc ) {
   return false; // remove offending doc from results
 }
 
+/**
+ * Build geocoding block with version info and deprecation warning
+ *
+ * @return {object}
+ */
+function buildGeocodingBlock() {
+  var geocoding = {};
+
+  geocoding.version = 'BETA';
+  geocoding.messages = {
+    warn: [
+      'Pelias v1.0 will be released in September 2015!!!',
+      'Starting September 1st, all users must obtain FREE developer keys in order to continue using this service.',
+      'There will be breaking changes to the API, so action must be taken to upgrade client code.',
+      'Backwards compatibility will be maintained through November, followed by deprecation and shut-off of previous version.'
+    ]
+  };
+
+  return { geocoding: geocoding };
+}
 
 module.exports.search = search;

test/unit/helper/geojsonify.js

@@ -1,4 +1,5 @@
 
+var extend = require('extend');
 var geojsonify = require('../../../helper/geojsonify');
 
 module.exports.tests = {};
@@ -37,6 +38,20 @@ module.exports.tests.earth = function(test, common) {
 
 module.exports.tests.search = function(test, common) {
 
+  var geocoding = {
+    'geocoding': {
+      'version': 'BETA',
+      'messages': {
+        'warn': [
+          'Pelias v1.0 will be released in September 2015!!!',
+          'Starting September 1st, all users must obtain FREE developer keys in order to continue using this service.',
+          'There will be breaking changes to the API, so action must be taken to upgrade client code.',
+          'Backwards compatibility will be maintained through November, followed by deprecation and shut-off of previous version.'
+        ]
+      }
+    }
+  };
+
   var input = [
     {
       '_id': 'id1',
@@ -217,6 +232,9 @@ module.exports.tests.search = function(test, common) {
     ]
   };
 
+  // merge in geocoding block
+  extend(expected, geocoding);
+
   var truthy_params = [true, 1];
 
   test('geojsonify.search(doc, true) with details', function(t) {
@@ -285,6 +303,9 @@ module.exports.tests.search = function(test, common) {
     ]
   };
 
+  // merge in geocoding block
+  extend(no_details_expected, geocoding);
+
   test('geojsonify.search(doc) with no details (default)', function(t) {
     var json = geojsonify.search( input );
     t.deepEqual(json, no_details_expected, 'all docs (with no details) mapped');