feat: Merge pull request #850 from pelias/add-placeholder-support

Add placeholder support

controller/placeholder.js

@@ -0,0 +1,271 @@
+const _ = require('lodash');
+const logger = require('pelias-logger').get('api');
+const Document = require('pelias-model').Document;
+const geolib = require('geolib');
+
+// composition of toNumber and isFinite, useful for single call to convert a value
+//  to a number, then checking to see if it's finite
+function isFiniteNumber(value) {
+  return !_.isEmpty(_.trim(value)) && _.isFinite(_.toNumber(value));
+}
+
+// returns true if value is parseable as finite non-negative number
+function isNonNegativeFiniteNumber(value) {
+  return isFiniteNumber(value) && _.gte(value, 0);
+}
+
+function hasLatLon(result) {
+  return _.isFinite(_.get(result.geom, 'lat')) && _.isFinite(_.get(result.geom, 'lon'));
+}
+
+function getLatLon(result) {
+  return {
+    latitude: result.geom.lat,
+    longitude: result.geom.lon
+  };
+}
+
+// if geom.lat/lon are parseable as finite numbers, convert to a finite number
+// otherwise remove the field
+function numberifyGeomLatLon(result) {
+  ['lat', 'lon'].forEach((f) => {
+    if (isFiniteNumber(_.get(result.geom, f))) {
+      result.geom[f] = _.toFinite(result.geom[f]);
+    } else {
+      // result.geom may not exist, so use unset instead of delete
+      _.unset(result.geom, f);
+    }
+  });
+
+  return result;
+
+}
+
+// returns true if all 4 ,-delimited (max) substrings are parseable as finite numbers
+// '12.12,21.21,13.13,31.31'       returns true
+// '12.12,21.21,13.13,31.31,14.14' returns false
+// '12.12,21.21,13.13,blah'        returns false
+// '12.12,21.21,13.13,31.31,blah'  returns false
+// '12.12,NaN,13.13,31.31'         returns false
+// '12.12,Infinity,13.13,31.31'    returns false
+function is4CommaDelimitedNumbers(bbox) {
+  return _.defaultTo(bbox, '').
+    split(',').
+    filter(isFiniteNumber).length === 4;
+}
+
+function hasName(result) {
+  return !_.isEmpty(_.trim(result.name));
+}
+
+// filter that passes only results that match on requested layers
+// passes everything if req.clean.layers is not found
+function getLayersFilter(clean) {
+  if (_.isEmpty(_.get(clean, 'layers', []))) {
+    return _.constant(true);
+  }
+
+  // otherwise return a function that checks for set inclusion of a result placetype
+  return (result) => {
+    return _.includes(clean.layers, result.placetype);
+  };
+
+}
+
+// return true if the hierarchy does not have a country.abbr
+// OR hierarchy country.abbr matches boundary.country
+function matchesBoundaryCountry(boundaryCountry, hierarchy) {
+  return !boundaryCountry || _.get(hierarchy, 'country.abbr') === boundaryCountry;
+}
+
+// return true if the result does not have a lineage
+// OR at least one lineage matches the requested boundary.country
+function atLeastOneLineageMatchesBoundaryCountry(boundaryCountry, result) {
+  return !result.lineage || result.lineage.some(_.partial(matchesBoundaryCountry, boundaryCountry));
+}
+
+// return a function that detects if a result has at least one lineage in boundary.country
+// if there's no boundary.country, return a function that always returns true
+function getBoundaryCountryFilter(clean) {
+  if (_.has(clean, 'boundary.country')) {
+    return _.partial(atLeastOneLineageMatchesBoundaryCountry, clean['boundary.country']);
+  }
+
+  return _.constant(true);
+
+}
+
+// return a function that detects if a result is inside a bbox if a bbox is available
+// if there's no bbox, return a function that always returns true
+function getBoundaryRectangleFilter(clean) {
+  if (['min_lat', 'min_lon', 'max_lat', 'max_lon'].every((f) => {
+    return _.has(clean, `boundary.rect.${f}`);
+  })) {
+    const polygon = [
+      { latitude: clean['boundary.rect.min_lat'], longitude: clean['boundary.rect.min_lon'] },
+      { latitude: clean['boundary.rect.max_lat'], longitude: clean['boundary.rect.min_lon'] },
+      { latitude: clean['boundary.rect.max_lat'], longitude: clean['boundary.rect.max_lon'] },
+      { latitude: clean['boundary.rect.min_lat'], longitude: clean['boundary.rect.max_lon'] }
+    ];
+    const isPointInsidePolygon = _.partialRight(geolib.isPointInside, polygon);
+
+    return _.partial(isInsideGeometry, isPointInsidePolygon);
+
+  }
+
+  return _.constant(true);
+
+}
+
+// return a function that detects if a result is inside a circle if a circle is available
+// if there's no circle, return a function that always returns true
+function getBoundaryCircleFilter(clean) {
+  if (['lat', 'lon', 'radius'].every((f) => {
+    return _.has(clean, `boundary.circle.${f}`);
+  })) {
+    const center = {
+      latitude: clean['boundary.circle.lat'],
+      longitude: clean['boundary.circle.lon']
+    };
+    const radiusInMeters = clean['boundary.circle.radius'] * 1000;
+    const isPointInCircle = _.partialRight(geolib.isPointInCircle, center, radiusInMeters);
+
+    return _.partial(isInsideGeometry, isPointInCircle);
+
+  }
+
+  return _.constant(true);
+
+}
+
+// helper that calls an "is inside some geometry" function
+function isInsideGeometry(f, result) {
+  return hasLatLon(result) ? f(getLatLon(result)) : false;
+}
+
+function placetypeHasNameAndId(hierarchyElement) {
+  return !_.isEmpty(_.trim(hierarchyElement.name)) &&
+          !_.isEmpty(_.trim(hierarchyElement.id));
+}
+
+// synthesize an ES doc from a placeholder result
+function synthesizeDocs(boundaryCountry, result) {
+  const doc = new Document('whosonfirst', result.placetype, result.id.toString());
+  doc.setName('default', result.name);
+
+  // only assign centroid if both lat and lon are finite numbers
+  if (hasLatLon(result)) {
+    doc.setCentroid( { lat: result.geom.lat, lon: result.geom.lon } );
+  } else {
+    logger.error(`could not parse centroid for id ${result.id}`);
+  }
+
+  // lodash conformsTo verifies that an object has a property with a certain format
+  if (_.conformsTo(result.geom, { 'bbox': is4CommaDelimitedNumbers } )) {
+    const parsedBoundingBox = result.geom.bbox.split(',').map(_.toFinite);
+    doc.setBoundingBox({
+      upperLeft: {
+        lat: parsedBoundingBox[3],
+        lon: parsedBoundingBox[0]
+      },
+      lowerRight: {
+        lat: parsedBoundingBox[1],
+        lon: parsedBoundingBox[2]
+      }
+    });
+  } else {
+    logger.error(`could not parse bbox for id ${result.id}: ${_.get(result, 'geom.bbox')}`);
+  }
+
+  // set population and popularity if parseable as finite number
+  if (isNonNegativeFiniteNumber(result.population)) {
+    doc.setPopulation(_.toFinite(result.population));
+  }
+  if (isNonNegativeFiniteNumber(result.popularity)) {
+    doc.setPopularity(_.toFinite(result.popularity));
+  }
+
+  _.defaultTo(result.lineage, [])
+    // remove all lineages that don't match an explicit boundary.country
+    .filter(_.partial(matchesBoundaryCountry, boundaryCountry))
+    // add all the lineages to the doc
+    .map((hierarchy) => {
+      Object.keys(hierarchy)
+        .filter(doc.isSupportedParent)
+        .filter((placetype) => {
+          return placetypeHasNameAndId(hierarchy[placetype]);
+        })
+        .forEach((placetype) => {
+          doc.addParent(
+            placetype,
+            hierarchy[placetype].name,
+            hierarchy[placetype].id.toString(),
+            hierarchy[placetype].abbr);
+      });
+    });
+
+  return buildESDoc(doc);
+
+}
+
+function buildESDoc(doc) {
+  const esDoc = doc.toESDocument();
+  return _.extend(esDoc.data, { _id: esDoc._id, _type: esDoc._type });
+}
+
+function setup(placeholderService, should_execute) {
+  function controller( req, res, next ){
+    // bail early if req/res don't pass conditions for execution
+    if (!should_execute(req, res)) {
+      return next();
+    }
+
+    placeholderService(req, (err, results) => {
+      if (err) {
+        // bubble up an error if one occurred
+        if (_.isObject(err) && err.message) {
+          req.errors.push( err.message );
+        } else {
+          req.errors.push( err );
+        }
+
+      } else {
+        const boundaryCountry = _.get(req, ['clean', 'boundary.country']);
+
+        // convert results to ES docs
+        // boundary.country filter must happen after synthesis since multiple
+        //  lineages may produce different country docs
+        res.meta = {};
+        res.data = results
+                    // filter out results that don't have a name
+                    .filter(hasName)
+                    // filter out results that don't match on requested layer(s)
+                    .filter(getLayersFilter(req.clean))
+                    // filter out results that don't match on any lineage country
+                    .filter(getBoundaryCountryFilter(req.clean))
+                    // clean up geom.lat/lon for boundary rect/circle checks
+                    .map(numberifyGeomLatLon)
+                    // filter out results that aren't in the boundary.rect
+                    .filter(getBoundaryRectangleFilter(req.clean))
+                    // filter out results that aren't in the boundary.circle
+                    .filter(getBoundaryCircleFilter(req.clean))
+                    // convert results to ES docs
+                    .map(_.partial(synthesizeDocs, boundaryCountry));
+
+        const messageParts = [
+          '[controller:placeholder]',
+          `[result_count:${_.defaultTo(res.data, []).length}]`
+        ];
+
+        logger.info(messageParts.join(' '));
+      }
+
+      return next();
+    });
+
+  }
+
+  return controller;
+}
+
+module.exports = setup;

