mirror of https://github.com/pelias/api.git
Diana Shkolnikov
9 years ago
19 changed files with 316 additions and 395 deletions
@ -1,100 +1 @@
|
||||
## /search |
||||
|
||||
The full text search endpoint that matches the name of a place to points on the planet. |
||||
|
||||
#### Required Parameters |
||||
* `text`: the string to search for (eg `new york city` or `london`) |
||||
|
||||
#### Optional Parameters |
||||
* `lat`, `lon`: the latitude/longitude coordinates to bias search results towards (may increase relevancy) |
||||
* `size` (default: `10`): the number of results to return |
||||
* `layers` (default: `poi,admin,address`): the comma-separated names of datasets you wish to query. Valid values are: |
||||
* aliases for multiple datasets like `poi`, `admin` or `address` |
||||
* `poi` expands internally to `geoname`, `osmnode`, `osmway` |
||||
* `admin` expands to `admin0`, `admin1`, `admin2`, `neighborhood`, `locality`, `local_admin` |
||||
* `address` expands to `osmaddress`, `openaddresses` |
||||
* the name of one particular dataset, like `geoname` or `osmaddress` |
||||
* `bbox`: the bounding box from which you want all your results to come |
||||
* can be one of the following comma separated string values |
||||
* "southwest_lng,southwest_lat,northeast_lng,northeast_lat" `L.latLngBounds(southwestLatLng, northeastLatLng).toBBoxString()` |
||||
* bottom left lon, bottom left lat, top right lon, top right lat |
||||
* left, bottom, right, top |
||||
* min longitude, min latitude, max longitude, max latitude |
||||
* `details` (default: `true`): indicates if results should contain detailed. Valid values: |
||||
* `false`: results will only contain `id`, `layer`, and `text` properties |
||||
* `true`: all available properties will be included in results |
||||
|
||||
|
||||
## /search/coarse |
||||
|
||||
Like the `/search` endpoint, but performs a "coarse" search, meaning that it only searches administrative regions |
||||
(countries, states, counties, neighborhoods, etc.). |
||||
|
||||
#### Required Parameters |
||||
Same as `/search`. |
||||
|
||||
#### Optional Parameters |
||||
Same as `/search`. |
||||
|
||||
## /suggest |
||||
|
||||
The autocompletion endpoint that offers very fast response times; ideal for completing partial user input. Mixes |
||||
results from around the provided lat/lon coordinates and also from precision level 1 and 3. |
||||
|
||||
#### Required Parameters |
||||
* `text`: query string |
||||
* `lat`, `lon`: The latitude/longitude coordinates to bias results towards. |
||||
* `lat`/`lon` are currently **required** because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444) |
||||
|
||||
#### Optional Parameters |
||||
* `size` (default: `10`): number of results requested |
||||
* `layers` (default: `poi,admin,address`): datasets you wish to query |
||||
* `details` (default: `true`) |
||||
|
||||
## /suggest/coarse |
||||
|
||||
Only queries the admin layers. |
||||
|
||||
#### Required Parameters |
||||
Same as `/suggest`. |
||||
|
||||
#### Optional Parameters |
||||
Same as `/suggest`. |
||||
|
||||
|
||||
## /suggest/nearby |
||||
|
||||
Works as autocomplete for only the places located near a latitude/longitude; this endpoint is the same as `/suggest` |
||||
but the results are all from within 50 kilometers of the specified point. Unlike `/suggest`, `/suggest/nearby` does |
||||
not mix results from different precision levels (500km, 1000km etc from lat/lon). |
||||
|
||||
#### Required Parameters |
||||
Same as `/suggest`. |
||||
|
||||
#### Optional Parameters |
||||
Same as `/suggest`. |
||||
|
||||
## /reverse |
||||
|
||||
The reverse geocoding endpoint; matches a point on the planet to the name of that place. |
||||
|
||||
#### Required Parameters |
||||
* `lat`, `lon`: The coordinates of the point. |
||||
|
||||
#### Optional Parameters |
||||
* `layers` (default: `poi,admin,address`) |
||||
* `details` (default: `true`) |
||||
|
||||
|
||||
## /place |
||||
|
||||
The endpoint for retrieving one or more places with specific ids. These correspond |
||||
directly with Elasticsearch documents. |
||||
|
||||
#### Required Parameters |
||||
* one of `id` or `ids` |
||||
* `id`: |
||||
* unique id of the places to be retrieved |
||||
* should be in the form of type:id, for example: `geoname:4163334` |
||||
* `ids`: |
||||
* if multiple places are to be fetched in bulk, an array of ids |
||||
## DETAILED DOCUMENTATION COMING SOON! |
||||
@ -0,0 +1,50 @@
|
||||
var _ = require('lodash'); |
||||
|
||||
/** |
||||
* Returns sanitizer function for boolean flag parameters |
||||
* |
||||
* @param {string} paramName name of parameter being sanitized |
||||
* @param {boolean} defaultValue value to set variable to if none specified |
||||
* @returns {Function} |
||||
*/ |
||||
function setup( paramName, defaultValue ) { |
||||
return function( raw, clean ){ |
||||
return sanitize( raw, clean, { |
||||
paramName: paramName, |
||||
defaultValue: defaultValue |
||||
}); |
||||
}; |
||||
} |
||||
|
||||
/** |
||||
* Validate inputs, convert types and apply defaults |
||||
* |
||||
* @param {object} raw |
||||
* @param {object} clean |
||||
* @param {object} opts |
||||
* @returns {{errors: Array, warnings: Array}} |
||||
*/ |
||||
function sanitize( raw, clean, opts ){ |
||||
|
||||
// error & warning messages`1
|
||||
var messages = { errors: [], warnings: [] }; |
||||
|
||||
if( !_.isUndefined( raw[opts.paramName] ) ){ |
||||
clean[opts.paramName] = isTruthy( raw[opts.paramName] ); |
||||
} |
||||
else { |
||||
clean[opts.paramName] = opts.defaultValue; |
||||
} |
||||
return messages; |
||||
} |
||||
|
||||
/** |
||||
* Determine if param value is "truthy" |
||||
* @param {*} val |
||||
* @returns {boolean} |
||||
*/ |
||||
function isTruthy(val) { |
||||
return _.contains( ['true', '1', 1, true], val ); |
||||
} |
||||
|
||||
module.exports = setup; |
||||
@ -0,0 +1,64 @@
|
||||
var sanitizer = require('../../../sanitiser/_flag_bool'); |
||||
var sanitize = sanitizer('dirty_param', true); |
||||
|
||||
module.exports.tests = {}; |
||||
|
||||
module.exports.tests.sanitize_private = function(test, common) { |
||||
var invalid_values = [null, -1, 123, NaN, 'abc']; |
||||
invalid_values.forEach(function (value) { |
||||
test('invalid dirty_param ' + value, function (t) { |
||||
var raw = {dirty_param: value}; |
||||
var clean = {}; |
||||
sanitize(raw, clean); |
||||
t.equal(clean.dirty_param, false, 'default clean value set (to false)'); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
|
||||
var valid_values = ['true', true, 1, '1']; |
||||
valid_values.forEach(function (value) { |
||||
test('valid dirty_param ' + value, function (t) { |
||||
var raw = {dirty_param: value}; |
||||
var clean = {}; |
||||
sanitize(raw, clean); |
||||
t.equal(clean.dirty_param, true, 'clean value set to true'); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
|
||||
var valid_false_values = ['false', false, 0, '0']; |
||||
valid_false_values.forEach(function (value) { |
||||
test('test setting false explicitly ' + value, function (t) { |
||||
var raw = {dirty_param: value}; |
||||
var clean = {}; |
||||
sanitize(raw, clean); |
||||
t.equal(clean.dirty_param, false, 'clean value set to false'); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
}; |
||||
|
||||
module.exports.tests.validate_default_behavior = function(test, common) { |
||||
var default_values = [true, false, 'foo']; |
||||
default_values.forEach(function (defaultValue) { |
||||
test('test default behavior: ' + defaultValue, function (t) { |
||||
var sanitize_true = sanitizer('foo_bar', defaultValue); |
||||
var raw = {}; |
||||
var clean = {}; |
||||
sanitize_true(raw, clean); |
||||
t.equal(clean.foo_bar, defaultValue, 'foo_bar set to ' + defaultValue); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
}; |
||||
|
||||
module.exports.all = function (tape, common) { |
||||
|
||||
function test(name, testFunction) { |
||||
return tape('SANTIZE _flag_bool: ' + name, testFunction); |
||||
} |
||||
|
||||
for( var testCase in module.exports.tests ){ |
||||
module.exports.tests[testCase](test, common); |
||||
} |
||||
}; |
||||
@ -0,0 +1,53 @@
|
||||
var sanitize = require('../../../sanitiser/_private'); |
||||
|
||||
module.exports.tests = {}; |
||||
|
||||
module.exports.tests.sanitize_private = function(test, common) { |
||||
var invalid_values = [null, -1, 123, NaN, 'abc']; |
||||
invalid_values.forEach(function(privateValue) { |
||||
test('invalid private param ' + privateValue, function(t) { |
||||
var req = {query: { private: privateValue }}; |
||||
sanitize(req); |
||||
t.equal(req.clean.private, false, 'default private set (to false)'); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
|
||||
var valid_values = ['true', true, 1, '1', 'yes', 'y']; |
||||
valid_values.forEach(function(privateValue) { |
||||
test('valid private param ' + privateValue, function(t) { |
||||
var req = {query: { private: privateValue }}; |
||||
sanitize(req); |
||||
t.equal(req.clean.private, true, 'private set to true'); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
|
||||
var valid_false_values = ['false', false, 0, '0', 'no', 'n']; |
||||
valid_false_values.forEach(function(privateValue) { |
||||
test('test setting false explicitly ' + privateValue, function(t) { |
||||
var req = {query: { private: privateValue }}; |
||||
sanitize(req); |
||||
t.equal(req.clean.private, false, 'private set to false'); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
|
||||
test('test default behavior', function(t) { |
||||
var req = {query: {}}; |
||||
sanitize(req); |
||||
t.equal(req.clean.private, true, 'private set to true'); |
||||
t.end(); |
||||
}); |
||||
}; |
||||
|
||||
module.exports.all = function (tape, common) { |
||||
|
||||
function test(name, testFunction) { |
||||
return tape('SANTIZE _private ' + name, testFunction); |
||||
} |
||||
|
||||
for( var testCase in module.exports.tests ){ |
||||
module.exports.tests[testCase](test, common); |
||||
} |
||||
}; |
||||
@ -0,0 +1,31 @@
|
||||
var isTruthy = require('../../../sanitiser/_truthy'); |
||||
|
||||
module.exports.tests = {}; |
||||
|
||||
module.exports.tests.sanitize_truthy = function(test, common) { |
||||
var valid_values = ['true', true, 1, '1', 'yes', 'y']; |
||||
valid_values.forEach(function(value) { |
||||
test('truthy value ' + value, function(t) { |
||||
t.equal(isTruthy(value), true, 'returns true'); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
|
||||
var valid_false_values = ['false', false, 0, '0', 'no', 'n', null, -1, 123, NaN, 'abc']; |
||||
valid_false_values.forEach(function(value) { |
||||
test('falsey value ' + value, function(t) { |
||||
t.equal(isTruthy(value), false, 'returns false'); |
||||
t.end(); |
||||
}); |
||||
}); |
||||
}; |
||||
|
||||
module.exports.all = function (tape, common) { |
||||
function test(name, testFunction) { |
||||
return tape('SANTIZE _truthy ' + name, testFunction); |
||||
} |
||||
|
||||
for( var testCase in module.exports.tests ){ |
||||
module.exports.tests[testCase](test, common); |
||||
} |
||||
}; |
||||
Loading…
Reference in new issue