Browse Source

Merge pull request #17 from pelias/imageOrganization

Organizing the repository & clearing out the cruft.
pull/9/merge
David Riordan 9 years ago
parent
commit
7832b6e7f7
  1. 2
      .gitignore
  2. 0
      000-getting-started.md
  3. 0
      001-api.md
  4. 12
      002-search.md
  5. 0
      003-autocomplete.md
  6. 0
      004-reverse.md
  7. 0
      005-place.md
  8. 0
      006-response.md
  9. 0
      007-data-sources.md
  10. 0
      007-using-cors.md
  11. 0
      008-transition-from-beta.md
  12. 0
      images/boundary_london.png
  13. 0
      images/focus_point.png
  14. 0
      images/overlapping_boundaries.gif
  15. 0
      images/world_all.png
  16. 0
      images/world_circle.png
  17. 0
      images/world_country.png
  18. 0
      images/world_rect.png
  19. 3
      index.md
  20. 0
      swagger-docs/definitions.md
  21. 24
      swagger-docs/overview.md
  22. 122
      swagger-docs/paths.md
  23. 355
      swagger-docs/pelias-v1-api-swagger.yml
  24. 63
      tools/locmux.js
  25. 17
      tools/package.json

2
.gitignore vendored

@ -1,3 +1,3 @@
node_modules
npm-debug.log
.DS_Store

0
getting-started/000-getting-started.md → 000-getting-started.md

0
getting-started/001-api.md → 001-api.md

12
getting-started/002-search.md → 002-search.md

@ -17,7 +17,7 @@ All Mapzen Search requests share the same format:
## Search the world
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_all.png)
![](/getting-started/images/world_all.png)
In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To accomplish this, build a query where the `text` parameter is set to the item you want to find.
@ -61,7 +61,7 @@ If you are looking for places in a particular region, or country, or only want t
### Search within a particular country
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_country.png)
![](/getting-started/images/world_country.png)
Sometimes your work might require that all the search results be from a particular country. To do this, you can set the `boundary.country` parameter value to the alpha-2 or alpha-3 [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1).
@ -107,7 +107,7 @@ Results in the United States:
### Search within a rectangular region
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_rect.png)
![](/getting-started/images/world_rect.png)
To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the mininum and the maximum latitude, longitude).
@ -139,7 +139,7 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary
### Search within a circular region
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_circle.png)
![](/getting-started/images/world_circle.png)
Sometimes you don't have a rectangle to work with, but rather you have a point on earth—for example, your location coordinates—and a maximum distance within which acceptable results can be located.
@ -168,14 +168,14 @@ You can see the results have fewer than the standard 10 items because there are
If you're going to attempt using multiple boundary types in a single search request, be aware that the results will come from the intersection of all the boundaries. So if you provide regions that don't overlap, you'll be looking at an empty set of results. You've been warned. Here's an image of how it works:
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/overlapping_boundaries.gif)
![](/getting-started/images/overlapping_boundaries.gif)
## Prioritize results by proximity
Many use cases call for the ability to promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. Mapzen Search allows you to prioritize results within geographic boundaries, including around a point, within a country, or within a region.
### Prioritize around a point
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/focus_point.png)
![](/getting-started/images/focus_point.png)
By specifying a `focus.point`, nearby places will be scored higher depending on how close they are to the `focus.point` so that places with higher scores will appear higher in the results list. The effect of this scoring boost diminishes to zero after 100 kilometers away from the `focus.point`. After all the nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization.

0
getting-started/003-autocomplete.md → 003-autocomplete.md

0
getting-started/004-reverse.md → 004-reverse.md

0
getting-started/005-place.md → 005-place.md

0
getting-started/006-response.md → 006-response.md

0
getting-started/007-data-sources.md → 007-data-sources.md

0
getting-started/007-using-cors.md → 007-using-cors.md

0
transition.md → 008-transition-from-beta.md

0
getting-started/boundary_london.png → images/boundary_london.png

Before

Width:  |  Height:  |  Size: 120 KiB

After

Width:  |  Height:  |  Size: 120 KiB

