pelias
/
documentation
mirror of https://github.com/pelias/documentation.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

fix conflicts with master

pull/150/head
rmglennon 8 years ago
parent
04128df816 6a5f5c8f7f
commit
34fba65032
16 changed files with 173 additions and 137 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 5
      add-search-to-a-map.md
  2. 42
      api-keys-rate-limits.md
  3. 52
      autocomplete.md
  4. 7
      data-sources.md
  5. 11
      get-started.md
  6. 2
      glossary.md
  7. BIN
      images/world_country.png
  8. 18
      index.md
  9. 20
      installing.md
  10. 4
      place.md
  11. 69
      release-notes.md
  12. 4
      response.md
  13. 26
      reverse.md
  14. 36
      search.md
  15. 10
      transition-from-beta.md
  16. 4
      use-cors.md

5
add-search-to-a-map.md
Unescape View File

@ -14,8 +14,6 @@ Suggested text editor applications include [Atom - OS X, Windows, Linux](https:/
## Sign up for a Mapzen API key
To use the geocoding service, you must first get a Mapzen [API key](https://en.wikipedia.org/wiki/Application_programming_interface_key). Because the search service is shared among many users, an API key is a way to make sure that the performance is acceptable for everyone. 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](https://help.github.com/articles/signing-up-for-a-new-github-account/). If you have not done this before, you need to agree to the terms first.
3. Create a new key, and, optionally, give it a project name so you can remember the purpose of the key.
@ -191,6 +189,7 @@ To recap how you created this, you added references to the Mapzen JS and CSS fil
So far, you have referenced the necessary files, initialized Leaflet with a map container on the page, and added data to the map. Now, you are ready to add the Search box.
1. Go back to the https://mapzen.com/developers page and copy your API key to the clipboard.
<<<<<<< HEAD
2. Inside the same `<script>` tag, and after the code you just added for the map, initialize a search box and add it to the map with the following code. Use your own API key substituted for the placeholder text of `mapzen-xxxxxx`.
```js
@ -206,7 +205,6 @@ So far, you have referenced the necessary files, initialized Leaflet with a map
![Search icon on the map canvas](images/geocoder-search-icon.png)
Your `<body>` section should look like this:
```html
@ -367,7 +365,6 @@ You can refer to this HTML if you want to review your work or troubleshoot an er
}
html,body{margin: 0; padding: 0}
</style>
</head>
<body>
<div id='map'></div>

42
api-keys-rate-limits.md
Unescape View File

@ -6,7 +6,7 @@ To use the Mapzen Search service, you must first get a developer API key. Sign i
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.
3. Create a new key and optionally, give it a name so you can remember the purpose of the project.
4. Copy the key into your code.
## Rate limits
@ -17,41 +17,7 @@ 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.
## Failing to provide an `api_key`
If you fail to supply the `api_key` parameter, the service will respond with the status code `403 Forbidden`:
```bash
{
"meta": {
"version": 1,
"status_code": 403
},
"results": {
"error": {
"type": "KeyError",
"message": "No api_key specified."
}
}
}
```
## Exceeding your limits
If you exceed your limits, the service will respond with the status code `429 Too Many Requests`:
```bash
{
"meta": {
"version": 1,
"status_code": 429
},
"results": {
"error": {
"type": "QpsExceededError",
"message": "Queries per second exceeded: Queries exceeded (6 allowed)."
}
}
}
```
If you need more capacity, contact [search@mapzen.com](mailto:search@mapzen.com). You can also set up your own instance of [Pelias](https://pelias.io), which has access to the same data used in Mapzen Search.
## Security
Mapzen Search works over HTTPS and 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.
@ -62,7 +28,7 @@ Mapzen Search uses caching to serve commonly requested content as quickly as pos
Queries that are served from the edge cache do not count toward your limit of queries per second or queries per day, although you will still see them listed in your [dashboard](https://mapzen.com/developers/).
When you send a request to Mapzen Search, it first goes to the CDN server that is the closest path from your internet service provider before it is forwarded onto a Mapzen Search application server. Mapzen Search uses [Fastly](https://www.fastly.com) for its CDN; you can look at this [network map](https://www.fastly.com/network-map) to see where your requests are likely being sent.
When you send a request to Mapzen Search, it first goes to the CDN server that is the closest path from your internet service provider before it is forwarded onto a Mapzen Search application server. Mapzen Search uses [Fastly](https://www.fastly.com) for its CDN; you can look at this [network map](https://www.fastly.com/network-map) to see where your requests are likely being sent.
If your request is not found in the current CDN cache, the CDN server then passes it to one of the Mapzen Search application servers. When it comes back with a response to your API call, the CDN server keeps a copy of that response (minus any personal data to your application, including your API key). If you or another nearby user makes the identical API call, you will likely be sent to the same CDN server, which has the response in its local cache. From tests in the Mapzen offices in New York, this has the effect of shortening a query from 190ms to 21ms. Your speed improvements may vary, as requests from other locations and internet providers may be served by different edge cache servers. The Mapzen Search cache is updated on the CDN at least once a week.
@ -73,4 +39,4 @@ Unless you have recently made a particular API call, you will not know ahead of
These header entries are most helpful to determine whether caching was used:
- `X-Cache` indicates if your request was served from the Mapzen Search application server (`MISS`) or the cache server (`HIT`). This header should be there for any query you make to the Mapzen Search API. Any query with `X-Cache: MISS` is a query that counts toward your rate limit.
- `X-ApiaxleProxy-Qps-Left` is the number of queries per second remaining on your API key, and `X-ApiaxleProxy-Qpd-Left` is the remaining queries per day. These headers are only present when you see `X-Cache: MISS`.
- `X-ApiaxleProxy-Qps-Left` is the number of queries per second remaining on your API key, and `X-ApiaxleProxy-Qpd-Left` is the remaining queries per day. These headers are only present when you see `X-Cache: MISS`.

52
autocomplete.md
Unescape View File

@ -8,9 +8,9 @@ To build a query with autocomplete, you need an [API key](https://mapzen.com/dev
There are two user experience pitfalls to watch out for when implementing a client-side typeahead solution:
**Requests must be throttled.** The client must only send a maximum of one or two requests per second. Sending requests more often than this will result in a sluggish network and laggy user interface for mobile consumers. A general rule is to account for fast typers by batching their keystrokes and sending the input text no more than twice per second. Mapzen Search limits the amount of requests per second (per API key), so be sure to account for those limits in your throttle code. [Learn more in this interactive demo.](http://jsfiddle.net/missinglink/19e2r2we/)
**Requests must be throttled.** Since autocomplete requests generally correspond directly to user input, it's important to account for fast typers and throttle requests when using the autocomplete endpoint. Mapzen Search has a per second rate limit (that defaults to 6 requests per second), but some devices and networks (for example, mobile phones on a slow connection) may also respond poorly when too many requests are sent too quickly, so be sure to do some testing on your own. [Learn more in this interactive demo.](http://jsfiddle.net/missinglink/19e2r2we/)
**Responses are asynchronous.** This means you cannot be sure responses will be returned in the same order they were requested. If you were to send two queries synchronously, first `'Lo'` then `'London'`, you may find the `'London'` response would arrive before the `'Lo'` response. This will result in a quick flash of `'London'` results followed by the results for `'Lo'`, which can confuse the user. You must account for this behavior by storing the `requested_at` timestamps for each request and discarding older responses when they arrive late.
**Responses are asynchronous.** This means you cannot be sure responses will be returned in the same order they were requested. If you were to send two queries synchronously, first `'Lo'` then `'London'`, you may find the `'London'` response would arrive before the `'Lo'` response. This will result in a quick flash of `'London'` results followed by the results for `'Lo'`, which can confuse the user.
## Global scope, local focus
@ -19,7 +19,7 @@ To focus your search based upon a geographical area, such as the center of the u
From San Francisco:
>
[/v1/autocomplete?api_key=search-TeXrSTX&__focus.point.lat=37.7&focus.point.lon=-122.4&text=union square__](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&focus.point.lat=37.7&focus.point.lon=-122.4&text=union square)
[/v1/autocomplete?api_key=mapzen-xxxxxx&__focus.point.lat=37.7&focus.point.lon=-122.4&text=union square__](https://search.mapzen.com/v1/autocomplete?focus.point.lat=37.7&focus.point.lon=-122.4&text=union square)
```
1) Union Square, San Francisco County, CA
@ -29,7 +29,7 @@ From San Francisco:
From New York City:
>
[/v1/autocomplete?api_key=search-TeXrSTX&__focus.point.lat=40.7&focus.point.lon=-73.9&text=union square__](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&focus.point.lat=40.7&focus.point.lon=-73.9&text=union square)
[/v1/autocomplete?api_key=mapzen-xxxxxx&__focus.point.lat=40.7&focus.point.lon=-73.9&text=union square__](https://search.mapzen.com/v1/autocomplete?focus.point.lat=40.7&focus.point.lon=-73.9&text=union square)
```
1) Union Square, New York County, NY
@ -38,7 +38,7 @@ From New York City:
The `/autocomplete` endpoint can promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. For example, searching `hard rock cafe` with a focus on Berlin:
> [/v1/autocomplete?api_key=search-TeXrSTX&__focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe__](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe)
> [/v1/autocomplete?api_key=mapzen-xxxxxx&__focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe__](https://search.mapzen.com/v1/autocomplete?focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe)
with `focus.point` you will find the Berlin restaurant first:
```
@ -65,7 +65,7 @@ The `sources` parameter allows you to specify from which data sources you'd like
* `geonames` or `gn`
* `whosonfirst` or `wof`
> [/v1/autocomplete?api_key=search-TeXrSTX&__sources=openaddresses__&text=pennsylvania](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&sources=openaddresses&text=pennsylvania)
> [/v1/autocomplete?api_key=mapzen-xxxxxx&__sources=openaddresses__&text=pennsylvania](https://search.mapzen.com/v1/autocomplete?sources=openaddresses&text=pennsylvania)
with `sources=openaddresses` you will only find addresses on Pennsylvania Ave or Street:
```
@ -84,22 +84,23 @@ without `sources=openaddresses` you will find the most popular Pennsylvanias fir
### Layers
The type of record is referred to as its `layer`. All records are indexed into the following layers:
* `venue`
* `address`
* `microhood`
* `neighbourhood`
* `macrohood`
* `county`
* `macrocounty`
* `localadmin`
* `locality`
* `borough`
* `region`
* `country`
You can also refer to all the administrative hierarchy layers with a single alias, `coarse`.
> [/v1/autocomplete?api_key=search-TeXrSTX&__layers=coarse__&text=starbuck](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&layers=coarse&text=starbuck)
|layer|description|
|----|----|
|`venue`|points of interest, businesses, things with walls|
|`address`|places with a street address|
|`street`|streets,roads,highways|
|`country`|places that issue passports, nations, nation-states|
|`macroregion`|a related group of regions. Mostly in Europe|
|`region`|states and provinces|
|`macrocounty`|a related group of counties. Mostly in Europe.|
|`county`|official governmental area; usually bigger than a locality, almost always smaller than a region|
|`locality`|towns, hamlets, cities|
|`localadmin`|local administrative boundaries|
|`borough`| a local administrative boundary, currently only used for New York City|
|`neighbourhood`|social communities, neighbourhoods|
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
> [/v1/autocomplete?api_key=mapzen-xxxxxx&__layers=coarse__&text=starbuck](https://search.mapzen.com/v1/autocomplete?layers=coarse&text=starbuck)
with `layers=coarse` you will see only administrative areas with names containing Starbuck
@ -117,6 +118,12 @@ with `layers=venue` you will see only the venues by that name
3) Starbucks, Austin, TX, USA
```
### Country
![Searching in a country](/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).
## Available autocomplete parameters
| Parameter | Type | Required | Default | Example |
@ -127,3 +134,4 @@ with `layers=venue` you will see only the venues by that name
| `focus.point.lon` | floating point number | no | none | `7.745843` |
| `sources` | string | no | all sources: osm,oa,gn,wof | openstreetmap,wof |
| `layers` | string | no | all layers: address,venue,neighbourhood,locality,borough,localadmin,county,macrocounty,region,marcoregion,country,coarse | address,venue |
| `boundary.country` | string | no | none | 'GBR' |

7
data-sources.md
Unescape View File

@ -29,8 +29,9 @@ Layers:
- `region`
- `macrocounty`
- `county`
- `locality`
- `localadmin`
- `locality`
- `borough`
- `neighbourhood`
- `coarse` (alias for simultaneously using all the above)
@ -56,6 +57,7 @@ Layers:
- `address`
- `venue`
- `street`
[OpenStreetMap](https://www.openstreetmap.org/) is a community-driven, editable map of the world. It prioritizes local knowledge and individual contributions over bulk imports, which often means it has excellent coverage even in remote areas where no large-scale mapping efforts have been attempted. OpenStreetMap contains information on landmarks, buildings, roads, and natural features.
@ -71,10 +73,11 @@ Layers:
- `venue`
- `country`
- `macroregion`
- `region`
- `county`
- `locality`
- `localadmin`
- `locality`
- `neighbourhood`
- `coarse` (alias for simultaneously using all the above)

11
get-started.md
Unescape View File

@ -1,11 +0,0 @@
# Get started with Mapzen Search
[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and powered entirely by open data. To start integrating Mapzen Search to your apps, you need an [API key](api-keys-rate-limits.md). You might use this functionality in any app that has a geographic part, including ones that deliver goods, locate hotels or venues, or even provide local weather forecasts.
Through a process known as [geocoding](search.md), Mapzen Search allows you to use natural language to find a particular place by entering an address or the name of a landmark or business, and then translates the result in to the geographic coordinates used by computers. Mapzen Search accesses [global databases](data-sources.md) of place names and locations, but you can receive more locally relevant search results by limiting the search to a particular radius around a location (such as a cell phone), region, or country. With text [autocompletion capabilities](autocomplete.md), you can search for places and match against Mapzen Search data in real-time.
Mapzen Search also enables the opposite workflow, known as [reverse geocoding](reverse.md), to transform latitude and longitude values in to a list of places. This process attempts to find the name and address of the place nearest a longitude and latitude pair. For example, you can click a position on the map to learn which business is located there.
Behind the scenes of your app, Mapzen Search can improve the quality of your own data by augmenting it with information where your users are located. You can pass the coordinates returned from Mapzen Search to other services, such as [Mapzen Turn-by-Turn](https://mapzen.com/projects/valhalla) that enables navigation and routing directions between points. Mapzen Search can also convert a geographic coordinate pair into the administrative boundary hierarchy containing it, such as a from the neighbourhood to the local administrative area, and on up to the country level. Getting this information can be useful when filtering for places in non-geographic databases.
Mapzen Search is powered by Pelias, an experimental, community-focused geocoder from Mapzen, is available for both commercial and non-commercial purposes. The [source code](https://github.com/pelias/pelias) is open to view and change, and contributions are welcomed.

2
glossary.md
Unescape View File

@ -1,4 +1,4 @@
# Mapzen Search terminology
# Mapzen Search glossary
## Common search and geocoding terms

BIN
images/world_country.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 364 KiB

After

Width:  |  Height:  |  Size: 402 KiB

18
index.md
Unescape View File

@ -1,15 +1,15 @@
[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and powered entirely by open data. To start integrating Mapzen Search to your apps, you need a [Mapzen developer API key](api-keys-rate-limits.md). You might use this functionality in any app that has a geographic element, including ones that deliver goods, locate hotels or venues, or even provide local weather forecasts.
[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and powered entirely by open data. To start integrating Mapzen Search to your apps, you need a [Mapzen developer API key](api-keys-rate-limits.md). Through a process known as [geocoding](search.md), Mapzen Search allows you to use natural language to find a particular place by entering an address or the name of a landmark or business, and then translates the result in to the geographic coordinates used by computers.
Through a process known as [geocoding](search.md), Mapzen Search allows you to use natural language to find a particular place by entering an address or the name of a landmark or business, and then translates the result in to the geographic coordinates used by computers. Mapzen Search accesses [global databases](data-sources.md) of place names and locations, but you can receive more locally relevant search results by limiting the search to a particular radius around a location (such as a cell phone), region, or country. With text [autocompletion capabilities](autocomplete.md), you can search for places and match against Mapzen Search data in real-time.
Mapzen Search accesses [global databases](data-sources.md) of place names and locations, but you can receive more locally relevant search results by limiting the search to a particular radius around a location (such as a cell phone), region, or country. With text [autocompletion capabilities](autocomplete.md), you can search for places and match against Mapzen Search data in real-time.
Mapzen Search also enables the opposite workflow, known as [reverse geocoding](reverse.md), to transform latitude and longitude values in to a list of places. This process attempts to find the name and address of the place nearest a longitude and latitude pair. For example, you can click a position on the map to learn which business is located there.
## Features of Mapzen Search
- Forward geocoding to find a place by searching for an address or name
- Reverse geocoding to find what is located at a certain coordinate location
- Autocomplete to give real-time result suggestions without having to type the whole location
- Global coverage with prioritized local results
- Open-source software using open data sources
- Plug-in for embedding search in a [Leaflet-based](https://leafletjs.com/) map
- API with generous rate limits
- [Forward geocoding](search.md) to find a place by searching for an address or name
- [Reverse geocoding](reverse.md) to find what is located at a certain coordinate location
- [Autocomplete](autocomplete.md) to give real-time result suggestions without having to type the whole location
- [Global coverage with prioritized local results](data-sources.md)
- Open-source software using [open data sources](data-sources.md)
- [Plug-in for embedding search](https://mapzen.com/documentation/mapzen-js/search/) in a [Leaflet-based](http://leafletjs.com/) map
- API with [generous rate limits](api-keys-rate-limits.md)

20
installing.md
Unescape View File

@ -25,9 +25,9 @@ The steps for fully installing Pelias look like this:
In general, Pelias will require:
* A working [Elasticsearch](https://www.elastic.co/products/elasticsearch) 1.7 cluster. It can be on
* A working [Elasticsearch](https://www.elastic.co/products/elasticsearch) 2.3 cluster. It can be on
a single machine or across several
* [Node.js](https://nodejs.org/) 0.12 or newer (Node 4 or 5 is recommended)
* [Node.js](https://nodejs.org/) 0.12 or newer (Node 4 or 6 is recommended)
* Up to 100GB disk space to download and extract data
* Lots of RAM, 8GB is a good minimum. A full North America OSM import just fits in 16GB RAM
@ -61,7 +61,7 @@ instructions for downloading Geonames data automatically. Individual countries,
### OpenAddresses
The OpenAddresses project includes [numerous download options](https://results.openaddresses.io/),
all of which are `.zip` downloads. The full dataset is just over 3 gigabytes compressed, but there
all of which are `.zip` downloads. The full dataset is just over 6 gigabytes compressed, but there
are numerous subdivision options. In any case, the `.zip` files simply need to be extracted to a
directory of your choice, and Pelias can be configured to either import every `.csv` in that
directory, or only selected files.
@ -122,7 +122,7 @@ it eventually.
As may be evident from the dataset section above, importing all the data in all four supported datasets is
worthy of its own discussion. Current [full planet builds](https://pelias-dashboard.mapzen.com/pelias)
weigh in at over 300 million documents, and require about 140GB total storage in Elasticsearch.
weigh in at over 320 million documents, and require about 230GB total storage in Elasticsearch.
Needless to say, a full planet build is not likely to succeed on most personal computers.
Fortunately, because of services like AWS and the scalability of Elasticsearch, full planet builds
@ -245,19 +245,19 @@ configure admin lookup and deduplication for OpenAddresses.
### Install Elasticsearch
Other than requiring Elasticsearch 1.7, nothing special in the Elasticsearch setup is required for
Pelias, so please refer to the [official 1.7 install docs](https://www.elastic.co/guide/en/elasticsearch/reference/1.7/setup.html).
Other than requiring Elasticsearch 2.3, nothing special in the Elasticsearch setup is required for
Pelias, so please refer to the [official 2.3 install docs](https://www.elastic.co/guide/en/elasticsearch/reference/2.3/setup.html).
Newer versions of Elasticsearch are not supported.
Older versions of Elasticsearch are not supported.
Make sure Elasticsearch is running and connectable, and then you can continue with the Pelias
specific setup and importing. Using a plugin like [head](https://mobz.github.io/elasticsearch-head/)
or [Marvel](https://www.elastic.co/products/marvel) can help monitor Elasticsearch as you import
data.
If you're using a terminal, you can also search and/or monitor Elasticsearch using their [APIs.](https://www.elastic.co/guide/en/elasticsearch/reference/1.7/api-conventions.html)
If you're using a terminal, you can also search and/or monitor Elasticsearch using their [APIs.](https://www.elastic.co/guide/en/elasticsearch/reference/2.3/api-conventions.html)
**Note:** On large imports, Elasticsearch can be very sensitive to memory issues. Be sure to modify it's [heap size](https://www.elastic.co/guide/en/elasticsearch/guide/1.x/heap-sizing.html) from the default confiration to something more appropriate to your machine.
**Note:** On large imports, Elasticsearch can be very sensitive to memory issues. Be sure to modify it's [heap size](https://www.elastic.co/guide/en/elasticsearch/guide/2.x/heap-sizing.html) from the default confiration to something more appropriate to your machine.
### Set up the Elasticsearch Schema
@ -302,7 +302,7 @@ importers.
Depending on how much data you've imported, now may be a good time to grab a coffee. Without admin
lookup, the fastest speeds you'll see are around 10,000 records per second. With admin lookup,
expect around 800-1000 inserts per second.
expect around 800-2000 inserts per second.
### Start the API

4
place.md
Unescape View File

@ -9,13 +9,13 @@ These `gid` strings should not be built manually, but rather used directly as-is
For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap (OSM):
> [/v1/place?api_key=search-TeXrSTX&__ids=openstreetmap:venue:way:5013364__](https://search.mapzen.com/v1/place?api_key=search-TeXrSTX&ids=openstreetmap:venue:way:5013364)
> [/v1/place?api_key=mapzen-xxxxxx&__ids=openstreetmap:venue:way:5013364__](https://search.mapzen.com/v1/place?ids=openstreetmap:venue:way:5013364)
## 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 OpenStreetMap and the borough of Manhattan in Who's on First:
> [/v1/place?api_key=search-TeXrSTX&__ids=openstreetmap:venue:way:5013364,whosonfirst:borough:421205771__](https://search.mapzen.com/v1/place?api_key=search-TeXrSTX&ids=openstreetmap:venue:way:5013364,whosonfirst:borough:421205771)
> [/v1/place?api_key=mapzen-xxxxxx&__ids=openstreetmap:venue:way:5013364,whosonfirst:borough:421205771__](https://search.mapzen.com/v1/place?ids=openstreetmap:venue:way:5013364,whosonfirst:borough:421205771)
The results are returned in the order requested.

69
release-notes.md
Unescape View File

@ -1,3 +1,69 @@
## 19 September 2016
Another data-only release. Stay tuned for next week!
## 12 September 2016
* Get excited for the addition of ✨ __STREETS__ ✨! That's right, with this release Mapzen Search gets a brand new `street` layer, which contains OSM street centroids. With this addition, if we can't find the exact address you're looking for we'll return the street record. Stay tuned for an in-depth blog post in the next few days. 👏
## 7 September 2016
* Crikey! We noticed we weren't handling Australian province abbreviations, so we [added support for them in our labels](https://github.com/pelias/api/pull/638).
* Geonames ADM3 records now are [correctly listed as localadmins](https://github.com/pelias/geonames/pull/120), not venues.
* Our wonderful, now departed intern made sure [Germanic street names are consistently handled](https://github.com/pelias/openaddresses/pull/68) (previously, some would end in -strasse while others ended in the abbreviation -str).
* Records with a Who's on First [dependency](https://github.com/whosonfirst/whosonfirst-placetypes#dependency) now [have that dependency listed in API responses](https://github.com/pelias/api/pull/643).
## 22 August 2016
No changes in functionality at all, just the freshest data! We did clean up some tests and do other work only visible to developers and those who run their own Pelias instance, but nothing major.
Stay tuned for next week's release where we already have some nice changes queued up.
## 18 August 2016
* After much feedback we've added the [`boundary.country` parameter for autocomplete](https://github.com/pelias/api/pull/634)! It works just like the one on the search endpoint.
* To help make Leaflet maps display results better, we now use [use the `lbl:bbox` property on Who's on First records](https://github.com/pelias/whosonfirst/pull/122). This is useful for places like [San Francisco](https://en.wikipedia.org/wiki/Farallon_Islands) where the mathematical bounding box is bigger than people expect.
* The API was [incorrectly warning](https://github.com/pelias/api/pull/617) against using the `boundary.circle` parameter. Now it doesn't complain!
* We've added a new `/v1/nearby` endpoint that is currently in _early alpha_! There's no documentation, probably some bugs, and any part of the interface is still subject to change.
* Finally, we're now running Node.js 4 in production, rather than Node.js 0.12. For those running their own Pelias instance, be aware that we'll be dropping support for Node.js 0.12 in September. At first, things may work on Node.js 0.12, but we're very excited to finally start using ES2016, so that won't last too long.
## 8 August 2016
Incremental release resolving the final outstanding tasks in the Elasticsearch 2 upgrade.
We have registered a new website [http://pelias.io](http://pelias.io) which has information about the milstones we have planned for the current quarter.
* Elasticsearch 2+ does not support co-ordinate wrapping as it did prior to the 2 release. Some front-ends allow users to 'wrap' around the globe. Floats outside of the normal -90/+90 -180/+180 geographic coordinate ranges cause Elasticsearch to error. We added a function to the API which [unwraps these coordinates](https://github.com/pelias/api/pull/608); providing better compatibility with these tools.
- We added `borough` as a [possible layer for Geonames](https://github.com/pelias/api/pull/612)
- Since the beginning of the project the Elasticsearch `_index` name has always been hard-coded as 'pelias', the [index names configurable PRs](https://github.com/pelias/config/pull/30) allow this behaviour to be adjusted in your individual pelias config files.
- We [removed the focus.viewport API](https://github.com/pelias/api/pull/620) which was undocumented and never used outside of test suites.
## 2 August 2016
Another bigger than usual release, we had some ops related challenges to resolve after the update to Elasticsearch 2, as well as some data issues, but we also have some great improvements in store!
* We use more of the population data in Who's on First, which really helps more [relevant cities come up in searches](https://github.com/pelias/whosonfirst/pull/116).
* Searching for [only records in certain layers in Geonames](https://github.com/pelias/api/pull/573) now works! We keep adding better handling of Geonames data but sometimes our API code doesn't keep up with those changes.
* Labels now [include county names](https://github.com/pelias/api/pull/576) if there's no city (locality) info present. This helps with [addresses that are outside the bounds of any city](https://github.com/pelias/api/issues/575)
* Capitalization across all OpenAddresess records is now more consistent. We've tried to [properly capitalize all records that were either in all caps or all lowercase](https://github.com/pelias/openaddresses/pull/131). This is better in general, although there are certainly exceptions, and we welcome bug reports for those cases.
* Geonames records for New York City boroughs like Manhattan and Brooklyn are [now in the `borough`, rather than `locality` layer](https://github.com/pelias/geonames/pull/100). This makes them consistent with the records from Who's on First, which have been boroughs for some time.
* Addresses in the [Czech Republic](https://github.com/pelias/api/pull/594) now show the street name before the house number, in keeping with local customs
* When using the `/v1/place` endpoint, the source name can either be the full name or the [abbreviation](https://github.com/pelias/api/pull/574) (like the `sources` parameter to the search and autocomplete endpoints). We love saving people some typing :)
* We've made lots of internal changes like [reducing the size of our documents](https://github.com/pelias/model/pull/37), using a cleaner method to construct [layer filter queries](https://github.com/pelias/api/pull/580), removing dependencies on [packages we've deprecated](https://github.com/pelias/schema/pull/151), and allowing the Elasticsearch index name to be configured for both the [API](https://github.com/pelias/api/pull/595) and [schema](https://github.com/pelias/schema/pull/155) packages.
* In related internal changes news, we've also worked to make sure that all our code works with Node.js version 6, which was recently released! Support for Node.js 0.10, which is quite old and near end-of-life, is also starting to be removed.
We also have two **known issues** in this build:
* Some OpenAddresses records for the statewide data in Massachusetts, USA are incorrect. This is because of an issue [when changing data sources](https://github.com/openaddresses/openaddresses/pull/1892) that will be resolved in the next OpenAddresses build
* Geonames `localadmin` records, like the [City of New York](http://pelias.github.io/compare/#/v1/search%3Fsources=gn&layers=localadmin&text=city%20of%20new%20york) will have extra components in the label (in this case, "Brooklyn, New York"). The [fix for this](https://github.com/pelias/wof-admin-lookup/pull/53) is merged but was accidentally omitted from this build. Look forward to it next week!
## 07 July 2016
* **Big news:** We've finally [upgraded to Elasticsearch 2.3](https://github.com/pelias/pelias/issues/325)! This brings improved performance and more importantly sets us up for lots of improvements from the new features of Elasticsearch 2. Elasticsearch 1.7 is no longer supported.
* As part of the Elasticsearch 2 upgrade we've also improved a few edge cases for searching for numeric values, and with single character tokens. You can [read more](https://github.com/pelias/pelias/issues/325#issuecomment-230724630) in the Github issue for the upgrade.
* We've also fixed some lingering issues where a few places in Denmark were listed as [being part of Sweden](https://github.com/pelias/pelias/issues/368). This was due to the same data bug as mentioned in our recent [blog post](https://mapzen.com/blog/assult-on-copenhagen/).
* The OpenAddresses importer now has better [whitespace cleanup](https://github.com/pelias/openaddresses/pull/130), so there won't be any extra spaces in street names.
* We recently added data to new [layers](https://mapzen.com/documentation/search/search/#filter-by-data-type) in Geonames, but the API didn't know about it, and prevented you from searching for them. We [fixed it](https://github.com/pelias/api/pull/573).
## 13 June 2016
* Who's on First importer: records now use the label centroid if it's present. The previous behavior was to always use the center of the record's bounding box. In cases like [San Francisco](https://github.com/pelias/pelias/issues/356), this caused the record to not show up where people expect!
@ -34,7 +100,7 @@
## 08 April 2016
This release marks the official integration of the Mapzen `Who's on First` data set into Mapzen Search. This data is replacing `Quattroshapes` across the entire service. Any forward usage or references to `Quattroshapes` will be replaced with `WhosOnFirst`. This substitution allows us to fix long-standing encoding issues in administrative hierarchy place-names. We've also added a bounding box for individual features in the results, not only the all-encompassing bounding box at the top level of the geojson results. Also, the all-encompassing bounding box will extend to include the bounding boxes of all the features in the results, not only their centroids.
This release marks the official integration of the Mapzen `Who's on First` data set into Mapzen Search. This data is replacing `Quattroshapes` across the entire service. Any forward usage or references to `Quattroshapes` will be replaced with `WhosOnFirst`. This substitution allows us to fix long-standing encoding issues in administrative hierarchy place-names. We've also added a bounding box for individual features in the results, not only the all-encompassing bounding box at the top level of the geojson results. Also, the all-encompassing bounding box will extend to include the bounding boxes of all the features in the results, not only their centroids.
Another major improvement that many have been waiting for is the addition of more filters for the `/autocomplete` endpoint. Users can now ask `/autocomplete` to filter by `layers` and `sources`, as documented [here](https://mapzen.com/documentation/search/autocomplete/#available-autocomplete-parameters).
See the detailed list of changes below for more specifics.
@ -48,4 +114,3 @@ See the detailed list of changes below for more specifics.
* `gid` values have been added for each parent in the admin hierarchies of results.
* `/autocomplete` now allows filtering by `sources` and `layers`.
* Fixed a bug that allowed `/autocomplete` to accept the `size` parameter. The default and only size of `/autocomplete` results is now `10`, as originally intended.

4
response.md
Unescape View File

@ -99,8 +99,8 @@ By default, Mapzen Search results 10 places, unless otherwise specified. If you
| `text` | YMCA |
| `size` | 1 |
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&size=1)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?text=YMCA&size=1)
If you want 25 results, you can build the query where `size` is 25.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&size=25)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?text=YMCA&size=25)

26
reverse.md
Unescape View File

@ -14,7 +14,7 @@ With reverse geocoding with Mapzen Search, you can look up all sorts of informat
To get started with reverse geocoding, you need a [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=search-TeXrSTX&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471)
>[/v1/reverse?api_key=mapzen-xxxxxx&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?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.
@ -36,7 +36,7 @@ Parameter | Type | Required | Default | Example
A basic parameter for filtering is `size`, which is used to limit the number of results returned. In the earlier 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=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&___size=1___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&size=1)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=48.858268&point.lon=2.294471&___size=1___](https://search.mapzen.com/v1/reverse?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.
@ -51,7 +51,7 @@ By default, reverse geocoding returns results from any [data source](data-source
| [Who's on First](https://whosonfirst.mapzen.com) | `whosonfirst` | `wof` |
| [GeoNames](http://www.geonames.org/) | `geonames` | `gn` |
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&sources=osm)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?point.lat=48.858268&point.lon=2.294471&sources=osm)
### Filter by layers (data type)
@ -61,22 +61,26 @@ Without specifying further, reverse geocoding doesn't restrict results to a part
|----|----|
|`venue`|points of interest, businesses, things with walls|
|`address`|places with a street address|
|`street`|streets,roads,highways|
|`country`|places that issue passports, nations, nation-states|
|`macroregion`|a related group of regions. Mostly in Europe|
|`region`|states and provinces|
|`macrocounty`|a related group of counties. Mostly in Europe.|
|`county`|official governmental area; usually bigger than a locality, almost always smaller than a region|
|`locality`|towns, hamlets, cities|
|`localadmin`|local administrative boundaries|
|`borough`| a local administrative boundary, currently only used for New York City|
|`neighbourhood`|social communities, neighbourhoods|
|`coarse`|alias for simultaneously using `country`, `region`, `county`, `locality`, `localadmin`, and `neighbourhood`|
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&layers=locality)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?point.lat=48.858268&point.lon=2.294471&layers=locality)
### 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=search-TeXrSTX&point.lat=47.270521&point.lon=9.530846&___boundary.country=LIE___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=47.270521&point.lon=9.530846&boundary.country=LIE)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=47.270521&point.lon=9.530846&___boundary.country=LIE___](https://search.mapzen.com/v1/reverse?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.
@ -98,16 +102,16 @@ Distance from `point.lat`/`point.lon` | Confidence score
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=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493)
* Only OpenStreetMap results near the Tower of London
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&sources=osm)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&sources=osm)
* Only street addresses near the Tower of London
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&layers=address)
* Only OpenStreetMap street addresses near the Tower of London
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://search.mapzen.com/v1/reverse?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=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1)

