Browse Source

📎 Merge remote-tracking branch 'origin/master' into finishing-getting-started

pull/15/head
Riordan 9 years ago
parent
commit
7cd79a64b5
  1. 2
      .gitignore
  2. 0
      000-getting-started.md
  3. 0
      001-api.md
  4. 34
      002-search.md
  5. 0
      003-autocomplete.md
  6. 10
      004-reverse.md
  7. 4
      005-place.md
  8. 4
      006-response.md
  9. 0
      007-data-sources.md
  10. 0
      007-using-cors.md
  11. 6
      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 node_modules
npm-debug.log 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

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

@ -17,13 +17,13 @@ All Mapzen Search requests share the same format:
## Search the world ## 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. 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.
For example, if you want to find a [YMCA](https://en.wikipedia.org/wiki/YMCA) facility, here's what you'd need to append to the base URL of the service, `search.mapzen.com`. For example, if you want to find a [YMCA](https://en.wikipedia.org/wiki/YMCA) facility, here's what you'd need to append to the base URL of the service, `search.mapzen.com`.
> [/v1/search?api_key={YOUR-KEY}&___text=YMCA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA) > [/v1/search?api_key=search-XXXXXXX&___text=YMCA___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA)
Note the parameter values are set as follows: Note the parameter values are set as follows:
@ -51,7 +51,7 @@ In the example above, you will find the name of each matched locations in a prop
Spelling matters, but not capitalization when performing a query with Mapzen Search. You can type `ymca`, `YMCA`, or even `yMcA`. See for yourself by comparing the results of the previous search to the following: Spelling matters, but not capitalization when performing a query with Mapzen Search. You can type `ymca`, `YMCA`, or even `yMcA`. See for yourself by comparing the results of the previous search to the following:
> [/v1/search?api_key={YOUR-KEY}&___text=yMcA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yMcA) > [/v1/search?api_key=search-XXXXXXX&___text=yMcA___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=yMcA)
Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search. Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search.
@ -61,13 +61,13 @@ If you are looking for places in a particular region, or country, or only want t
### Search within a particular country ### 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). 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).
Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is *GBR* and set the parameters like this: Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is *GBR* and set the parameters like this:
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.country=GBR___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.country=GBR) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&___boundary.country=GBR___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&boundary.country=GBR)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
@ -90,7 +90,7 @@ Note that all the results reside within Great Britain:
If you attempt the same search request with different country codes, the results change to reflect YMCA locations within this region. If you attempt the same search request with different country codes, the results change to reflect YMCA locations within this region.
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.country=USA___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.country=USA) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&___boundary.country=USA___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&boundary.country=USA)
Results in the United States: Results in the United States:
@ -107,7 +107,7 @@ Results in the United States:
### Search within a rectangular region ### 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). 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).
@ -115,7 +115,7 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary
Tip: You can look up a bounding box for a known region with this [web tool](http://boundingbox.klokantech.com/)* Tip: You can look up a bounding box for a known region with this [web tool](http://boundingbox.klokantech.com/)*
[/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51) [/v1/search?api_key=search-XXXXXXX&text=YMCA&___boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
@ -139,13 +139,13 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary
### Search within a circular region ### 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. 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.
In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` represents your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers. In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` represents your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers.
> [/v1/search?api_key={YOUR_API_KEY}&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
@ -168,20 +168,20 @@ 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: 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 ## 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. 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 ### 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. 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.
To find YMCA again, but this time near the a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia. To find YMCA again, but this time near the a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia.
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
@ -212,7 +212,7 @@ Now that you have seen how to use boundary and focus to narrow and sort your res
Going back to the YMCA search you conducted with a focus around a point in Sydney, the results came back from distant parts of the world, as expected. But say you wanted to only see results from the country in which your focus point lies. You can combine that same focus point in Sydney with the country boundary of Australia like this. Going back to the YMCA search you conducted with a focus around a point in Sydney, the results came back from distant parts of the world, as expected. But say you wanted to only see results from the country in which your focus point lies. You can combine that same focus point in Sydney with the country boundary of Australia like this.
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281) > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
@ -241,7 +241,7 @@ The results below look very different from the ones you saw previously with only
If you are looking for the nearest YMCA locations, and are willing to travel no farther than 50 kilometers from your current location, you likely would want the results to be sorted by distance from current location to make your selection process easier. You can get this behavior by using `focus.point` in combination with `boundary.circle.*`. You can use the `focus.point.*` values as the `boundary.circle.lat` and `boundary.circle.lon`, and add the required `boundary.circle.radius` value in kilometers. If you are looking for the nearest YMCA locations, and are willing to travel no farther than 50 kilometers from your current location, you likely would want the results to be sorted by distance from current location to make your selection process easier. You can get this behavior by using `focus.point` in combination with `boundary.circle.*`. You can use the `focus.point.*` values as the `boundary.circle.lat` and `boundary.circle.lon`, and add the required `boundary.circle.radius` value in kilometers.
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&___boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&___boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
@ -284,7 +284,7 @@ The search examples so far have returned a mix of results from all the data sour
If you use the `sources` parameter, you can choose which of these data sources to include in your search. So if you're only interested in finding a YMCA in data from OpenAddresses, for example, you can build a query specifying that data source. If you use the `sources` parameter, you can choose which of these data sources to include in your search. So if you're only interested in finding a YMCA in data from OpenAddresses, for example, you can build a query specifying that data source.
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___sources=oa___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&sources=oa) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&___sources=oa___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&sources=oa)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
@ -307,7 +307,7 @@ Because OpenAddresses is, as the name suggests, only address data, here's what y
If you wanted to combine several data sources together, set `sources` to a comma separated list of desired source names. Note that the order of the comma separated values does not impact sorting order of the results; they are still sorted based on the linguistic match quality to `text` and distance from `focus`, if you specified one. If you wanted to combine several data sources together, set `sources` to a comma separated list of desired source names. Note that the order of the comma separated values does not impact sorting order of the results; they are still sorted based on the linguistic match quality to `text` and distance from `focus`, if you specified one.
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___sources=osm,gn___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&sources=oa) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&___sources=osm,gn___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&sources=oa)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |

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

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

