Merge pull request #146 from pelias/doc-fest-edits

Doc fest edits for Search

api-keys-rate-limits.md

@@ -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.

autocomplete.md

@@ -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
 

get-started.md

@@ -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.

glossary.md

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

index.md

@@ -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](http://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)