36
search.md
Unescape View File

@ -9,7 +9,7 @@ Making the leap from text to coordinates is an intricate and challenging process
All Mapzen Search requests share the same format:
```
https://search.mapzen.com/v1/search?text=London&api_key=search-xxxxxx
https://search.mapzen.com/v1/search?text=London&api_key=mapzen-xxxxxx
\___/ \_______________/\__/\_____/\__________/\___________________/
| | / | | |
scheme domain version path query authentication token
@ -23,7 +23,7 @@ In the simplest search, you can provide only one parameter, the text you want to
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=search-TeXrSTX&___text=YMCA___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA)
> [/v1/search?api_key=mapzen-xxxxxx&___text=YMCA___](https://search.mapzen.com/v1/search?text=YMCA)
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 earlier search to the following:
> [/v1/search?api_key=search-TeXrSTX&___text=yMcA___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=yMcA)
> [/v1/search?api_key=mapzen-xxxxxx&___text=yMcA___](https://search.mapzen.com/v1/search?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.
@ -65,11 +65,11 @@ By default, Mapzen Search results 10 places, unless otherwise specified. If you
| `text` | YMCA |
| `size` | 1 |
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&size=1)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?text=YMCA&size=1)
If you want 25 results, you can build the query where `size` is 25.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&size=25)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?text=YMCA&size=25)
## Narrow your search
@ -83,7 +83,7 @@ Sometimes your work might require that all the search results be from a particul
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=search-TeXrSTX&text=YMCA&___boundary.country=GBR___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&boundary.country=GBR)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___boundary.country=GBR___](https://search.mapzen.com/v1/search?text=YMCA&boundary.country=GBR)
| parameter | value |
| :--- | :--- |
@ -106,7 +106,7 @@ Note that all the results are within Great Britain:
If you try the same search request with different country codes, the results change to show YMCA locations within this region.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___boundary.country=USA___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&boundary.country=USA)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___boundary.country=USA___](https://search.mapzen.com/v1/search?text=YMCA&boundary.country=USA)
Results in the United States:
@ -131,7 +131,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/).
> [/v1/search?api_key=search-TeXrSTX&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-TeXrSTX&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=mapzen-xxxxxx&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?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 |
| :--- | :--- |
@ -161,7 +161,7 @@ Sometimes you don't have a rectangle to work with, but rather you have a point o
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` is 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=search-TeXrSTX&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-TeXrSTX&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://search.mapzen.com/v1/search?api_key=mapzen-xxxxxx&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35)
| parameter | value |
| :--- | :--- |
@ -197,7 +197,7 @@ By specifying a `focus.point`, nearby places will be scored higher depending on
To find YMCA again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use `focus.point`.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
| parameter | value |
| :--- | :--- |
@ -226,7 +226,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.
> [/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-TeXrSTX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
| parameter | value |
| :--- | :--- |
@ -253,7 +253,7 @@ The results below look different from the ones you saw before with only a focus
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=search-TeXrSTX&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-TeXrSTX&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=mapzen-xxxxxx&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?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 |
| :--- | :--- |
@ -295,7 +295,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.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___sources=oa___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&sources=oa)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___sources=oa___](https://search.mapzen.com/v1/search?text=YMCA&sources=oa)
| parameter | value |
| :--- | :--- |
@ -318,7 +318,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.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___sources=osm,gn___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&sources=oa)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___sources=osm,gn___](https://search.mapzen.com/v1/search?text=YMCA&sources=oa)
| parameter | value |
| :--- | :--- |
@ -335,15 +335,19 @@ In Mapzen Search, place types are referred to as `layers`, ranging from fine to
|----|----|
|`venue`|points of interest, businesses, things with walls|
|`address`|places with a street address|
|`street`|streets,roads,highways|
|`country`|places that issue passports, nations, nation-states|
|`macroregion`|a related group of regions. Mostly in Europe|
|`region`|states and provinces|
|`macrocounty`|a related group of counties. Mostly in Europe.|
|`county`|official governmental area; usually bigger than a locality, almost always smaller than a region|
|`locality`|towns, hamlets, cities|
|`localadmin`|local administrative boundaries|
|`borough`| a local administrative boundary, currently only used for New York City|
|`neighbourhood`|social communities, neighbourhoods|
|`coarse`|alias for simultaneously using `country`, `region`, `county`, `locality`, `localadmin`, and `neighbourhood`|
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___layers=venue,address___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&layers=venue,address)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___layers=venue,address___](https://search.mapzen.com/v1/search?text=YMCA&layers=venue,address)
| parameter | value |
| :--- | :--- |

10
transition-from-beta.md
Unescape View File

@ -16,7 +16,7 @@ Mapzen Search API keys allow you:
* 6 requests per second
* 30,000 requests per 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).
To start using an API key, append `&api_key=mapzen-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, such as in this example:
@ -126,7 +126,7 @@ 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=<search-xxxxxx>`
`https://search.mapzen.com/v1/search?text=<search-text>&layers=coarse&api_key=<mapzen-xxxxxx>`
You can also call the coarse layers directly, namely, `country`, `region`, `county`, `locality`, `neighbourhood`, to restrict the kinds of results you'll get back.
@ -154,7 +154,7 @@ The `/autocomplete` endpoint serves as a renamed `/suggest` to show that these a
Reverse geocoding finds the places closest to geospatial coordinates.
```
https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&api_key=search-xxxxxx
https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&api_key=mapzen-xxxxxx
```
Used to be (Beta) | New parameter (V1) | New behavior (if any) |
@ -169,7 +169,7 @@ New parameters:
### 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=search-xxxxxx
```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&layers=coarse&api_key=mapzen-xxxxxx
```
## `/place` (formerly `/doc`)
@ -177,7 +177,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:
```
https://search.mapzen.com/v1/place?ids=geonames:3544:adm1:fr:fra:paris&api_key=search-xxxxxx
https://search.mapzen.com/v1/place?ids=geonames:3544:adm1:fr:fra:paris&api_key=mapzen-xxxxxx
```
## Security

4
use-cors.md
Unescape View File

@ -27,7 +27,7 @@ $.ajax({
dataType: "json",
data: {
"text": "London, UK",
"api_key": "search-EEgHGcM"
"api_key": "mapzen-xxxxxx"
},
success: function( data, status, jqxhr ){
console.log( "Request received:", data );
@ -49,7 +49,7 @@ $http({
headers: { "Accept": "application/json" },
params: {
"text": "London, UK",
"api_key": "search-EEgHGcM"
"api_key": "mapzen-xxxxxx"
},
})
.success(function( data, status ) {

Write Preview
Loading…
Cancel
Save