Riordan
9 years ago
19 changed files with 0 additions and 868 deletions
@ -1,16 +0,0 @@
|
||||
Get started with Mapzen Search |
||||
|
||||
Mapzen Search is a modern geocoding and place search service based on [Pelias](https://github.com/pelias/pelias), an experimental open geocoder from [Mapzen](https://mapzen.com) and powered by open data. It's used to transform the way people talk about places - with names and addresses - into geographic coordinates. |
||||
|
||||
[REWRITE] |
||||
Mapzen Search can be used to: |
||||
- geocode addresses, points of interest, neighbourhood, cities, and regions |
||||
- power real-time search autocomplete for places |
||||
- turn a list of addresses into coordinates to plot |
||||
- Take location coordinates and turn them into human readable places, like an address |
||||
- find the neighbourhood, cities, states, and countries of location coordinates to quickly classify where your data is coming from |
||||
|
||||
Mapzen Search offers: |
||||
- Advanced Geocoding tools |
||||
- Coarse Geocoding |
||||
- |
||||
@ -1,22 +0,0 @@
|
||||
# API keys and rate limits |
||||
|
||||
## Obtain an API key |
||||
|
||||
To use the Mapzen Search service, you must first obtain a free, developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys. |
||||
|
||||
1. Go to https://mapzen.com/developers. |
||||
2. Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first. |
||||
3. Create a new key for Mapzen Search, and optionally, give it a name so you can remember the purpose of the project. |
||||
4. Copy the key into your code. |
||||
|
||||
## Rate limits |
||||
Because Mapzen Search is a free, shared service, there are limitations on the numbers of requests to prevent individual users from degrading the overall system performance. |
||||
|
||||
Mapzen Search allows you a maximum of: |
||||
- 6 requests per second |
||||
- 30,000 requests per day |
||||
|
||||
If you need more capacity, contact [search@mapzen.com](mailto:search@mapzen.com). You can also set up your own instance of [Pelias](https://github.com/pelias/pelias), which has access to the same data used in Mapzen Search. |
||||
|
||||
## Security |
||||
Mapzen Search works over HTTPS, in addition to HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query. |
||||
@ -1,335 +0,0 @@
|
||||
# Mapzen Search: Finding places |
||||
|
||||
Geospatial search, commonly referred to as geocoding, is the process of matching an address to its corresponding geographic coordinates. |
||||
|
||||
There's nothing inherent in the language we use to describe a physical address that allows us to convert that human readable sentence in to a format that a computer can understand, such as latitude & longitude. |
||||
|
||||
Making the leap from text to coordinates is an intricate and challenging process. Lucky for you, Mapzen has done all the hard work and made it accessible though a free web service. |
||||
|
||||
All Mapzen Search requests share the same format: |
||||
|
||||
``` |
||||
https://search.mapzen.com/v1/search?text=London&api_key=search-xxxxxx |
||||
\___/ \_______________/\__/\_____/\__________/\___________________/ |
||||
| | / | | | |
||||
scheme domain version path query authentication token |
||||
``` |
||||
|
||||
## Search the world |
||||
|
||||
 |
||||
|
||||
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`. |
||||
|
||||
> [/v1/search?api_key={YOUR-KEY}&___text=YMCA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA) |
||||
|
||||
Note the parameter values are set as follows: |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | ***YMCA*** | |
||||
|
||||
Clicking the link above will open a file containing the best matching results for the text `YMCA`. You will notice the data is in a computer-friendly format called [GeoJSON](http://geojson.org/), which may be hard for humans to read in some browsers. |
||||
|
||||
If you are having trouble seeing the JSON in your browser, you can install a browser extension for [Chrome](https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en) or [Firefox](https://addons.mozilla.org/en-us/firefox/addon/jsonview/) that will make it easier for you to read. |
||||
|
||||
In the example above, you will find the name of each matched locations in a property named `'label'`. The top 10 labels returned were: |
||||
|
||||
> * YMCA, Bargoed Community, United Kingdom |
||||
* YMCA, Nunspeet, Gelderland |
||||
* YMCA, Belleville, IL |
||||
* YMCA, Forest City, IA |
||||
* YMCA, Fargo, ND |
||||
* YMCA, Taipei, Taipei City |
||||
* YMCA, Orpington, Greater London |
||||
* YMCA, Frisco, TX |
||||
* YMCA, Jefferson, OH |
||||
* YMCA, Belleville, IL |
||||
|
||||
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) |
||||
|
||||
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. |
||||
|
||||
## Narrow your search |
||||
|
||||
If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. Mapzen Search currently supports three types: country, rectangle, and circle. |
||||
|
||||
### Search within a particular country |
||||
|
||||
 |
||||
|
||||
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: |
||||
|
||||
> [/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) |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | YMCA | |
||||
| `boundary.country` | ***GBR*** | |
||||
|
||||
Note that all the results reside within Great Britain: |
||||
|
||||
> * YMCA, Bargoed Community, United Kingdom |
||||
* YMCA, Orpington, Greater London |
||||
* YMCA, Erdington, West Midlands |
||||
* YMCA, Malvern CP, United Kingdom |
||||
* YMCA, Ancoats, Greater Manchester |
||||
* YMCA, Carmarthen Community, United Kingdom |
||||
* YMCA, Halebank, Cheshire |
||||
* YMCA, Brightlingsea CP, United Kingdom |
||||
* YMCA, Lenton Abbey, Nottinghamshire |
||||
* YMCA, Old Clee, Lincolnshire |
||||
|
||||
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) |
||||
|
||||
Results in the United States: |
||||
|
||||
> * YMCA, Belleville, IL |
||||
* YMCA, Forest City, IA |
||||
* YMCA, Fargo, ND |
||||
* YMCA, Frisco, TX |
||||
* YMCA, Jefferson, OH |
||||
* YMCA, Belleville, IL |
||||
* YMCA, Chapel Hill, NC |
||||
* YMCA, West Lampeter, PA |
||||
* YMCA, Bremerton, WA |
||||
* YMCA, Westerly, RI |
||||
|
||||
### Search within a rectangular region |
||||
|
||||
 |
||||
|
||||
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). |
||||
|
||||
For example, to find a YMCA within the state of Texas, you can set the `boundary.rect.*` parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5 |
||||
|
||||
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) |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `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*** | |
||||
|
||||
> * YMCA, Austin, TX |
||||
* YMCA, Frisco, TX |
||||
* Y.M.C.A, Fort Worth, TX |
||||
* YMCA, Rockwall, TX |
||||
* YMCA, Missouri City, TX |
||||
* YMCA, Northshore, TX |
||||
* YMCA, Austin, TX |
||||
* YMCA, Tulsa, OK |
||||
* YMCA, Los Alamos, NM |
||||
* YMCA, Tulsa, OK |
||||
|
||||
### Search within a circular region |
||||
|
||||
 |
||||
|
||||
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. |
||||
|
||||
> [/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) |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | YMCA | |
||||
| `boundary.circle.lat` | ***43.818156*** | |
||||
| `boundary.circle.lon` | ***-79.186484*** | |
||||
| `boundary.circle.radius` | ***35*** | |
||||
|
||||
You can see the results have fewer than the standard 10 items because there are not that many YMCA locations in the specified radius: |
||||
|
||||
> * YMCA, Toronto, Ontario |
||||
* YMCA, Markham, Ontario |
||||
* YMCA, Toronto, Ontario |
||||
* Metro Central YMCA, Toronto, Ontario |
||||
* Pinnacle Jr YMCA, Toronto, Ontario |
||||
* Cooper Koo Family Cherry Street YMCA Centre, Toronto, Ontario |
||||
|
||||
### Specify multiple boundaries |
||||
|
||||
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: |
||||
|
||||
 |
||||
|
||||
## 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 |
||||
|
||||
 |
||||
|
||||
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. |
||||
|
||||
> [/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) |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | YMCA | |
||||
| `focus.point.lat` | ***-33.856680*** | |
||||
| `focus.point.lon` | ***151.215281*** | |
||||
|
||||
Looking at the results, you can see that the few locations closer to this location show up at the top of the list, sorted by distance. You also still get back a significant amount of remote locations, for a well balanced mix. Because you provided a focus point, Mapzen Search can compute distance from that point for each resulting feature. |
||||
|
||||
> * YMCA, Redfern, New South Wales [distance: 3.836] |
||||
* YMCA, St Ives (NSW), New South Wales [distance: 14.844] |
||||
* YMCA, Epping (NSW), New South Wales [distance: 16.583] |
||||
* YMCA, Revesby, New South Wales [distance: 21.335] |
||||
* YMCA, Kochâang, South Gyeongsang [distance: 8071.436] |
||||
* YMCA, Center, IN [distance: 14882.675] |
||||
* YMCA, Lake Villa, IL [distance: 14847.667] |
||||
* YMCA, Onondaga, NY [distance: 15818.08] |
||||
* YMCA, 's-Gravenhage, Zuid-Holland [distance: 16688.292] |
||||
* YMCA, Loughborough, United Kingdom [distance: 16978.367] |
||||
|
||||
## Combine boundary search and prioritization |
||||
Now that you have seen how to use boundary and focus to narrow and sort your results, you can examine a few scenarios where they work well together. |
||||
|
||||
### Prioritize within a country |
||||
|
||||
**TBD: insert image here** |
||||
|
||||
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) |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | YMCA | |
||||
| `focus.point.lat` | -33.856680 | |
||||
| `focus.point.lon` | 151.215281 | |
||||
| `boundary.country` | ***AUS*** | |
||||
|
||||
The results below look very different from the ones you saw previously with only a focus point specified. These results are all from within Australia. You'll note the closest results show up at the top of the list, which is facilitated by the focus parameter. |
||||
|
||||
> * YMCA, Redfern, New South Wales [distance: 3.836] |
||||
* YMCA, St Ives (NSW), New South Wales [distance: 14.844] |
||||
* YMCA, Epping (NSW), New South Wales [distance: 16.583] |
||||
* YMCA, Revesby, New South Wales [distance: 21.335] |
||||
* YMCA, Larrakeyah, Northern Territory [distance: 3144.296] |
||||
* YMCA, Kepnock, Queensland [distance: 1001.657] |
||||
* YMCA, Kings Meadows, Tasmania [distance: 917.144] |
||||
* YMCA, Katherine East, Northern Territory [distance: 2873.376] |
||||
* YMCA, Sadadeen, Northern Territory [distance: 2026.731] |
||||
* YMCA, Ararat, Victoria [distance: 841.022] |
||||
|
||||
### Prioritize within a circular region |
||||
|
||||
**TBD: insert image here** |
||||
|
||||
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) |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `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*** | |
||||
|
||||
Looking at these results, they are all less than 50 kilometers away from the focus point: |
||||
|
||||
> * YMCA, Redfern, New South Wales [distance: 3.836] |
||||
* YMCA, St Ives (NSW), New South Wales [distance: 14.844] |
||||
* YMCA, Epping (NSW), New South Wales [distance: 16.583] |
||||
* YMCA, Revesby, New South Wales [distance: 21.335] |
||||
* Caringbah YMCA, Caringbah, New South Wales [distance: 22.543] |
||||
* YMCA building, Loftus, New South Wales [distance: 25.756] |
||||
|
||||
## Filter your search |
||||
|
||||
Mapzen Search brings together data from multiple open sources and combines a variety of place types into a single database, allowing you options for selecting the dataset you want to search. |
||||
|
||||
With Mapzen Search, you can filter by: |
||||
* `sources`: the originating source of the data |
||||
* `layers`: the kind of place you want to find |
||||
|
||||
### Filter by data source |
||||
The search examples so far have returned a mix of results from all the data sources available to Mapzen Search. Here are the sources currently being searched: |
||||
|
||||
| source | name | short name | |
||||
|---|---|---| |
||||
| [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` | |
||||
| [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` | |
||||
| [Quattroshapes](http://quattroshapes.com/) | `quattroshapes` | `qs` | |
||||
| [GeoNames](http://www.geonames.org/) | `geonames` | `ga` | |
||||
|
||||
****TO DO: Add a description of each of these.***** |
||||
|
||||
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) |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | YMCA | |
||||
| `sources` | **oa** | |
||||
|
||||
Because OpenAddresses is, as the name suggests, only address data, here's what you can expect to find: |
||||
|
||||
> * 0 Ymca, New Brunswick |
||||
* 0 Ymca Drive, Cary, NC |
||||
* 14843 Ymca Lane, Cormorant, MN |
||||
* 14660 Ymca Lane, Cormorant, MN |
||||
* 6221 Ymca Lane, Northampton County, VA |
||||
* 6223 Ymca Lane, Northampton County, VA |
||||
* 74 Ymca Road, Wairoa District, Hawke's Bay Region |
||||
* 108 Ymca Drive, Clinton, SC |
||||
* 101 Ymca Drive, Kannapolis, NC |
||||
* 31440 Ymca Road, Washington, OH |
||||
|
||||
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) |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | YMCA | |
||||
| `sources` | **osm,gn** | |
||||
|
||||
### Filter by data type |
||||
In Mapzen Search, place types are referred to as `layers`, ranging from fine to coarse. The Mapzen Search layers are derived from the hierarchy created by the gazetteer [Who's on First](https://github.com/whosonfirst/whosonfirst-placetypes/blob/master/README.md) and can be used to facilitate coarse geocoding. Here's a list of the types of places you could find in the results, sorted by granularity: |
||||
|
||||
****TO DO: Describe fine and coarse geocoding, gazeteer. *** |
||||
|
||||
|layer|description| |
||||
|----|----| |
||||
|`venue`|points of interest, businesses, things with walls| |
||||
|`address`|places with a street address| |
||||
|`country`|places that issue passports, nations, nation-states| |
||||
|`region`|states and provinces| |
||||
|`county`|official governmental area; usually bigger than a locality, almost always smaller than a region| |
||||
|`locality`|towns, hamlets, cities, etc.| |
||||
|`localadmin`|***TBD***| |
||||
|`neighbourhood`|...ehm, neighbourhoods| |
||||
|`coarse`|alias for simultaneously using `country`, `region`, `county`, `locality`, `localadmin`, and `neighbourhood`| |
||||
|
||||
****Add example**** |
||||
@ -1,3 +0,0 @@
|
||||
# Search with autocomplete |
||||
|
||||
If you are building an end-user application, you can enable `/autocomplete` alongside the `/search` to add real-time feedback to help users find what they are looking for more easily, without requiring them to type the entire search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list. |
||||
@ -1,97 +0,0 @@
|
||||
# Reverse geocoding |
||||
|
||||
Reverse geocoding is used for finding places or addresses near a latitude,longitude pair&mdashlike clicking on a map to see what's there when the map doesn't show it otherwise. For example, picture a map showing building outlines but no labels, then clicking on a building and being shown the name of the business. That's reverse geocoding. |
||||
|
||||
With reverse geocoding with Mapzen Search, you can look up all sorts of information about points on a map, including: |
||||
|
||||
* addresses |
||||
* points of interest (businesses, museums, parks, and so on) |
||||
* neighborhoods |
||||
* cities |
||||
* states |
||||
* postal areas |
||||
* countries |
||||
|
||||
To get started with reverse geocoding, you need a [free, developer API key](https://mapzen.com/developers) and a latitude,longitude pair in decimal degrees specified with the parameters `point.lat` and `point.lon`, respectively. For example, the Eiffel Tower in Paris, France, is located at `48.858268,2.294471`. The reverse geocode query for this would be: |
||||
|
||||
>[/v1/reverse?api\_key={YOUR-KEY}&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471) |
||||
|
||||
Notice that the first result is the Eiffel Tower (well, Tour Eiffel). The output is the standard GeoJSON format. |
||||
|
||||
reverse geocoding |
||||
|
||||
Similar to other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results. |
||||
|
||||
Parameter | Type | Required | Default | Example |
||||
--- | --- | --- | --- | --- |
||||
`api_key` | string | yes | none | [get yours here!](https://mapzen.com/developers) |
||||
`point.lat` | floating point number | yes | none | `48.858268` |
||||
`point.lon` | floating point number | yes | none | `2.294471` |
||||
`size` | integer | no | `10` | `3` |
||||
`layers` | comma-delimited string array | no | none (all layers) | `oa,gn` |
||||
`sources` | comma-delimited string array | no | none (all sources) | `address,locality` |
||||
`boundary.country` | <a href="https://en.wikipedia.org/wiki/ISO_3166-1" target="\_blank">ISO-3166 alpha-2 or alpha-3</a> | no | none | `FR` |
||||
|
||||
### Size |
||||
|
||||
A basic parameter for filtering is `size`, which is used to limit the number of results returned. In the previous request that returned the Eiffel Tower (or 'Tour Eiffel', to be exact), notice that other results were returned including "Bureau de Gustave Eiffel" (a museum) and "Le Jules Verne" (a restaurant). To limit a reverse geocode to only the first result, pass the `size` parameter: |
||||
|
||||
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___size=1___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&size=1) |
||||
|
||||
The default value for `size` is `10` and the maximum value is `40`. Specifying a value greater than `40` will override to `40` and return a warning in the response metadata. |
||||
|
||||
### Filter by data source |
||||
|
||||
By default, reverse geocoding returns results from any source available to Mapzen Search. To filter results by source, specify one or more valid source names in a comma-delimited list using the `sources` parameter. For example, the following request returns only results from OpenStreetMap: |
||||
|
||||
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&sources=osm) |
||||
|
||||
***TO DO: Add correct link**** For more information on the data each source provides, see [this link](http://source link). |
||||
|
||||
### Filter by layers |
||||
|
||||
Without specifying further, reverse geocoding doesn't restrict results to a particular type (street, venue, neighbourhood, and so on). If your application is only concerned with, say, which city a latitude, longitude is closest to, then use the `layers` parameter. For example, the following request returns only results that are localities (cities and towns): |
||||
|
||||
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&layers=locality) |
||||
|
||||
***TO DO: Add correct link**** For more information on what the different layers mean, see [this link](http://layers link). |
||||
|
||||
### Filter by country |
||||
|
||||
If you are performing a reverse geocode near a country boundary, and are only interested in results from one country and not the other, you can specify a country code. 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). For example, the latitude,longitude pair `47.270521,9.530846` is on the boundary of Austria, Liechtenstein, and Switzerland. Without specifying a `boundary.country`, the first 10 results returned may come from all three countries. By including `boundary.country=LIE`, all 10 results will be from Liechtenstein. Here's the request in action: |
||||
|
||||
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=47.270521&point.lon=9.530846&___boundary.country=LIE___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=47.270521&point.lon=9.530846&boundary.country=LIE) |
||||
|
||||
Note that `UK` is not a valid ISO 3166-1 alpha-2 country code. |
||||
|
||||
## Confidence scores for the results |
||||
|
||||
Each result returned has an associated confidence score. Currently confidence scores are calculated based on the distance from the result to the supplied `point.lat` and `point.lon`. Confidence scoring for reverse geocode results is likely to change with different data sources and layers. |
||||
|
||||
Distance from `point.lat`/`point.lon` | Confidence score |
||||
--- | --- |
||||
< 1m | 1.0 |
||||
< 10m | 0.9 |
||||
< 100m | 0.8 |
||||
< 250m | 0.7 |
||||
< 1km | 0.6 |
||||
>= 1km | 0.5 |
||||
|
||||
## Example requests |
||||
|
||||
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) |
||||
|
||||
* 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) |
||||
|
||||
* 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) |
||||
|
||||
* 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) |
||||
|
||||
* 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) |
||||
@ -1,42 +0,0 @@
|
||||
# Search an ID to get details on a place |
||||
|
||||
When you know an identification number and the source it came from, you can use Mapzen Search to get details on the location. |
||||
|
||||
To get started with a place search, you need a [free, developer API key](https://mapzen.com/developers) and these three pieces of information: |
||||
|
||||
* source - the data source, such as OpenStreetMap |
||||
* layer - the type of place, such as a venue, address, country. |
||||
* id - the identification number of the item |
||||
|
||||
If you have all of those, join them together with semicolon and pass them in with the `ids` parameter. |
||||
|
||||
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 |
||||
|
||||
***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 -- what are some examples of when you would use a /place search? When would you have this info and need to get the details? What would you do with it.*** |
||||
|
||||
## Search for multiple places in a query |
||||
|
||||
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 |
||||
|
||||
The results are returned in the order requested. |
||||
|
||||
***From Rhonda -- is there another example where you might do multiple requests at the same time...in other words, more related locations?*** |
||||
|
||||
Keep in mind that if you enter a `source:layer:id` combination that cannot be found, then the `features` array in the response contains a different number of elements than the number of requests. This will be most noticeable in requests with multiple IDs, as your request may have three IDs requested but only two results returned. The reason for this is that the `features` section of the response is GeoJSON-compliant and there is currently no way to convey an exception condition (not even an empty JSON element, `{}`). For this reason, if your application is dependent upon the results mapping directly to the individual input requests in order, then you'll have to do your own bookkeeping to handle exception conditions. |
||||
|
||||
## Valid combinations of place searches |
||||
|
||||
Some combinations of `sources` and `layers` are valid while others are not. This table shows valid combinations. |
||||
|
||||
source | layers |
||||
--- | --- |
||||
`osm` or `openstreetmap` | `venue`, `address` |
||||
`oa` or `openaddresses` | `address` |
||||
`gn` or `geonames` | `venue`, `address`, `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse` |
||||
`qs` or `quattroshapes` | `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse` |
||||
@ -1,70 +0,0 @@
|
||||
# Search results |
||||
|
||||
When requesting results from Mapzen Search, you will always get back `GeoJSON` results, unless something goes terribly wrong, in which case you'll get an error message. |
||||
|
||||
Tip: You can go to http://geojson.org/geojson-spec.html to learn more about the GeoJSON data format specification. |
||||
|
||||
The top-level structure to every response looks like this: |
||||
|
||||
```json |
||||
{ |
||||
"geocoding":{...}, |
||||
"type":"FeatureCollection", |
||||
"features":[...], |
||||
"bbox":[...] |
||||
} |
||||
``` |
||||
|
||||
##List of `features` returned |
||||
|
||||
The `features` property of the result is where you will find the list of results that best matched your input parameters. |
||||
|
||||
Each item in this list will contain all the information needed to identify it in human-readable format in the `properties` block, as well as computer friendly coordinates in the `geometry` property. Note the `label` property, which is a human-friendly representation of the place, ready to be displayed to an end-user. |
||||
|
||||
```json |
||||
{ |
||||
"type":"Feature", |
||||
"properties":{ |
||||
"gid":"...", |
||||
"layer":"address", |
||||
"source":"osm", |
||||
"name":"30 West 26th Street", |
||||
"housenumber":"30", |
||||
"street":"West 26th Street", |
||||
"postalcode":"10010", |
||||
"country_a":"USA", |
||||
"country":"United States", |
||||
"region":"New York", |
||||
"region_a":"NY", |
||||
"county":"New York County", |
||||
"localadmin":"Manhattan", |
||||
"locality":"New York", |
||||
"neighbourhood":"Flatiron District", |
||||
"confidence":0.9624939994613662, |
||||
"label":"30 West 26th Street, Manhattan, NY" |
||||
}, |
||||
"geometry":{ |
||||
"type":"Point", |
||||
"coordinates":[ |
||||
-73.990342, |
||||
40.744243 |
||||
] |
||||
} |
||||
} |
||||
``` |
||||
|
||||
## Result count |
||||
|
||||
By default, Mapzen Search results 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning only the first result. |
||||
|
||||
| parameter | value | |
||||
| :--- | :--- | |
||||
| `api_key` | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | YMCA | |
||||
| `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) |
||||
|
||||
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) |
||||
@ -1,8 +0,0 @@
|
||||
Data Sources |
||||
============= |
||||
|
||||
Mapzen Search is powered by several major open data sets and owes a tremendous debt of gratitude to the individuals and communities which produced them. |
||||
|
||||
# Data Sources |
||||
|
||||
# Licensing & Attribution |
||||
@ -1,73 +0,0 @@
|
||||
# Loading data from the browser |
||||
|
||||
For security reasons, web browsers prevent what are called “cross-origin” or “cross-site” requests from one domain to another. JavaScript `XMLHTTPRequests` (commonly called “AJAX” requests) inherit all of the authentication context of the currently logged in user, so a malicious web page could attempt to make malicious requests that cross domain contexts and cause trouble. Historically, that has made it difficult for web developers to build web applications making use of third-party APIs. |
||||
|
||||
Fortunately, techniques have since been developed that allow developers to securely access APIs cross-domain. |
||||
|
||||
## Cross-Origin Resource Sharing (CORS) |
||||
|
||||
`CORS` is the recommended standard for allowing your web browser and a web server to negotiate and allow requests to be made across domain contexts. `CORS` is currently supported in modern Chrome, Firefox, Safari, and Internet Explorer (10+) web browsers. It became an official W3C Recommendation on the 16th January 2014. |
||||
|
||||
You don’t need to do anything special to use `CORS` with JavaScript in a modern browser. Your web browser and our servers will automatically negotiate the cross-origin request. For example, to make a `CORS` request with `jQuery`, you’d make your request just like you were performing it within the context of your own domain. |
||||
|
||||
For a full list of supported browsers see: http://caniuse.com/#feat=cors |
||||
|
||||
### Loading data with jQuery |
||||
|
||||
```javascript |
||||
$.ajax({ |
||||
url: "https://search.mapzen.com/v1/search", |
||||
method: "GET", |
||||
dataType: "json", |
||||
data: { |
||||
"text": "London, UK", |
||||
"api_key": "search-EEgHGcM" |
||||
}, |
||||
success: function( data, status, jqxhr ){ |
||||
console.log( "Request received:", data ); |
||||
}, |
||||
error: function( jqxhr, status, error ){ |
||||
console.log( "Something went wrong!" ); |
||||
} |
||||
}); |
||||
``` |
||||
|
||||
interactive demo: http://jsfiddle.net/missinglink/fb6p0par/ |
||||
|
||||
### Loading data with Angular |
||||
|
||||
```javascript |
||||
$http({ |
||||
url: "https://search.mapzen.com/v1/search", |
||||
method: "GET", |
||||
headers: { "Accept": "application/json" }, |
||||
params: { |
||||
"text": "London, UK", |
||||
"api_key": "search-EEgHGcM" |
||||
}, |
||||
}) |
||||
.success(function( data, status ) { |
||||
console.log( "Request received:", data ); |
||||
}) |
||||
.error(function( data, status ) { |
||||
console.log( "Something went wrong!" ); |
||||
}); |
||||
``` |
||||
|
||||
interactive demo: http://jsfiddle.net/missinglink/nchh8a9j/ |
||||
|
||||
## Why not JSONP? |
||||
|
||||
Also called “JSON with Padding”, `JSONP` is a technique for fooling a web browser into performing cross-origin requests using a special ``<script>`` tag that uses the `src` attribute that to make a special API request. |
||||
|
||||
Instead of responding with just a `JSON` object, the server responds with JavaScript code that calls a client-declared callback function, passing the data as that function’s first parameter. |
||||
|
||||
`JSONP` **is disabled** by default for Mapzen Search as `CORS` is offered as a more modern alternative. |
||||
|
||||
You can find more information online using the queries `"CORS vs JSONP"` and `"Security risks with JSONP"`. |
||||
|
||||
If you are having any issues implementing `CORS` with Mapzen Search you can open up an issue on the tracker https://github.com/pelias/pelias, please include the name of any frameworks you are using and some example code :) |
||||
|
||||
--- |
||||
|
||||
This content is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Some content adapted from the [Socrata Documentation](http://dev.socrata.com/docs/cors-and-jsonp.html). |
||||
|
Before Width: | Height: | Size: 120 KiB |
|
Before Width: | Height: | Size: 255 KiB |
|
Before Width: | Height: | Size: 2.1 MiB |
|
Before Width: | Height: | Size: 359 KiB |
|
Before Width: | Height: | Size: 372 KiB |
|
Before Width: | Height: | Size: 364 KiB |
|
Before Width: | Height: | Size: 373 KiB |
@ -1,10 +0,0 @@
|
||||
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. |
||||
|
||||
- Getting Started |
||||
- API Specification |
||||
- Transitioning From Beta to 1.0 |
||||
@ -1,191 +0,0 @@
|
||||
Mapzen Search: Beta to V1 transition guide |
||||
=========================================== |
||||
|
||||
First of all, thank you for being an early user of Mapzen Search/Pelias. You trusted the idea of a modern geocoding service built by and for the open mapping community and have helped make that happen. |
||||
|
||||
We're moving out of our beta stage and have an updated API designed to support the next several generations of progress to Pelias and Mapzen Search. |
||||
|
||||
The changes aren't too drastic and should be implementable in an afternoon or a day at most for existing users. |
||||
|
||||
These changes also affect self-hosted users of Pelias upgrading from the beta to 1.0 (leaving aside API key restrictions), but these users can make the upgrade on their own time. |
||||
|
||||
# API Keys |
||||
The first big change is the introduction of API Keys. Like all other Mapzen APIs, Search now requires a free API key. You can register at the Mapzen Developer Portal and generate one (or more) for all your search needs. |
||||
|
||||
Mapzen Search API keys allow you: |
||||
* 6 requests / second |
||||
* 30,000 requests / day |
||||
|
||||
To start using an API key, append `&api_key=search-xxxxxx` to all API calls to all endpoints (aside from `/attribution`, which requires no key). |
||||
|
||||
Your API usage limits are displayed in the HTTP headers of any API call. |
||||
|
||||
e.g. |
||||
``` |
||||
X-ApiaxleProxy-Qpd-Left:4828 |
||||
X-ApiaxleProxy-Qps-Left:4 |
||||
``` |
||||
|
||||
# Changes to response document |
||||
The response document is still plain vanilla GeoJSON. Dots will still show up without a problem! Take a look at our [specification document](https://github.com/pelias/geocodejson-spec/blob/master/draft/README.md) or our [sample response](https://github.com/pelias/geocodejson-spec/blob/master/sample.geo.json?short_path=7cdb999) for further details. |
||||
|
||||
## Metadata |
||||
The GeoJSON result object now contains a `geocoding` property, that has lots of goodies about the request (how Mapzen Search parsed your query, certain explicit errors and warnings, attribution link). |
||||
|
||||
## Features |
||||
The bulk of a valid response is still an array of `Feature` objects, ordered by result ranking (most relevant result first). Changed feature response elements include: |
||||
|
||||
If the only property you used before was `text` for what to display, you'll just have to change it to `label` and you'll be ready to process responses. |
||||
|
||||
| Used to be (Beta) | Is Now (V1) | Notes | |
||||
| ----------------- | ----------- | --------------- | |
||||
| `text` | `label` | Our suggested display text. You can construct your own from the elements passed along, but this is our best understanding of how to display it. | |
||||
| `layer` | `layer` & `source` | Some layers were not attributes, but sources the data was derived from. This has been split out into a separate field. (see Search/Layers below for full explanation) | |
||||
| `admin0` | `country` | Now with Human Readable:tm: | |
||||
| `admin1` | `region` | States & Provinces | |
||||
| `alpha3` | `country_a` | 3-character abbreviation for country | |
||||
| `admin1_abbr` | `region_a` | Region abbreviation (e.g. NY = New York, usually 2 character) | |
||||
| `locality` | `locality` | No change| |
||||
| `neighborhood` | `neighbourhood` | Note change in spelling | |
||||
| `category` | Deprecated | We're rethinking categories. They'll be back soon, better than ever.| |
||||
| `address:{}` | | address elements are no longer grouped into their own object | |
||||
| `address:{zip}` | `postalcode` | | |
||||
| `address:{number}` | `housenumber` | | |
||||
| `address:{street}` | `street` | | |
||||
|
||||
|
||||
# Changes to `/search` |
||||
Most parameters (and options) for search have been renamed: |
||||
|
||||
| Used to be (Beta) | New Parameter (V1) | New Behavior (if any) | |
||||
| ---------- | ------------- | --------------------- | |
||||
| `input` | `text` | | |
||||
| `lat` / `lon` | `focus.point.lat` / `focus.point.lon` | Biases search results toward places nearby, without excluding global matches | |
||||
| `zoom` | `focus.viewport.min_lon`, `focus.viewport.min_lat`, `focus.viewport.max_lon`, `focus.viewport.max_lat` | Passing along information about how far out an end-user is looking is now accomplished by passing along the end-user's viewport. Why judge just from a centerpoint and a zoom level when you can see what the user's seeing? | |
||||
| `size` | `count` | Number of responses. Minimum: 1, maximum: 50 | |
||||
| `layers` | `layers` (SEE BELOW) | While the parameter remains the same, the options have changed. Please see the below table for description.| |
||||
| `bbox` | `boundary.rect.min_lon`, `boundary.rect.min_lat`, `boundary.rect.max_lon`, `boundary.rect.max_lat`| Bounding box parameters are now individually specified to prevent error.| |
||||
| `details` | Deprecated (for the moment) | `details=false` used to respond with a minimized set of elements. We are reevaluating which elements of the response document make most sense for minimization. If you've got opinions, let us know at [search@mapzen.com](mailto:search@mapzen.com)| |
||||
|
||||
`layers` were previously opaque about many of the kinds of places they represented (particularly the administrative layers). `layers` were also used to retrieve places from a particular source. `sources` is now a separate parameter from `layers` to facilitate clarity. |
||||
|
||||
| Beta | V1 | Represents | |
||||
| -------------- | ------------ | ---------------- | |
||||
| `layers=geoname` | `sources=geonames` or `sources=gn` | [All manners of places](http://www.geonames.org/export/codes.html) from Geonames | |
||||
| `layers=osmnode` | `layers=venue,address&sources=openstreetmap` | Venues (points of interest) and all places with addresses from OpenStreetMap| |
||||
| `layers=osmway` | `layers=venue,address&sources=openstreetmap` | Streets & Highways with Addresses | |
||||
| `layers=admin0` | `layers=country` | Countries| |
||||
| `layers=admin1` | `layers=region` | Provinces & States (for the most part) | |
||||
| `layers=admin2` | `layers=county` | Things within states that often aren't cities, but sometimes are.| |
||||
| `layers=neighborhood` | `layers=neighbourhood` | Neighbourhoods (within localities, may be [macrohoods](http://whosonfirst.mapzen.com/spelunker/placetypes/macrohood/), neighbourhoods, or [microhoods](http://whosonfirst.mapzen.com/spelunker/placetypes/microhood/)) | |
||||
| `layers=locality` | `layers=locality` | | |
||||
| `layers=local_admin` | `layers=localadmin` | Local administrative areas (e.g. New York City, encompassing the five boroughs of NYC, which are themselves independent counties)| |
||||
| `layers=osmaddresses` | `layers=addresses&source=openstreetmap` | Addresses from OpenStreetMap| |
||||
| `layers=openaddresses` | `source=openaddresses` | Addresses from OpenAddresses | |
||||
| `layers=poi` | `layers=venue` | Places with walls | |
||||
| `layers=admin` | `layers=coarse` | Shortcut for coarse geocoding layers (see below) | |
||||
| `layers=address` | `layers=address` | | |
||||
|
||||
So the new legitimate `layers` values are: |
||||
* `venue` |
||||
* `address` |
||||
* `neighbourhood` |
||||
* `localadmin` |
||||
* `locality` |
||||
* `county` |
||||
* `region` |
||||
* `country` |
||||
* `coarse` |
||||
|
||||
And the `sources` values are: |
||||
* `openstreetmap` or `osm` |
||||
* `geonames` or `gn` |
||||
* `openaddresses` or `oa` |
||||
* `quattroshapes` or `qs` |
||||
|
||||
|
||||
## Additions |
||||
| Oooh, shiny! | What's it do? | |
||||
| ------------ | ------------- | |
||||
| `sources` parameter | pick the datasource (separate from `layers`) | |
||||
| `boundary.circle` | Bounding circle. Like a bounding box, but circular. Takes, `boundary.circle.lon`, `boundary.circle.lat`, and `boundary.circle.radius` (in kilometers) | |
||||
| `boundary.country` | Search only within a particular country. Takes Alpha-2 or Alpha-3 country code abbreviations.| |
||||
|
||||
## Coarse Search |
||||
Coarse search (looking for countries, regions, counties, localities, neighbourhoods), was previously available on `/search/coarse`. This is now handled as a layer on search. |
||||
|
||||
A former query for a coarse geocode may have been: |
||||
`https://pelias.mapzen.com/search/coarse?input=<search-text>` |
||||
|
||||
That same query would now be written as: |
||||
`https://search.mapzen.com/v1/search?text=<search-text>&layers=coarse&api_key=<your-api-key>` |
||||
|
||||
You can also call the coarse layers directly, namely: `country`, `region`, `county`, `locality`, `neighbourhood`, to restrict the kinds of results you'll get back. |
||||
|
||||
Feel free to mix and match these layers with `boundary` parameters, particularly `boundary.country` if you want to restrict your results to a particular country. |
||||
|
||||
# `/autocomplete` (formerly `/suggest`) |
||||
The `/autocomplete` endpoint serves as a renamed `/suggest` to indicate that these are not recommendations. It is subject to many of the same changes as `/search`: |
||||
|
||||
| Used to be (Beta) | New Parameter (V1) | New Behavior (if any) | |
||||
| ---------- | ------------- | --------------------- | |
||||
| `input` | `text` | Required | |
||||
| `lat` / `lon` | `focus.point.lat` / `focus.point.lon` | Biases search results toward places nearby, without excluding global matches. No longer required for `/autocomplete` | |
||||
| `size` | Deprecated | Responds with 10 results every time | |
||||
| `zoom` | Deprecated | | |
||||
| `layers` | Deprecated | | |
||||
| `bbox` | Deprecated | | |
||||
| `details` | Deprecated | | |
||||
|
||||
## Deprecated endpoints |
||||
- `/suggest/coarse` |
||||
- `/suggest/nearby` |
||||
|
||||
# `/reverse` |
||||
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} |
||||
``` |
||||
|
||||
Used to be (Beta) | New Parameter (V1) | New Behavior (if any) | |
||||
| ---------- | ------------- | --------------------- | |
||||
| `lat` / `lon` | `point.lon` / `point.lat` | Required | |
||||
| `layers` | `layers` | same set of layers as for `/search` | |
||||
|
||||
New parameters: |
||||
- `boundary.circle` - use `boundary.circle.radius` to set the distance for a reverse point search in kilometers |
||||
- `boundary.country` - Restricts reverse geocodes to a particular country based on alpha2 or alpha3 country codes |
||||
|
||||
## 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: |
||||
|
||||
```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&layers=coarse&api_key={your-api-key} |
||||
``` |
||||
|
||||
# `/place` (formerly `/doc`) |
||||
`/place` is used to retrieve the underlying place record behind a particular result. |
||||
|
||||
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} |
||||
``` |
||||
|
||||
# In-Browser Cross-Site Scripting |
||||
If you were using Pelias from within a browser with client-side javascript (using Pelias on a domain that is different mapzen.com), you should know that Mapzen Search does not support JSONP requests to get around cross-site scripting limitations. |
||||
|
||||
Instead, Mapzen Search supports [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) (CORS), which enables secure cross-site data transfers. |
||||
|
||||
Mapzen Search is set to allow CORS requests from all domains. |
||||
|
||||
# HTTPS |
||||
Mapzen Search continues to support HTTPS and traditional HTTP. We encourage you to use HTTPS in lieu of HTTP, especially when handling sensitive personal information (e.g. users' searches, users' location data). |
||||
|
||||
# What's happening to pelias.mapzen.com? |
||||
We're keeping the beta API available at pelias.mapzen.com up through the end of November, 2015. Starting December 1, 2015, you will only be able to use search.mapzen.com or your own hosted version of Pelias. |
||||
|
||||
# Anything Else We're Forgetting? |
||||
Let us know. |
||||
|
||||
Words go to: [search@mapzen.com](mailto:search@mapzen.com) |
||||
|
||||
Issues go to [Github](https://github.com/pelias/pelias-doc/issues) |
||||
Loading…
Reference in new issue