controller/predicates/has_results_at_layers.js

@@ -0,0 +1,19 @@
+const _ = require('lodash');
+
+// returns a function that returns true if any result.layer is in any of the
+// supplied layers using array intersection
+
+// example usage: determining if the response contains only admin results
+
+module.exports = (layers) => {
+  return (request, response) => {
+    return !_.isEmpty(
+      _.intersection(
+        // convert layers to an array if it isn't already one
+        _.castArray(layers),
+        // pull all the layer properties into an array
+        _.map(response.data, _.property('layer'))
+    ));
+  };
+
+};

controller/predicates/is_admin_only_analysis.js

@@ -0,0 +1,13 @@
+const _ = require('lodash');
+
+module.exports = (request, response) => {
+  if (!request.clean.hasOwnProperty('parsed_text')) {
+    return false;
+  }
+
+  // return true only if all non-admin properties of parsed_text are empty
+  return ['number', 'street', 'query', 'category'].every((prop) => {
+    return _.isEmpty(request.clean.parsed_text[prop]);
+  });
+
+};

controller/predicates/is_pip_service_enabled.js

@@ -1,7 +0,0 @@
-module.exports = (uri) => {
-  // this predicate relies upon the fact that the schema has already validated
-  //  that api.pipService is a URI-formatted string
-  return (request, response) => {
-    return uri !== undefined;
-  };
-};

controller/predicates/is_service_enabled.js

@@ -0,0 +1,5 @@
+module.exports = (uri) => {
+  return (request, response) => {
+    return uri !== undefined;
+  };
+};

middleware/normalizeParentIds.js

@@ -1,7 +1,9 @@
-var logger = require('pelias-logger').get('api');
-var Document = require('pelias-model').Document;
+'use strict';
 