@ -81,17 +81,17 @@ Distance from `point.lat`/`point.lon` | Confidence score
This section shows how the various parameters can be combined to form complex use cases. This section shows how the various parameters can be combined to form complex use cases.
* All results near the Tower of London >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493) * All results near the Tower of London >[/v1/reverse?api\_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493)
* Only OpenStreetMap results near the Tower of London * Only OpenStreetMap results near the Tower of London
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&sources=osm) >[/v1/reverse?api\_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493&sources=osm)
* Only street addresses near the Tower of London * Only street addresses near the Tower of London
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address) >[/v1/reverse?api\_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493&layers=address)
* Only OpenStreetMap street addresses near the Tower of London * Only OpenStreetMap street addresses near the Tower of London
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm) >[/v1/reverse?api\_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm)
* Only the first OpenStreetMap address near the Tower of London * Only the first OpenStreetMap address near the Tower of London
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1) >[/v1/reverse?api\_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1)

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

@ -12,7 +12,7 @@ If you have all of those, join them together with semicolon and pass them in wit
For example, this `/place` query looks up the Eiffel Tower in OSM: For example, this `/place` query looks up the Eiffel Tower in OSM:
http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:venue:5013364 https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:venue:5013364
***From Rhonda -- looks like this returns a radio station in Michigan? Also need to redo the query to include production server and the reader's API key*** ***From Rhonda -- looks like this returns a radio station in Michigan? Also need to redo the query to include production server and the reader's API key***
@ -22,7 +22,7 @@ http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:venue:50
To search for more than one `/place` in a request, join multiple values together and separate them with a comma. For example, this /place query looks up the Eiffel Tower in OSM and `30 West 26th St, New York, NY` in OpenAddresses: To search for more than one `/place` in a request, join multiple values together and separate them with a comma. For example, this /place query looks up the Eiffel Tower in OSM and `30 West 26th St, New York, NY` in OpenAddresses:
http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:country:5013364,oa:address:65cf57e4eb5548eca9bb548fb1461633 https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:country:5013364,oa:address:65cf57e4eb5548eca9bb548fb1461633
The results are returned in the order requested. The results are returned in the order requested.

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

@ -63,8 +63,8 @@ By default, Mapzen Search results 10 places, unless otherwise specified. If you
| `text` | YMCA | | `text` | YMCA |
| `size` | ***1*** | | `size` | ***1*** |
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___size=1___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&size=1) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&size=1)
If you want 25 results, you can build the query where `size` is 25. If you want 25 results, you can build the query where `size` is 25.
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___size=25___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&size=25) > [/v1/search?api_key=search-XXXXXXX&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&size=25)

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

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

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

@ -144,7 +144,7 @@ The `/autocomplete` endpoint serves as a renamed `/suggest` to indicate that the
# `/reverse` # `/reverse`
Reverse geocoding finds the places closest to geospatial coordinates. Reverse geocoding finds the places closest to geospatial coordinates.
```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&api_key={your-api-key} ```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&api_key=search-XXXXXXX
``` ```
Used to be (Beta) | New Parameter (V1) | New Behavior (if any) | Used to be (Beta) | New Parameter (V1) | New Behavior (if any) |
@ -159,7 +159,7 @@ New parameters:
## Reverse Coarse Geocoding ## Reverse Coarse Geocoding
Reverse coarse geocoding is not a point-in-polygon lookup (finding the hierarchy for the polygon that the point falls in), but instead looks for the hierarchy of points nearby. To use reverse coarse geocoding, use: Reverse coarse geocoding is not a point-in-polygon lookup (finding the hierarchy for the polygon that the point falls in), but instead looks for the hierarchy of points nearby. To use reverse coarse geocoding, use:
```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&layers=coarse&api_key={your-api-key} ```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&layers=coarse&api_key=search-XXXXXXX
``` ```
# `/place` (formerly `/doc`) # `/place` (formerly `/doc`)
@ -167,7 +167,7 @@ Reverse coarse geocoding is not a point-in-polygon lookup (finding the hierarchy
If a search returns `id: "geonames:3544:adm1:fr:fra:paris"` as the matching ID for a record, the complete underlying place record can be returned with: If a search returns `id: "geonames:3544:adm1:fr:fra:paris"` as the matching ID for a record, the complete underlying place record can be returned with:
``` ```
https://search.mapzen.com/v1/place?ids=geonames:3544:adm1:fr:fra:paris&api_key={your-api-key} https://search.mapzen.com/v1/place?ids=geonames:3544:adm1:fr:fra:paris&api_key=search-XXXXXXX
``` ```
# In-Browser Cross-Site Scripting # In-Browser Cross-Site Scripting

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 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 - Getting Started
- API Specification
- Transitioning From Beta to 1.0 - 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