0
getting-started/focus_point.png → images/focus_point.png

Before

Width:  |  Height:  |  Size: 255 KiB

After

Width:  |  Height:  |  Size: 255 KiB

0
getting-started/overlapping_boundaries.gif → images/overlapping_boundaries.gif

Before

Width:  |  Height:  |  Size: 2.1 MiB

After

Width:  |  Height:  |  Size: 2.1 MiB

0
getting-started/world_all.png → images/world_all.png

Before

Width:  |  Height:  |  Size: 359 KiB

After

Width:  |  Height:  |  Size: 359 KiB

0
getting-started/world_circle.png → images/world_circle.png

Before

Width:  |  Height:  |  Size: 372 KiB

After

Width:  |  Height:  |  Size: 372 KiB

0
getting-started/world_country.png → images/world_country.png

Before

Width:  |  Height:  |  Size: 364 KiB

After

Width:  |  Height:  |  Size: 364 KiB

0
getting-started/world_rect.png → images/world_rect.png

Before

Width:  |  Height:  |  Size: 373 KiB

After

Width:  |  Height:  |  Size: 373 KiB

3
index.md

@ -3,8 +3,7 @@ Mapzen Search Documentation V1
Geocoding service powered by [Pelias](https://github.com/pelias/pelias) and open data
_____________________________________________________________________________________
These pages offer an introduction to the API and terminology used in Mapzen Search and the accompanying experimental open source geocoder, Pelias which powers it.
These pages offer an introduction to the API and terminology used in Mapzen Search and the accompanying open source geocoder which powers it, Pelias.
- Getting Started
- API Specification
- Transitioning From Beta to 1.0

0
swagger-docs/definitions.md

24
swagger-docs/overview.md

@ -1,24 +0,0 @@
# Mapzen Search API
## Overview
Searching the world with the Mapzen Search API, powered by [Pelias](https://github.com/pelias/pelias).
----------
Pelias is an experimental, open geocoder from [Mapzen](https://mapzen.com). It's built from the ground up as an open source and open data-friendly geocoder that's designed to operate on top of any new
This documentation refers specifically to Mapzen Search (//TODO: do we want to call this Mapzen Place Search?), powered by Pelias, but is mirrored in the API of the [Pelias code](https://github.com/pelias/pelias).
### Version information
Version: 1.0.0
### URI scheme
Host: pelias.mapzen.com
BasePath: /v1
Schemes: HTTP, HTTPS
### Produces
* application/vnd.geo+json

122
swagger-docs/paths.md

@ -1,122 +0,0 @@
## Paths
### Fast response endpoint to provide an end-user suggestions of matching places as they're typing the search string. Returns 10 matching places. Intended for use while the user is typing a response. For searching a complete query (if autocomplete doesn't deliver a match), use the /search endpoint.
```
GET /autocomplete
```
#### Parameters
|Type|Name|Description|Required|Schema|Default|
|----|----|----|----|----|----|
|QueryParameter|text|User's search string|true|string (string)||
|QueryParameter|focus.point.lon|Focal point longitude. Ideally a user's device location, but can also be a focal point (like the center of their view). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.|false|number (float)||
|QueryParameter|focus.point.lat|Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.|false|number (float)||
#### Responses
|HTTP Code|Description|Schema|
|----|----|----|
|200|A GeoJSON FeatureCollection array of geocoded places.|No Content|
|400|Invalid request. Check that you are passing along valid parameters without conflicting options.|No Content|
#### Tags
* search
* forward geocoding
### Retrieves the full GeoJSON record for a given place. ID determined from the results of a `/search`, `/autocomplete`, or `/reverse` response.
```
GET /place
```
#### Parameters
|Type|Name|Description|Required|Schema|Default|
|----|----|----|----|----|----|
|QueryParameter|ids|Place ID from Mapzen Search.|false|string (string)||
#### Responses
|HTTP Code|Description|Schema|
|----|----|----|
|200|ok|No Content|
### Takes the coordinates of a location and searches for the name or address of the place it's from.
```
GET /reverse
```
#### Parameters
|Type|Name|Description|Required|Schema|Default|
|----|----|----|----|----|----|
|QueryParameter|point.lon||true| (float)||
|QueryParameter|point.lat||true| (float)||
|QueryParameter|boundary.circle.lon||false|number (float)||
|QueryParameter|boundary.circle.lat||false|number (float)||
|QueryParameter|boundary.circle.radius|bounding circle radius (in KM).|false|number (float)||
|QueryParameter|boundary.country|Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.|false|string (string)||
|QueryParameter|layer||false|||
#### Responses
|HTTP Code|Description|Schema|
|----|----|----|
|200|All Good.|No Content|
### Geocodes a user's search query
```
GET /search
```
#### Parameters
|Type|Name|Description|Required|Schema|Default|
|----|----|----|----|----|----|
|QueryParameter|text|User's search string|true|string (string)||
|QueryParameter|focus.point.lon|Focal point longitude. Ideally a user's device location, but can also be a focal point. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.|false|number (float)||
|QueryParameter|focus.point.lat|Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.|false|number (float)||
|QueryParameter|focus.viewport.min_lon|`focus.viewport` provides focus to user's viewable map area, using the viewable screen to calibrate results relevant for an end-user's area of interest based on what's on screen, where that is located, and the level of zoom.
This parameter limits the user's viewport latitude (furthest bottom coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
Accepts only WGS84 longitudes.
|false|number (float)||
|QueryParameter|focus.viewport.min_lat|This parameter limits the user's viewport longitude (furthest left coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
Accepts only WGS84 latitudes.
|false|number (float)||
|QueryParameter|focus.viewport.max_lon|This parameter limits the user's viewport latitude (furthest right coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
Accepts only WGS84 longitudes.
|false|number (float)||
|QueryParameter|focus.viewport.max_lat|This parameter limits the user's viewport longitude (furthest top coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
Accepts only WGS84 latitudes.
|false|number (float)||
|QueryParameter|layers|For more than one layer, accepts a comma separated list of valid layers. If any of those layers is invalid, the request will still be honored, but a warning will be thrown in the `geocoding` block of the response.
|false|string (string)||
|QueryParameter|sources|tk|false|string||
|QueryParameter|boundary.circle.lon|tk|false|number (float)||
|QueryParameter|boundary.circle.lat|tk|false|number (float)||
|QueryParameter|boundary.circle.radius|Maximum distance in meters from the centroid to search from. Forms the radius of a bounding circle.|false|number (float)||
|QueryParameter|boundary.rect.min_lon||false|number (float)||
|QueryParameter|boundary.rect.min_lat||false|number (float)||
|QueryParameter|boundary.rect.max_lon||false|number (float)||
|QueryParameter|boundary.rect.max_lat||false|number (float)||
|QueryParameter|boundary.country|Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.
|false|string (string)||
|QueryParameter|size|Maximum number of possible matching places to be returned|false|integer (int32)|10|
|QueryParameter|private|Option to disable query logging in Mapzen Search. Defaults to False.|false|boolean|false|
#### Responses
|HTTP Code|Description|Schema|
|----|----|----|
|200|a GeoJSON FeatureCollection array of geocoded places|No Content|
|400|invalid request. Check that you are passing along valid parameters|No Content|
|403|invalid API key. Register for a valid API key at the [Mapzen Developer Portal](https://mapzen.com/developer).|No Content|
#### Tags
* forward geocoding
* search

355
swagger-docs/pelias-v1-api-swagger.yml

@ -1,355 +0,0 @@
swagger: '2.0'
################################################################################
# API Information #
################################################################################
info:
title: Mapzen Search API
description: |
Searching the world with the Mapzen Search API, powered by [Pelias](https://github.com/pelias/pelias).
----------
Pelias is an experimental, open geocoder from [Mapzen](https://mapzen.com). It's built from the ground up as an open source and open data-friendly geocoder that's designed to operate on top of any new
This documentation refers specifically to Mapzen Search (//TODO: do we want to call this Mapzen Place Search?), powered by Pelias, but is mirrored in the API of the [Pelias code](https://github.com/pelias/pelias).
version: "1.0.0"
# the domain of the service
host: pelias.mapzen.com
# array of all schemes that your API supports
schemes:
- http
- https
# will be prefixed to all paths
basePath: /v1
produces:
- application/vnd.geo+json
################################################################################
# Security #
################################################################################
securityDefinitions:
api_key:
type: apiKey
name: api_key
in: query
description: |
Use of Mapzen Search service requires an API key. Register for a free API key at the [MapzenDeveloper Portal](https://mapzen.com/developer).
We have generous rate limits (30,000 requests/day, 3 requests/second), and if you require more capacity, you can [run Pelias](https://github.com/pelias/vagrant) on your own servers, or [get in touch](mailto:pelias@mapzen.com) with the team at Mapzen.
Use of the Mapzen Place Search API uses API tokens as part of the URL parameters like:
<code>
https://pelias.mapzen.com/v1/search?text=New York City&api_key=pelias-prod-xxxxxx</code>
By clicking the Authenticate button above, you can paste your API Key in from the [Mapzen Developer Portal](https://mapzen.com/developer),
security:
- api_key: []
################################################################################
# API Calls #
################################################################################
paths:
/search:
get:
tags:
- forward geocoding
- search
summary: Geocodes a user's search query
parameters:
- name: text
in: query
description: User's search string
required: true
type: string
format: string
- name: focus.point.lon
in: query
description: Focal point longitude. Ideally a user's device location, but can also be a focal point. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.
required: false
type: number
format: float
- name: focus.point.lat
in: query
description: Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.
required: false
type: number
format: float
- name: focus.viewport.min_lon
in: query
description: |
`focus.viewport` provides focus to user's viewable map area, using the viewable screen to calibrate results relevant for an end-user's area of interest based on what's on screen, where that is located, and the level of zoom.
This parameter limits the user's viewport latitude (furthest bottom coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
Accepts only WGS84 longitudes.
required: false
type: number
format: float
- name: focus.viewport.min_lat
in: query
description: |
This parameter limits the user's viewport longitude (furthest left coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
Accepts only WGS84 latitudes.
required: false
type: number
format: float
- name: focus.viewport.max_lon
in: query
description: |
This parameter limits the user's viewport latitude (furthest right coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
Accepts only WGS84 longitudes.
required: false
type: number
format: float
- name: focus.viewport.max_lat
in: query
description: |
This parameter limits the user's viewport longitude (furthest top coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
Accepts only WGS84 latitudes.
required: false
type: number
format: float
- name: layers
in: query
type: string
format: string
description: |
For more than one layer, accepts a comma separated list of valid layers. If any of those layers is invalid, the request will still be honored, but a warning will be thrown in the `geocoding` block of the response.
required: false
collectionFormat: csv
- name: sources
in: query
required: false
type: string
collectionFormat: csv
description: tk
# BOUNDARY CIRCLE
- name: boundary.circle.lon
in: query
required: false
type: number
format: float
description: tk
minimum: -180.0
maximum: 180.0
- name: boundary.circle.lat
in: query
required: false
type: number
format: float
description: tk
minimum: -90
maximum: 90
- name: boundary.circle.radius
in: query
required: false
type: number
format: float
description: Maximum distance in meters from the centroid to search from. Forms the radius of a bounding circle.
# BOUNDARY RECTANGLE
- name: boundary.rect.min_lon
in: query
type: number
format: float
- name: boundary.rect.min_lat
in: query
type: number
format: float
- name: boundary.rect.max_lon
in: query
type: number
format: float
- name: boundary.rect.max_lat
in: query
type: number
format: float
- name: boundary.country
in: query
format: string
type: string
description: |
Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.
- name: size
in: query
type: integer
format: int32
minimum: 1
maximum: 50
default: 10
required: false
description: Maximum number of possible matching places to be returned
## VIEW NOT BEING IMPLEMENTED AT THIS TIME
# - name: view
# in: query
# type: string
# default: "standard"
# enum:
# - "standard"
# - "mobile"
- name: private
in: query
type: boolean
default: false
required: false
description: Option to disable query logging in Mapzen Search. Defaults to False.
security:
- api_key: []
responses:
200:
description: a GeoJSON FeatureCollection array of geocoded places
400:
description: invalid request. Check that you are passing along valid parameters
403:
description: invalid API key. Register for a valid API key at the [Mapzen Developer Portal](https://mapzen.com/developer).
/autocomplete:
get:
summary: Fast response endpoint to provide an end-user suggestions of matching places as they're typing the search string. Returns 10 matching places. Intended for use while the user is typing a response. For searching a complete query (if autocomplete doesn't deliver a match), use the /search endpoint.
tags: [search, forward geocoding]
parameters:
- name: text
in: query
description: User's search string
required: true
type: string
format: string
- name: focus.point.lon
in: query
description: Focal point longitude. Ideally a user's device location, but can also be a focal point (like the center of their view). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.
required: false
type: number
format: float
- name: focus.point.lat
in: query
description: Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.
required: false
type: number
format: float
security:
- api_key: []
responses:
200:
description: A GeoJSON FeatureCollection array of geocoded places.
400:
description: Invalid request. Check that you are passing along valid parameters without conflicting options.
/reverse:
get:
summary: Takes the coordinates of a location and searches for the name or address of the place it's from.
parameters:
- name: point.lon
in: query
format: float
required: true
min: -180
max: 180
- name: point.lat
in: query
format: float
required: true
min: -90
max: 90
- name: boundary.circle.lon
in: query
type: number
format: float
required: false
min: -180
max: 180
- name: boundary.circle.lat
in: query
type: number
format: float
required: false
min: -90
max: 180
- name: boundary.circle.radius
in: query
type: number
format: float
required: false
description: bounding circle radius (in KM).
- name: boundary.country
in: query
type: string
format: string
required: false
description: Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.
- name: layer
in: query
responses:
200:
description: All Good.
security:
- api_key: []
/place:
get:
summary: Retrieves the full GeoJSON record for a given place. ID determined from the results of a `/search`, `/autocomplete`, or `/reverse` response.
parameters:
- name: ids
in: query
format: string
type: string
description: Place ID from Mapzen Search.
responses:
200:
description: ok
security:
- api_key: []
################################################################################
# Definitions #
################################################################################

63
tools/locmux.js

@ -1,63 +0,0 @@
/**
* To run do as follows:
*
* $ npm install request
* $ node locmux.js 'text i want to search for'
*
* If you'd like more locations to be searched just add them to the list below.
*
*/
var request = require('request');
var colors = require('text-hex');
var async = require('async');
var locations = [
{
name: 'London',
lat: 51.507222,
lon: -0.1275
},
{
name: 'New York',
lat: 37.783333,
lon: -122.416667
}
];
var text = process.argv[2];
var geojsonio = true; //process.argv[2] === 'geojson';
var geojson = {
type: 'FeatureCollection',
features: []
};
async.forEach(locations, function (loc, cb) {
request.get('http://pelias.bigdev.mapzen.com/v1/search?text=' + text +
'&focus.point.lat=' + loc.lat + '&focus.point.lon=' + loc.lon, function (err, res) {
var results = JSON.parse(res.body);
if (!geojsonio) {
console.log('\n\n\nSearching for "' + text + '" near ' + loc.name);
console.log('> result count:', results.features.length);
}
results.features.forEach(function (feature) {
feature.properties['marker-color'] = colors(loc.name);
feature.properties.query = loc.name;
geojson.features.push(feature);
if (!geojsonio) {
console.log(feature.properties.label);
}
});
cb();
});
},
function () {
if (geojsonio) {
console.log(JSON.stringify(geojson));
}
});

17
tools/package.json

@ -1,17 +0,0 @@
{
"name": "tools",
"version": "1.0.0",
"description": "",
"main": "locmux.js",
"scripts": {
"start": "node locmux.js geojson"
},
"author": "Diana Shkolnikov <dianashk@gmail.com>",
"license": "MIT",
"dependencies": {
"async": "^1.4.2",
"geojsonio-cli": "^0.1.2",
"request": "^2.62.0",
"text-hex": "0.0.0"
}
}
Loading…
Cancel
Save