-var placeTypes = require('../helper/placeTypes');
+const logger = require('pelias-logger').get('api');
+const Document = require('pelias-model').Document;
+const placeTypes = require('../helper/placeTypes');
+const _ = require('lodash');
 
 /**
  * Convert WOF integer ids to Pelias formatted ids that can be used by the /place endpoint.
@@ -32,16 +34,18 @@ function normalizeParentIds(place) {
   if (place) {
     placeTypes.forEach(function (placeType) {
       if (place[placeType] && place[placeType].length > 0 && place[placeType][0]) {
-        var source = 'whosonfirst';
+        let source = 'whosonfirst';
+
+        const placetype_ids = _.get(place, `${placeType}_gid`, [null]);
 
         // looking forward to the day we can remove all geonames specific hacks, but until then...
         // geonames sometimes has its own ids in the parent hierarchy, so it's dangerous to assume that 
         // it's always WOF ids and hardcode to that
-        if (place.source === 'geonames' && place.source_id === place[placeType + '_gid'][0]) {
+        if (place.source === 'geonames' && place.source_id === placetype_ids[0]) {
           source = place.source;
         }
         
-        place[placeType + '_gid'] = [ makeNewId(source, placeType, place[placeType + '_gid']) ];
+        place[`${placeType}_gid`] = [ makeNewId(source, placeType, placetype_ids[0]) ];
       }
     });
   }

middleware/sortResponseData.js

@@ -0,0 +1,35 @@
+const _ = require('lodash');
+
+const logger = require('pelias-logger').get('api');
+
+function setup(comparator, should_execute) {
+  function middleware(req, res, next) {
+    // bail early if req/res don't pass conditions for execution or there's no data to sort
+    if (!should_execute(req, res) || _.isEmpty(res.data)) {
+      return next();
+    }
+
+    // capture the pre-sort order
+    const presort_order = res.data.map(_.property('_id'));
+
+    // sort operates on array in place
+    res.data.sort(comparator(req.clean));
+
+    // capture the post-sort order
+    const postsort_order = res.data.map(_.property('_id'));
+
+    // log it for debugging purposes
+    logger.debug([
+      `req.clean: ${JSON.stringify(req.clean)}`,
+      `pre-sort: [${presort_order}]`,
+      `post-sort: [${postsort_order}]`
+    ].join(', '));
+
+    next();
+  }
+
+  return middleware;
+
+}
+
+module.exports = setup;

package.json

@@ -50,22 +50,24 @@
     "geolib": "^2.0.18",
     "iso-639-3": "^1.0.0",
     "iso3166-1": "^0.3.0",
-    "joi": "^10.1.0",
+    "joi": "^10.5.2",
     "locale": "^0.1.0",
-    "lodash": "^4.5.0",
+    "lodash": "^4.17.4",
     "markdown": "0.5.0",
     "morgan": "^1.8.2",
     "pelias-config": "2.10.0",
     "pelias-categories": "1.2.0",
+    "pelias-config": "2.10.0",
     "pelias-labels": "1.6.0",
     "pelias-logger": "0.2.0",
-    "pelias-mock-logger": "^1.0.1",
+    "pelias-microservice-wrapper": "1.1.0",
     "pelias-model": "4.8.1",
     "pelias-query": "8.15.0",
+    "pelias-sorting": "1.0.1",
     "pelias-text-analyzer": "1.8.2",
     "predicates": "^1.0.1",
+    "request": "^2.81.0",
     "retry": "^0.10.1",
-    "request": "^2.79.0",
     "stats-lite": "^2.0.4",
     "superagent": "^3.2.1",
     "through2": "^2.0.3"
@@ -77,6 +79,7 @@
     "jshint": "^2.5.6",
     "npm-check": "git://github.com/orangejulius/npm-check.git#disable-update-check",
     "nsp": "^2.2.0",
+    "pelias-mock-logger": "1.1.0",
     "precommit-hook": "^3.0.0",
     "proxyquire": "^1.7.10",
     "semantic-release": "^6.3.2",

routes/v1.js

@@ -4,6 +4,7 @@ var elasticsearch = require('elasticsearch');
 const all = require('predicates').all;
 const any = require('predicates').any;
 const not = require('predicates').not;
+const _ = require('lodash');
 
 /** ----------------------- sanitizers ----------------------- **/
 var sanitizers = {
@@ -28,6 +29,7 @@ var controllers = {
   coarse_reverse: require('../controller/coarse_reverse'),
   mdToHTML: require('../controller/markdownToHtml'),
   place: require('../controller/place'),
+  placeholder: require('../controller/placeholder'),
   search: require('../controller/search'),
   status: require('../controller/status')
 };
@@ -59,16 +61,23 @@ var postProc = {
   parseBoundingBox: require('../middleware/parseBBox'),
   normalizeParentIds: require('../middleware/normalizeParentIds'),
   assignLabels: require('../middleware/assignLabels'),
-  changeLanguage: require('../middleware/changeLanguage')
+  changeLanguage: require('../middleware/changeLanguage'),
+  sortResponseData: require('../middleware/sortResponseData')
 };
 
 // predicates that drive whether controller/search runs
 const hasResponseData = require('../controller/predicates/has_response_data');
 const hasRequestErrors = require('../controller/predicates/has_request_errors');
 const isCoarseReverse = require('../controller/predicates/is_coarse_reverse');
+const isAdminOnlyAnalysis = require('../controller/predicates/is_admin_only_analysis');
+const hasResultsAtLayers = require('../controller/predicates/has_results_at_layers');
 
 // shorthand for standard early-exit conditions
 const hasResponseDataOrRequestErrors = any(hasResponseData, hasRequestErrors);
+const hasAdminOnlyResults = not(hasResultsAtLayers(['venue', 'address', 'street']));
+
+const serviceWrapper = require('pelias-microservice-wrapper').service;
+const PlaceHolder = require('../service/configurations/PlaceHolder');
 
 /**
  * Append routes to app
@@ -79,13 +88,22 @@ const hasResponseDataOrRequestErrors = any(hasResponseData, hasRequestErrors);
 function addRoutes(app, peliasConfig) {
   const esclient = elasticsearch.Client(peliasConfig.esclient);
 
-  const isPipServiceEnabled = require('../controller/predicates/is_pip_service_enabled')(peliasConfig.api.pipService);
+  const isPipServiceEnabled = require('../controller/predicates/is_service_enabled')(peliasConfig.api.pipService);
+
   const pipService = require('../service/pointinpolygon')(peliasConfig.api.pipService);
 
+  const placeholderConfiguration = new PlaceHolder(_.get(peliasConfig.api.services, 'placeholder', {}));
+  const placeholderService = serviceWrapper(placeholderConfiguration);
+  const isPlaceholderServiceEnabled = _.constant(placeholderConfiguration.isEnabled());
+
   const coarse_reverse_should_execute = all(
     not(hasRequestErrors), isPipServiceEnabled, isCoarseReverse
   );
 
+  const placeholderShouldExecute = all(
+    not(hasResponseDataOrRequestErrors), isPlaceholderServiceEnabled, isAdminOnlyAnalysis
+  );
+
   // execute under the following conditions:
   // - there are no errors or data
   // - request is not coarse OR pip service is disabled
@@ -112,6 +130,7 @@ function addRoutes(app, peliasConfig) {
       sanitizers.search.middleware,
       middleware.requestLanguage,
       middleware.calcSize(),
+      controllers.placeholder(placeholderService, placeholderShouldExecute),
       // 3rd parameter is which query module to use, use fallback/geodisambiguation
       //  first, then use original search strategy if first query didn't return anything
       controllers.search(peliasConfig.api, esclient, queries.libpostal, not(hasResponseDataOrRequestErrors)),
@@ -122,6 +141,7 @@ function addRoutes(app, peliasConfig) {
       postProc.confidenceScores(peliasConfig.api),
       postProc.confidenceScoresFallback(),
       postProc.interpolate(),
+      postProc.sortResponseData(require('pelias-sorting'), hasAdminOnlyResults),
       postProc.dedupe(),
       postProc.accuracy(),
       postProc.localNamingConventions(),
@@ -143,7 +163,7 @@ function addRoutes(app, peliasConfig) {
       postProc.confidenceScores(peliasConfig.api),
       postProc.confidenceScoresFallback(),
       postProc.interpolate(),
-      postProc.dedupe(),      
+      postProc.dedupe(),
       postProc.accuracy(),
       postProc.localNamingConventions(),
       postProc.renamePlacenames(),

sanitizer/_geonames_warnings.js

@@ -0,0 +1,37 @@
+const _ = require('lodash');
+
+const non_admin_fields = ['number', 'street', 'query', 'category'];
+
+function hasAnyNonAdminFields(parsed_text) {
+  return !_.isEmpty(
+            _.intersection(
+              _.keys(parsed_text),
+              non_admin_fields));
+}
+
+function sanitize( raw, clean ){
+  // error & warning messages
+  const messages = { errors: [], warnings: [] };
+
+  // bail early if analysis isn't admin-only
+  if (_.isUndefined(clean.parsed_text) || hasAnyNonAdminFields(clean.parsed_text)) {
+    return messages;
+  }
+
+  // the analysis is admin-only, so add errors or warnings if geonames was requested
+  if (_.isEqual(clean.sources, ['geonames'])) {
+    // if requested sources is only geonames, return an error
+    messages.errors.push('input contains only administrative area data, ' +
+      'no results will be returned when sources=geonames');
+
+  } else if (_.includes(clean.sources, 'geonames')) {
+    // if there are other sources besides geonames, return an warning
+    messages.warnings.push('input contains only administrative area data, ' +
+      'geonames results will not be returned');
+
+  }
+
+  return messages;
+}
+
+module.exports = sanitize;

sanitizer/search.js

@@ -15,7 +15,9 @@ var sanitizeAll = require('../sanitizer/sanitizeAll'),
       private: require('../sanitizer/_flag_bool')('private', false),
       geo_search: require('../sanitizer/_geo_search'),
       boundary_country: require('../sanitizer/_boundary_country'),
-      categories: require('../sanitizer/_categories')
+      categories: require('../sanitizer/_categories'),
+      // this can go away once geonames has been abrogated
+      geonames_warnings: require('../sanitizer/_geonames_warnings')
     };
 
 var sanitize = function(req, cb) { sanitizeAll(req, sanitizers, cb); };

schema.js

@@ -26,7 +26,13 @@ module.exports = Joi.object().keys({
     localization: Joi.object().keys({
       flipNumberAndStreetCountries: Joi.array().items(Joi.string().regex(/^[A-Z]{3}$/))
     }).unknown(false),
-    pipService: Joi.string().uri({ scheme: /https?/ })
+    pipService: Joi.string().uri({ scheme: /https?/ }),
+    placeholderService: Joi.any().forbidden(), // got moved to services
+    services: Joi.object().keys({
+      placeholder: Joi.object().keys({
+        url: Joi.string().uri({ scheme: /https?/ })
+      }).unknown(false).requiredKeys('url')
+    }).unknown(false).default({}) // default api.services to an empty object
 
   }).requiredKeys('version', 'indexName', 'host').unknown(true),
   esclient: Joi.object().keys({

service/configurations/PlaceHolder.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const url = require('url');
+
+const _ = require('lodash');
+
+const ServiceConfiguration = require('pelias-microservice-wrapper').ServiceConfiguration;
+
+class PlaceHolder extends ServiceConfiguration {
+  constructor(o) {
+    super('placeholder', o);
+  }
+
+  getParameters(req) {
+    const parameters = {
+      text: req.clean.text
+    };
+
+    if (_.has(req.clean, 'lang.iso6393')) {
+      parameters.lang = req.clean.lang.iso6393;
+    }
+
+    return parameters;
+  }
+
+  getUrl(req) {
+    return url.resolve(this.baseUrl, 'search');
+  }
+
+}
+
+module.exports = PlaceHolder;

test/unit/controller/predicates/has_results_at_layers.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const _ = require('lodash');
+const has_results_at_layers = require('../../../../controller/predicates/has_results_at_layers');
+
+module.exports.tests = {};
+
+module.exports.tests.interface = (test, common) => {
+  test('valid interface', (t) => {
+    t.equal(typeof has_results_at_layers, 'function', 'has_results_at_layers is a function');
+    t.equal(has_results_at_layers.length, 1);
+    t.end();
+  });
+};
+
+module.exports.tests.true_conditions = (test, common) => {
+  test('should return true when any result.layer matches any layer in array', (t) => {
+    const req = {};
+    const res = {
+      data: [
+        {
+          layer: 'layer 1'
+        },
+        {
+          layer: 'layer 2'
+        },
+        {
+          layer: 'layer 3'
+        }
+      ]
+    };
+
+    t.ok(has_results_at_layers(['layer 2', 'layer 4'])(req, res));
+    t.end();
+
+  });
+
+  test('should return true when any result.layer matches layer string', (t) => {
+    const req = {};
+    const res = {
+      data: [
+        {
+          layer: 'layer 1'
+        },
+        {
+          layer: 'layer 2'
+        },
+        {
+          layer: 'layer 3'
+        }
+      ]
+    };
+
+    t.ok(has_results_at_layers('layer 2')(req, res));
+    t.end();
+
+  });
+
+};
+
+module.exports.tests.false_conditions = (test, common) => {
+  test('should return false when response has undefined data', (t) => {
+    const req = {};
+    const res = {};
+
+    t.notOk(has_results_at_layers('layer')(req, res));
+    t.end();
+
+  });
+
+  test('should return false when response has empty data array', (t) => {
+    const req = {};
+    const res = {
+      data: []
+    };
+
+    t.notOk(has_results_at_layers('layer')(req, res));
+    t.end();
+
+  });
+
+  test('should return false when layer is a substring of non-array string layers parameter', (t) => {
+    const req = {};
+    const res = {
+      data: [
+        {
+          layer: 'aye'
+        }
+      ]
+    };
+
+    t.notOk(has_results_at_layers('layer')(req, res));
+    t.end();
+
+  });
+
+  test('should return false when no results have layer in supplied layers', (t) => {
+    const req = {};
+    const res = {
+      data: [
+        {
+          layer: 'layer 1'
+        }
+      ]
+    };
+
+    t.notOk(has_results_at_layers(['layer 2', 'layer 3'])(req, res));
+    t.end();
+
+  });
+
+};
+
+module.exports.all = (tape, common) => {
+  function test(name, testFunction) {
+    return tape(`GET /has_results_at_layers ${name}`, testFunction);
+  }
+
+  for( const testCase in module.exports.tests ){
+    module.exports.tests[testCase](test, common);
+  }
+};

test/unit/controller/predicates/is_admin_only_analysis.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const _ = require('lodash');
+const is_admin_only_analysis = require('../../../../controller/predicates/is_admin_only_analysis');
+
+module.exports.tests = {};
+
+module.exports.tests.interface = (test, common) => {
+  test('valid interface', (t) => {
+    t.equal(typeof is_admin_only_analysis, 'function', 'is_admin_only_analysis is a function');
+    t.end();
+  });
+};
+
+module.exports.tests.true_conditions = (test, common) => {
+  test('parsed_text with admin-only properties should return true', (t) => {
+    ['neighbourhood', 'borough', 'city', 'county', 'state', 'postalcode', 'country'].forEach((property) => {
+      const req = {
+        clean: {
+          parsed_text: {}
+        }
+      };
+      const res = {};
+
+      req.clean.parsed_text[property] = `${property} value`;
+
+      t.ok(is_admin_only_analysis(req, res));
+
+    });
+    t.end();
+
+  });
+
+};
+
+module.exports.tests.false_conditions = (test, common) => {
+  test('req.clean with no parsed_text should return false', (t) => {
+    const req = {
+      clean: {
+      }
+    };
+    const res = {};
+
+    t.notOk(is_admin_only_analysis(req, res));
+    t.end();
+
+  });
+
+  test('parsed_text with non-admin properties should return false', (t) => {
+    ['number', 'street', 'query', 'category'].forEach((property) => {
+      const req = {
+        clean: {
+          parsed_text: {}
+        }
+      };
+      const res = {};
+
+      req.clean.parsed_text[property] = `${property} value`;
+
+      t.notOk(is_admin_only_analysis(req, res));
+
+    });
+    t.end();
+
+  });
+
+};
+
+module.exports.all = (tape, common) => {
+  function test(name, testFunction) {
+    return tape(`GET /is_admin_only_analysis ${name}`, testFunction);
+  }
+
+  for( const testCase in module.exports.tests ){
+    module.exports.tests[testCase](test, common);
+  }
+};

test/unit/controller/predicates/is_service_enabled.js

@@ -1,21 +1,21 @@
 'use strict';
 
 const _ = require('lodash');
-const is_pip_service_enabled = require('../../../../controller/predicates/is_pip_service_enabled');
+const is_service_enabled = require('../../../../controller/predicates/is_service_enabled');
 
 module.exports.tests = {};
 
 module.exports.tests.interface = (test, common) => {
   test('valid interface', (t) => {
-    t.equal(typeof is_pip_service_enabled, 'function', 'is_pip_service_enabled  is a function');
-    t.equal(typeof is_pip_service_enabled(), 'function', 'is_pip_service_enabled() is a function');
+    t.equal(typeof is_service_enabled, 'function', 'is_service_enabled  is a function');
+    t.equal(typeof is_service_enabled(), 'function', 'is_service_enabled() is a function');
     t.end();
   });
 };
 
 module.exports.tests.true_conditions = (test, common) => {
   test('string uri should return true', (t) => {
-    t.ok(is_pip_service_enabled('pip uri')());
+    t.ok(is_service_enabled('pip uri')());
     t.end();
 
   });
@@ -24,7 +24,7 @@ module.exports.tests.true_conditions = (test, common) => {
 
 module.exports.tests.false_conditions = (test, common) => {
   test('undefined uri should return false', (t) => {
-    t.notOk(is_pip_service_enabled()());
+    t.notOk(is_service_enabled()());
     t.end();
 
   });
@@ -33,7 +33,7 @@ module.exports.tests.false_conditions = (test, common) => {
 
 module.exports.all = (tape, common) => {
   function test(name, testFunction) {
-    return tape(`GET /is_pip_service_enabled ${name}`, testFunction);
+    return tape(`GET /is_service_enabled ${name}`, testFunction);
   }
 
   for( const testCase in module.exports.tests ){

test/unit/middleware/sortResponseData.js

@@ -0,0 +1,156 @@
+const _ = require('lodash');
+const proxyquire =  require('proxyquire').noCallThru();
+const mock_logger = require('pelias-mock-logger');
+
+const sortResponseData = require('../../../middleware/sortResponseData');
+
+module.exports.tests = {};
+
+module.exports.tests.should_execute_failure = (test, common) => {
+  test('should_execute returning false should call next w/o invoking comparator', (t) => {
+    t.plan(2, 'this ensures that should_execute was invoked');
+
+    const comparator = () => {
+      throw Error('should not have been called');
+    };
+
+    const should_execute = (req, res) => {
+      t.deepEquals(req, { a: 1 });
+      t.deepEquals(res, { b: 2 });
+      return false;
+    };
+
+    const sort = sortResponseData(comparator, should_execute);
+
+    const req = { a: 1 };
+    const res = { b: 2 };
+
+    sort(req, res, () => {
+      t.end();
+    });
+
+  });
+
+};
+
+module.exports.tests.general_tests = (test, common) => {
+  test('req.clean should be passed to sort', (t) => {
+    t.plan(1, 'this ensures that comparator was invoked');
+
+    const comparator = (clean) => {
+      t.deepEquals(clean, { a: 1 });
+      return () => {
+        throw Error('should not have been called');
+      };
+    };
+
+    const sort = sortResponseData(comparator, _.constant(true));
+
+    const req = {
+      clean: {
+        a: 1
+      }
+    };
+
+    const res = {
+      data: [ {} ]
+    };
+
+    sort(req, res, () => {
+      t.end();
+    });
+
+  });
+
+  test('undefined res.data should return without interacting with comparator', (t) => {
+    const comparator = () => {
+      throw Error('should not have been called');
+    };
+
+    const sort = sortResponseData(comparator, _.constant(true));
+
+    const req = {};
+    const res = {};
+
+    sort(req, res, () => {
+      t.deepEquals(res, {});
+      t.end();
+    });
+
+  });
+
+  test('empty res.data should return without interacting with comparator', (t) => {
+    const comparator = () => {
+      throw Error('should not have been called');
+    };
+
+    const sort = sortResponseData(comparator, _.constant(true));
+
+    const req = {};
+    const res = {
+      data: []
+    };
+
+    sort(req, res, () => {
+      t.deepEquals(res.data, [], 'res.data should still be empty');
+      t.end();
+    });
+
+  });
+
+};
+
+module.exports.tests.successful_sort = (test, common) => {
+  test('comparator should be sort res.data', (t) => {
+    const logger = mock_logger();
+
+    const comparator = () => {
+      return (a, b) => {
+        return a._id > b._id;
+      };
+    };
+
+    const sortResponseData = proxyquire('../../../middleware/sortResponseData', {
+      'pelias-logger': logger
+    });
+
+    const sort = sortResponseData(comparator, _.constant(true));
+
+    const req = {
+      clean: {
+        field: 'value'
+      }
+    };
+    const res = {
+      data: [
+        { _id: 3 },
+        { _id: 2 },
+        { _id: 1 },
+      ]
+    };
+
+    sort(req, res, () => {
+      t.deepEquals(res.data.shift(), { _id: 1 });
+      t.deepEquals(res.data.shift(), { _id: 2 });
+      t.deepEquals(res.data.shift(), { _id: 3 });
+
+      t.ok(logger.isDebugMessage(
+        'req.clean: {"field":"value"}, pre-sort: [3,2,1], post-sort: [1,2,3]'));
+
+      t.end();
+    });
+
+  });
+
+};
+
+module.exports.all = (tape, common) => {
+
+  function test(name, testFunction) {
+    return tape(`[middleware] sortResponseData: ${name}`, testFunction);
+  }
+
+  for( var testCase in module.exports.tests ){
+    module.exports.tests[testCase](test, common);
+  }
+};

test/unit/run.js

@@ -14,11 +14,14 @@ var tests = [
   require('./controller/coarse_reverse'),
   require('./controller/index'),
   require('./controller/place'),
+  require('./controller/placeholder'),
   require('./controller/search'),
   require('./controller/predicates/has_response_data'),
+  require('./controller/predicates/has_results_at_layers'),
   require('./controller/predicates/has_request_errors'),
+  require('./controller/predicates/is_admin_only_analysis'),
   require('./controller/predicates/is_coarse_reverse'),
-  require('./controller/predicates/is_pip_service_enabled'),
+  require('./controller/predicates/is_service_enabled'),
   require('./helper/diffPlaces'),
   require('./helper/geojsonify'),
   require('./helper/logging'),
@@ -38,6 +41,7 @@ var tests = [
   require('./middleware/parseBBox'),
   require('./middleware/sendJSON'),
   require('./middleware/normalizeParentIds'),
+  require('./middleware/sortResponseData'),
   require('./middleware/trimByGranularity'),
   require('./middleware/trimByGranularityStructured'),
   require('./middleware/requestLanguage'),
@@ -52,6 +56,7 @@ var tests = [
   require('./query/text_parser'),
   require('./sanitizer/_boundary_country'),
   require('./sanitizer/_flag_bool'),
+  require('./sanitizer/_geonames_warnings'),
   require('./sanitizer/_geo_common'),
   require('./sanitizer/_geo_reverse'),
   require('./sanitizer/_groups'),
@@ -78,6 +83,7 @@ var tests = [
   require('./sanitizer/search'),
   require('./sanitizer/search_fallback'),
   require('./sanitizer/wrap'),
+  require('./service/configurations/PlaceHolder'),
   require('./service/mget'),
   require('./service/search'),
   require('./service/interpolation'),

test/unit/sanitizer/_geonames_warnings.js

@@ -0,0 +1,111 @@
+const _ = require('lodash');
+
+const geonames_warnings = require('../../../sanitizer/_geonames_warnings');
+
+const nonAdminProperties = ['number', 'street', 'query', 'category'];
+const adminProperties = ['neighbourhood', 'borough', 'city', 'county', 'state', 'postalcode', 'country'];
+
+module.exports.tests = {};
+
+module.exports.tests.no_errors = (test, common) => {
+  test('undefined clean.parsed_text should exit early', (t) => {
+    const clean = {
+      sources: ['geonames'],
+    };
+
+    const messages = geonames_warnings(undefined, clean);
+
+    t.deepEquals(messages, { errors: [], warnings: [] });
+    t.end();
+
+  });
+
+  test('any non-admin analysis field with only geonames sources should exit early', (t) => {
+    adminProperties.forEach((adminProperty) => {
+      nonAdminProperties.forEach((nonAdminProperty) => {
+        const clean = {
+          sources: ['geonames'],
+          parsed_text: {}
+        };
+        clean.parsed_text[nonAdminProperty] = `${nonAdminProperty} value`;
+        clean.parsed_text[adminProperty] = `${adminProperty} value`;
+
+        const messages = geonames_warnings(undefined, clean);
+
+        t.deepEquals(messages, { errors: [], warnings: [] });
+
+      });
+    });
+    t.end();
+
+  });
+
+  test('any non-admin analysis field with non-geonames sources should exit early', (t) => {
+    adminProperties.forEach((adminProperty) => {
+      nonAdminProperties.forEach((nonAdminProperty) => {
+        const clean = {
+          sources: ['this is not geonames'],
+          parsed_text: {}
+        };
+        clean.parsed_text[nonAdminProperty] = `${nonAdminProperty} value`;
+        clean.parsed_text[adminProperty] = `${adminProperty} value`;
+
+        const messages = geonames_warnings(undefined, clean);
+
+        t.deepEquals(messages, { errors: [], warnings: [] });
+
+      });
+    });
+    t.end();
+
+  });
+
+};
+
+module.exports.tests.error_conditions = (test, common) => {
+  test('any admin analysis field and only geonames sources should return error', (t) => {
+    adminProperties.forEach((property) => {
+      const clean = _.set({ sources: ['geonames'] },
+        ['parsed_text', property], `${property} value`);
+
+      const messages = geonames_warnings(undefined, clean);
+
+      t.deepEquals(messages.errors, ['input contains only administrative area data, ' +
+        'no results will be returned when sources=geonames']);
+      t.deepEquals(messages.warnings, []);
+
+    });
+    t.end();
+
+  });
+
+};
+
+module.exports.tests.warning_conditions = (test, common) => {
+  test('any admin analysis field and only geonames sources should return warning', (t) => {
+    adminProperties.forEach((property) => {
+      const clean = _.set({ sources: ['source 1', 'geonames', 'source 2'] },
+        ['parsed_text', property], `${property} value`);
+
+      const messages = geonames_warnings(undefined, clean);
+
+      t.deepEquals(messages.errors, []);
+      t.deepEquals(messages.warnings, ['input contains only administrative area data, ' +
+        'geonames results will not be returned']);
+
+    });
+    t.end();
+
+  });
+
+};
+
+module.exports.all = (tape, common) => {
+  function test(name, testFunction) {
+    return tape(`SANTIZE _geonames_warnings ${name}`, testFunction);
+  }
+
+  for( var testCase in module.exports.tests ){
+    module.exports.tests[testCase](test, common);
+  }
+};

test/unit/sanitizer/search.js

@@ -1,37 +1,38 @@
-var proxyquire =  require('proxyquire').noCallThru();
+const proxyquire =  require('proxyquire').noCallThru();
+const _ = require('lodash');
 
 module.exports.tests = {};
 
-module.exports.tests.sanitize = function(test, common) {
-  test('verify that all sanitizers were called as expected', function(t) {
-    var called_sanitizers = [];
+module.exports.tests.sanitize = (test, common) => {
+  test('verify that all sanitizers were called as expected', (t) => {
+    const called_sanitizers = [];
 
     // rather than re-verify the functionality of all the sanitizers, this test just verifies that they
     //  were all called correctly
-    var search = proxyquire('../../../sanitizer/search', {
-      '../sanitizer/_deprecate_quattroshapes': function() {
+    const search = proxyquire('../../../sanitizer/search', {
+      '../sanitizer/_deprecate_quattroshapes': () => {
         called_sanitizers.push('_deprecate_quattroshapes');
         return { errors: [], warnings: [] };
       },
-      '../sanitizer/_single_scalar_parameters': function() {
+      '../sanitizer/_single_scalar_parameters': () => {
         called_sanitizers.push('_single_scalar_parameters');
         return { errors: [], warnings: [] };
       },
-      '../sanitizer/_text': function() {
+      '../sanitizer/_text': () => {
         called_sanitizers.push('_text');
         return { errors: [], warnings: [] };
       },
-      '../sanitizer/_iso2_to_iso3': function() {
+      '../sanitizer/_iso2_to_iso3': () => {
         called_sanitizers.push('_iso2_to_iso3');
         return { errors: [], warnings: [] };
       },
-      '../sanitizer/_city_name_standardizer': function() {
+      '../sanitizer/_city_name_standardizer': () => {
         called_sanitizers.push('_city_name_standardizer');
         return { errors: [], warnings: [] };
       },
       '../sanitizer/_size': function() {
-        if (arguments.length === 0) {
-          return function() {
+        if (_.isEmpty(arguments)) {
+          return () => {
             called_sanitizers.push('_size');
             return { errors: [], warnings: [] };
           };
@@ -41,10 +42,10 @@ module.exports.tests.sanitize = function(test, common) {
         }
 
       },
-      '../sanitizer/_targets': function(type) {
+      '../sanitizer/_targets': (type) => {
         if (['layers', 'sources'].indexOf(type) !== -1) {
-          return function() {
-            called_sanitizers.push('_targets/' + type);
+          return () => {
+            called_sanitizers.push(`_targets/${type}`);
             return { errors: [], warnings: [] };
           };
 
@@ -54,13 +55,13 @@ module.exports.tests.sanitize = function(test, common) {
         }
 
       },
-      '../sanitizer/_sources_and_layers': function() {
+      '../sanitizer/_sources_and_layers': () => {
         called_sanitizers.push('_sources_and_layers');
         return { errors: [], warnings: [] };
       },
       '../sanitizer/_flag_bool': function() {
         if (arguments[0] === 'private' && arguments[1] === false) {
-          return function() {
+          return () => {
             called_sanitizers.push('_flag_bool');
             return { errors: [], warnings: [] };
           };
@@ -71,21 +72,25 @@ module.exports.tests.sanitize = function(test, common) {
         }
 
       },
-      '../sanitizer/_geo_search': function() {
+      '../sanitizer/_geo_search': () => {
         called_sanitizers.push('_geo_search');
         return { errors: [], warnings: [] };
       },
-      '../sanitizer/_boundary_country': function() {
+      '../sanitizer/_boundary_country': () => {
         called_sanitizers.push('_boundary_country');
         return { errors: [], warnings: [] };
       },
-      '../sanitizer/_categories': function() {
+      '../sanitizer/_categories': () => {
         called_sanitizers.push('_categories');
         return { errors: [], warnings: [] };
       },
+        '../sanitizer/_geonames_warnings': () => {
+        called_sanitizers.push('_geonames_warnings');
+        return { errors: [], warnings: [] };
+      }
     });
 
-    var expected_sanitizers = [
+    const expected_sanitizers = [
       '_single_scalar_parameters',
       '_deprecate_quattroshapes',
       '_text',
@@ -98,26 +103,27 @@ module.exports.tests.sanitize = function(test, common) {
       '_flag_bool',
       '_geo_search',
       '_boundary_country',
-      '_categories'
+      '_categories',
+      '_geonames_warnings'
     ];
 
-    var req = {};
-    var res = {};
+    const req = {};
+    const res = {};
 
-    search.middleware(req, res, function(){
+    search.middleware(req, res, () => {
       t.deepEquals(called_sanitizers, expected_sanitizers);
       t.end();
     });
   });
 };
 
-module.exports.all = function (tape, common) {
+module.exports.all = (tape, common) => {
 
   function test(name, testFunction) {
-    return tape('SANTIZE /search ' + name, testFunction);
+    return tape(`SANTIZE /search ${name}`, testFunction);
   }
 
-  for( var testCase in module.exports.tests ){
+  for( const testCase in module.exports.tests ){
     module.exports.tests[testCase](test, common);
   }
 };

test/unit/schema.js

@@ -3,14 +3,6 @@
 const Joi = require('joi');
 const schema = require('../../schema');
 
-function validate(config) {
-  Joi.validate(config, schema, (err, value) => {
-    if (err) {
-      throw new Error(err.details[0].message);
-    }
-  });
-}
-
 module.exports.tests = {};
 
 module.exports.tests.completely_valid = (test, common) => {
@@ -26,19 +18,26 @@ module.exports.tests.completely_valid = (test, common) => {
         localization: {
           flipNumberAndStreetCountries: ['ABC', 'DEF']
         },
-        requestRetries: 19
+        requestRetries: 19,
+        services: {
+          placeholder: {
+            url: 'http://locahost'
+          }
+        }
       },
       esclient: {
         requestTimeout: 17
       }
     };
 
-    t.doesNotThrow(validate.bind(config));
+    const result = Joi.validate(config, schema);
+
+    t.notOk(result.error);
     t.end();
 
   });
 
-  test('basic valid configuration should not throw error', (t) => {
+  test('basic valid configuration should not throw error and have defaults set', (t) => {
     var config = {
       api: {
         version: 'version value',
@@ -50,7 +49,10 @@ module.exports.tests.completely_valid = (test, common) => {
       }
     };
 
-    t.doesNotThrow(validate.bind(config));
+    const result = Joi.validate(config, schema);
+
+    t.notOk(result.error);
+    t.deepEquals(result.value.api.services, {}, 'missing api.services should default to empty object');
     t.end();
 
   });
@@ -63,7 +65,10 @@ module.exports.tests.api_validation = (test, common) => {
       esclient: {}
     };
 
-    t.throws(validate.bind(null, config), /"api" is required/, 'api should exist');
+    const result = Joi.validate(config, schema);
+
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"api" is required');
     t.end();
 
   });
@@ -79,7 +84,9 @@ module.exports.tests.api_validation = (test, common) => {
       esclient: {}
     };
 
-    t.doesNotThrow(validate.bind(null, config), 'unknown properties should be allowed');
+    const result = Joi.validate(config, schema);
+
+    t.notOk(result.error);
     t.end();
 
   });
@@ -95,7 +102,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"version" must be a string/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"version" must be a string');
 
     });
 
@@ -114,7 +124,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"indexName" must be a string/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"indexName" must be a string');
 
     });
 
@@ -133,7 +146,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"host" must be a string/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"host" must be a string');
 
     });
 
@@ -153,7 +169,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"legacyUrl" must be a string/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"legacyUrl" must be a string');
 
     });
 
@@ -173,7 +192,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"accessLog" must be a string/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"accessLog" must be a string');
 
     });
 
@@ -193,7 +215,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"relativeScores" must be a boolean/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"relativeScores" must be a boolean');
 
     });
 
@@ -213,7 +238,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"localization" must be an object/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"localization" must be an object');
 
     });
 
@@ -234,7 +262,10 @@ module.exports.tests.api_validation = (test, common) => {
       esclient: {}
     };
 
-    t.throws(validate.bind(null, config), /"unknown_property" is not allowed/);
+    const result = Joi.validate(config, schema);
+
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"unknown_property" is not allowed');
 
     t.end();
 
@@ -254,9 +285,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(
-        validate.bind(null, config),
-        /"flipNumberAndStreetCountries" must be an array/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"flipNumberAndStreetCountries" must be an array');
 
     });
 
@@ -278,7 +310,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"0" must be a string/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"0" must be a string');
 
     });
 
@@ -300,7 +335,11 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /fails to match the required pattern/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, `"0" with value "${value}" fails to match the required pattern: /^[A-Z]{3}$/`);
+
     });
 
     t.end();
@@ -319,9 +358,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(
-        validate.bind(null, config),
-        /"requestRetries" must be a number/, 'api.requestRetries should be a number');
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"requestRetries" must be a number');
 
     });
 
@@ -340,10 +380,10 @@ module.exports.tests.api_validation = (test, common) => {
       esclient: {}
     };
 
-    t.throws(
-      validate.bind(null, config),
-      /"requestRetries" must be an integer/, 'api.requestRetries should be an integer');
+    const result = Joi.validate(config, schema);
 
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"requestRetries" must be an integer');
     t.end();
 
   });
@@ -359,10 +399,10 @@ module.exports.tests.api_validation = (test, common) => {
       esclient: {}
     };
 
-    t.throws(
-      validate.bind(null, config),
-      /"requestRetries" must be larger than or equal to 0/, 'api.requestRetries must be positive');
+    const result = Joi.validate(config, schema);
 
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"requestRetries" must be larger than or equal to 0');
     t.end();
 
   });
@@ -379,7 +419,10 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"pipService" must be a string/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"pipService" must be a string');
 
     });
 
@@ -387,19 +430,22 @@ module.exports.tests.api_validation = (test, common) => {
 
   });
 
-  test('non-URI-formatted api.pipService should throw error', (t) => {
-    ['this is not a URI'].forEach((value) => {
+  test('non-http/https api.pipService should throw error', (t) => {
+    ['ftp', 'git', 'unknown'].forEach((scheme) => {
       var config = {
         api: {
           version: 'version value',
           indexName: 'index name value',
           host: 'host value',
-          pipService: value
+          pipService: `${scheme}://localhost`
         },
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"pipService" must be a valid uri/);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"pipService" must be a valid uri with a scheme matching the https? pattern');
 
     });
 
@@ -407,8 +453,8 @@ module.exports.tests.api_validation = (test, common) => {
 
   });
 
-  test('non-http/https api.pipService should throw error', (t) => {
-    ['ftp', 'git', 'unknown'].forEach((scheme) => {
+  test('http/https api.pipService should not throw error', (t) => {
+    ['http', 'https'].forEach((scheme) => {
       var config = {
         api: {
           version: 'version value',
@@ -419,7 +465,9 @@ module.exports.tests.api_validation = (test, common) => {
         esclient: {}
       };
 
-      t.throws(validate.bind(null, config), /"pipService" must be a valid uri/);
+      const result = Joi.validate(config, schema);
+
+      t.notOk(result.error);
 
     });
 
@@ -427,19 +475,23 @@ module.exports.tests.api_validation = (test, common) => {
 
   });
 
-  test('http/https api.pipService should not throw error', (t) => {
-    ['http', 'https'].forEach((scheme) => {
+  // api.placeholderService has been moved to api.services.placeholder.url
+  test('any api.placeholderService value should be disallowed', (t) => {
+    [null, 17, {}, [], true, 'http://localhost'].forEach((value) => {
       var config = {
         api: {
           version: 'version value',
           indexName: 'index name value',
           host: 'host value',
-          pipService: `${scheme}://localhost`
+          placeholderService: value
         },
         esclient: {}
       };
 
-      t.doesNotThrow(validate.bind(null, config), `${scheme} should be allowed`);
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"placeholderService" is not allowed');
 
     });
 
@@ -449,6 +501,154 @@ module.exports.tests.api_validation = (test, common) => {
 
 };
 
+module.exports.tests.api_services_validation = (test, common) => {
+  test('unsupported children of api.services should be disallowed', (t) => {
+    var config = {
+      api: {
+        version: 'version value',
+        indexName: 'index name value',
+        host: 'host value',
+        services: {
+          unknown_property: 'value'
+        }
+      },
+      esclient: {}
+    };
+
+    const result = Joi.validate(config, schema);
+
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"unknown_property" is not allowed');
+    t.end();
+
+  });
+
+  test('non-url children of api.services.placeholder should be disallowed', (t) => {
+    var config = {
+      api: {
+        version: 'version value',
+        indexName: 'index name value',
+        host: 'host value',
+        services: {
+          placeholder: {
+            url: 'http://localhost',
+            unknown_property: 'value'
+          }
+        }
+      },
+      esclient: {}
+    };
+
+    const result = Joi.validate(config, schema);
+
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"unknown_property" is not allowed');
+    t.end();
+
+  });
+
+  test('when api.services.placeholder is defined, url is required', (t) => {
+    var config = {
+      api: {
+        version: 'version value',
+        indexName: 'index name value',
+        host: 'host value',
+        services: {
+          placeholder: {
+          }
+        }
+      },
+      esclient: {}
+    };
+
+    const result = Joi.validate(config, schema);
+
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"url" is required');
+    t.end();
+
+  });
+
+  test('non-string api.services.placeholder.url should throw error', (t) => {
+    [null, 17, {}, [], true].forEach((value) => {
+      var config = {
+        api: {
+          version: 'version value',
+          indexName: 'index name value',
+          host: 'host value',
+          services: {
+            placeholder: {
+              url: value
+            }
+          }
+        },
+        esclient: {}
+      };
+
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"url" must be a string');
+
+    });
+
+    t.end();
+
+  });
+
+  test('non-http/https api.services.placeholder.url should throw error', (t) => {
+    ['ftp', 'git', 'unknown'].forEach((scheme) => {
+      var config = {
+        api: {
+          version: 'version value',
+          indexName: 'index name value',
+          host: 'host value',
+          services: {
+            placeholder: {
+              url: `${scheme}://localhost`
+            }
+          }
+        },
+        esclient: {}
+      };
+
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"url" must be a valid uri with a scheme matching the https\? pattern');
+
+    });
+
+    t.end();
+
+  });
+
+  test('non-url children of api.services.placeholder should be disallowed', (t) => {
+    var config = {
+      api: {
+        version: 'version value',
+        indexName: 'index name value',
+        host: 'host value',
+        services: {
+          placeholder: {
+            url: 'http://localhost',
+            unknown_property: 'value'
+          }
+        }
+      },
+      esclient: {}
+    };
+
+    const result = Joi.validate(config, schema);
+
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"unknown_property" is not allowed');
+    t.end();
+
+  });
+
+};
+
 module.exports.tests.esclient_validation = (test, common) => {
   test('config without esclient should throw error', (t) => {
     var config = {
@@ -459,9 +659,10 @@ module.exports.tests.esclient_validation = (test, common) => {
       }
     };
 
-    t.throws(
-      validate.bind(null, config),
-      /"esclient" is required/, 'esclient should exist');
+    const result = Joi.validate(config, schema);
+
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"esclient" is required');
     t.end();
 
   });
@@ -477,9 +678,10 @@ module.exports.tests.esclient_validation = (test, common) => {
         esclient: value
       };
 
-      t.throws(
-        validate.bind(null, config),
-        /"esclient" must be an object/, 'esclient should be an object');
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"esclient" must be an object');
 
     });
 
@@ -500,9 +702,10 @@ module.exports.tests.esclient_validation = (test, common) => {
         }
       };
 
-      t.throws(
-        validate.bind(null, config),
-        /"requestTimeout" must be a number/, 'esclient.requestTimeout should be a number');
+      const result = Joi.validate(config, schema);
+
+      t.equals(result.error.details.length, 1);
+      t.equals(result.error.details[0].message, '"requestTimeout" must be a number');
 
     });
 
@@ -522,10 +725,10 @@ module.exports.tests.esclient_validation = (test, common) => {
       }
     };
 
-    t.throws(
-      validate.bind(null, config),
-    /"requestTimeout" must be an integer/, 'esclient.requestTimeout should be an integer');
+    const result = Joi.validate(config, schema);
 
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"requestTimeout" must be an integer');
     t.end();
 
   });
@@ -542,10 +745,10 @@ module.exports.tests.esclient_validation = (test, common) => {
       }
     };
 
-    t.throws(
-      validate.bind(null, config),
-      /"requestTimeout" must be larger than or equal to 0/, 'esclient.requestTimeout must be positive');
+    const result = Joi.validate(config, schema);
 
+    t.equals(result.error.details.length, 1);
+    t.equals(result.error.details[0].message, '"requestTimeout" must be larger than or equal to 0');
     t.end();
 
   });

test/unit/service/configurations/PlaceHolder.js

@@ -0,0 +1,139 @@
+module.exports.tests = {};
+
+const PlaceHolder = require('../../../../service/configurations/PlaceHolder');
+
+module.exports.tests.all = (test, common) => {
+  test('getName should return \'placeholder\'', (t) => {
+    const configBlob = {
+      url: 'http://localhost:1234',
+      timeout: 17,
+      retries: 19
+    };
+
+    const placeholder = new PlaceHolder(configBlob);
+
+    t.equals(placeholder.getName(), 'placeholder');
+    t.equals(placeholder.getBaseUrl(), 'http://localhost:1234/');
+    t.equals(placeholder.getTimeout(), 17);
+    t.equals(placeholder.getRetries(), 19);
+    t.end();
+
+  });
+
+  test('getUrl should return value passed to constructor', (t) => {
+    const configBlob = {
+      url: 'http://localhost:1234',
+      timeout: 17,
+      retries: 19
+    };
+
+    const placeholder = new PlaceHolder(configBlob);
+
+    t.equals(placeholder.getUrl(), 'http://localhost:1234/search');
+    t.end();
+
+  });
+
+  test('getParameters should return object with text and lang from req', (t) => {
+    const configBlob = {
+      url: 'http://localhost:1234',
+      timeout: 17,
+      retries: 19
+    };
+
+    const placeholder = new PlaceHolder(configBlob);
+
+    const req = {
+      clean: {
+        text: 'text value',
+        lang: {
+          iso6393: 'lang value'
+        }
+      }
+    };
+
+    t.deepEquals(placeholder.getParameters(req), { text: 'text value', lang: 'lang value' });
+    t.end();
+
+  });
+
+  test('getHeaders should return empty object', (t) => {
+    const configBlob = {
+      url: 'base url',
+      timeout: 17,
+      retries: 19
+    };
+
+    const placeholder = new PlaceHolder(configBlob);
+
+    t.deepEquals(placeholder.getHeaders(), {});
+    t.end();
+
+  });
+
+  test('getParameters should not include lang if req.clean.lang is unavailable', (t) => {
+    const configBlob = {
+      url: 'base url',
+      timeout: 17,
+      retries: 19
+    };
+
+    const placeholder = new PlaceHolder(configBlob);
+
+    const req = {
+      clean: {
+        text: 'text value'
+      }
+    };
+
+    t.deepEquals(placeholder.getParameters(req), { text: 'text value' });
+    t.end();
+
+  });
+
+  test('getParameters should not include lang if req.clean.lang.iso6393 is unavailable', (t) => {
+    const configBlob = {
+      url: 'base url',
+      timeout: 17,
+      retries: 19
+    };
+
+    const placeholder = new PlaceHolder(configBlob);
+
+    const req = {
+      clean: {
+        text: 'text value',
+        lang: {}
+      }
+    };
+
+    t.deepEquals(placeholder.getParameters(req), { text: 'text value' });
+    t.end();
+
+  });
+
+  test('baseUrl ending in / should not have double /\'s return by getUrl', (t) => {
+    const configBlob = {
+      url: 'http://localhost:1234/blah',
+      timeout: 17,
+      retries: 19
+    };
+
+    const placeholder = new PlaceHolder(configBlob);
+
+    t.deepEquals(placeholder.getUrl(), 'http://localhost:1234/blah/search');
+    t.end();
+
+  });
+
+};
+
+module.exports.all = (tape, common) => {
+  function test(name, testFunction) {
+    return tape(`SERVICE CONFIGURATION /PlaceHolder ${name}`, testFunction);
+  }
+
+  for( var testCase in module.exports.tests ){
+    module.exports.tests[testCase](test, common);
+  }
+};