From 51a2b5ce13eee581dcd87c415fb8a8a1f47ddd30 Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Fri, 4 Mar 2016 17:29:49 -0500
Subject: [PATCH 01/27] Retext Simplified Documentation

Simplifies documentation language based on [retext-mapbox-standard](https://github.com/mapbox/retext-mapbox-standard).

There are still several things that don't pass linter muster, but they're key terms for the product (namely "prioritize").
---
 add-search-to-a-map.md  | 18 +++++++++---------
 api-keys-rate-limits.md |  8 ++++----
 autocomplete.md         |  6 +++---
 data-sources.md         |  6 +++---
 get-started.md          |  6 +++---
 glossary.md             | 10 +++++-----
 http-status-codes.md    |  2 +-
 index.md                |  4 ++--
 place.md                |  4 ++--
 response.md             |  6 +++---
 reverse.md              |  6 +++---
 search.md               | 18 +++++++++---------
 transition-from-beta.md |  8 ++++----
 use-cors.md             |  8 ++++----
 14 files changed, 55 insertions(+), 55 deletions(-)

diff --git a/add-search-to-a-map.md b/add-search-to-a-map.md
index 6e477ab..ba6c368 100644
--- a/add-search-to-a-map.md
+++ b/add-search-to-a-map.md
@@ -1,14 +1,14 @@
 # Add the Mapzen Search geocoder to a map
 
-[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and open data. Use this functionality to enhance any app that has a geographic context, such as ones that assist in delivering goods, locating hotels or venues, or providing local weather forecasts.
+[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and open data. Use this functionality to enhance any app that has a geographic context, such as ones that help in delivering goods, locating hotels or venues, or providing local weather forecasts.
 
 Through a process known as [geocoding](https://en.wikipedia.org/wiki/Geocoding), Mapzen Search allows you to enter an address or the name of a landmark or business, and the service translates the result into geographic coordinates for mapping. Mapzen Search is built on [Pelias](https://github.com/pelias), an open-source geocoding project.
 
-In this walkthrough, you will learn how to make a map with a search box that allows you to enter addresses and place names and locate them on a map. To complete the tutorial, you should have some familiarity with HTML and JavaScript, although all the source code is provided. You also need a Mapzen Search [API key](https://mapzen.com/developers), which requires a [GitHub account](https://help.github.com/articles/signing-up-for-a-new-github-account/) for authorization. You can use any text editor and operating system, but must maintain an Internet connection while you are working.
+In this walkthrough, you will learn how to make a map with a search box that allows you to enter addresses and place names and locate them on a map. To complete the tutorial, you should have some familiarity with HTML and JavaScript, although all the source code is provided. You also need a Mapzen Search [API key](https://mapzen.com/developers), which requires a [GitHub account](https://help.github.com/articles/signing-up-for-a-new-github-account/) for authorization. You can use any text editor and operating system, but must keep an Internet connection while you are working.
 
 ## Sign up for a Mapzen Search API key
 
-To use the geocoding service, you must first obtain a Mapzen Search [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.
+To use the geocoding service, you must first get a Mapzen Search [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.
@@ -76,7 +76,7 @@ A cascading style sheet (CSS) is used to style a webpage, including layout and f
     <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet/0.7.5/leaflet.js"></script>
     ```
 
-2. In the `<head>` section, immediately after the lines you added for Leaflet, add references to the geocoder's CSS and JavaScript files. These are also being linked to on a website.
+2. In the `<head>` section, directly after the lines you added for Leaflet, add references to the geocoder's CSS and JavaScript files. These are also being linked to on a website.
 
     ```html
     <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.4.0/leaflet-geocoder-mapzen.css">
@@ -109,7 +109,7 @@ Note that you are linking to a website that is serving the geocoder's CSS and Ja
 
 To display a Leaflet map on a page, you need a `<div>` element, which is a container on the page that groups elements, with an ID value. If you want to know more about initializing a Leaflet map, see the [Leaflet getting started documentation](http://leafletjs.com/examples/quick-start.html).
 
-1. At the bottom of the `<head>` section, after the references you added in the previous steps, add a `<style>` tag and the following attributes to set the size of the map on your webpage.
+1. At the bottom of the `<head>` section, after the references you added in the earlier steps, add a `<style>` tag and the following attributes to set the size of the map on your webpage.
 
     ```html
     <style>
@@ -128,7 +128,7 @@ To display a Leaflet map on a page, you need a `<div>` element, which is a conta
     <div id="map"></div>
     ```
 
-3. Immediately after the `<div>`, add this JavaScript code within a `<script>` tag to initialize Leaflet.
+3. Directly after the `<div>`, add this JavaScript code within a `<script>` tag to initialize Leaflet.
 
     ```html
     <script>
@@ -136,7 +136,7 @@ To display a Leaflet map on a page, you need a `<div>` element, which is a conta
     </script>
     ```
 
-    `L.xxxxx` is a convention used with the Leaflet API. The `setView([37.804146, -122.275045], 16)` part sets the center of the map, in decimal degrees, and the zoom level. The map is centered in Oakland, California, with a zoom level that allows you to see the streets and features of the city. Zoom levels are similar to map scales or resolutions, where a smaller value shows a larger area in less detail, and a larger zoom level value depicts smaller area in great detail.
+    `L.xxxxx` is a convention used with the Leaflet API. The `setView([37.804146, -122.275045], 16)` part sets the center of the map, in decimal degrees, and the zoom level. The map is centered in Oakland, California, with a zoom level that allows you to see the streets and features of the city. Zoom levels are like map scales or resolutions, where a smaller value shows a larger area in less detail, and a larger zoom level value depicts smaller area in great detail.
 
 4. Within the same `<script>` tag, start a new line and set the data source for the map. This line adds the default OpenStreetMap tiles and an attribution.
 
@@ -231,13 +231,13 @@ Your `<body>` section should look like this:
 
 If you want to [customize the geocoder plug-in behavior](https://github.com/pelias/leaflet-geocoder#customizing-the-plugin) beyond the defaults in this Walkthrough, you can set additional options in your code. For example, the Search box collapses to an icon by default, but you can specify that the text box be shown at full width. There are also options for customizing the parameters for the Mapzen Search service, such as limiting the search to the map's extent or prioritizing results near the current view. Right now, you may notice that results from around the world appear in the list.
 
-Mapzen Search uses a [variety of open data sources](https://mapzen.com/documentation/search/data-sources/), including OpenStreetMap. Part of the power of open data is that anyone can modify the source data and improve the quality for everyone. If you are unable to find a location, the place could be missing or incorrect in the source datasets. Mapzen is also building a comprehensive, open database of places known as [Who's on First](https://github.com/whosonfirst/whosonfirst-data) that can be publicly edited, and is working on integrating it into the geocoder.  
+Mapzen Search uses a [variety of open data sources](https://mapzen.com/documentation/search/data-sources/), including OpenStreetMap. Part of the power of open data is that anyone can change the source data and improve the quality for everyone. If you are unable to find a location, the place could be missing or incorrect in the source datasets. Mapzen is also building a comprehensive, open database of places known as [Who's on First](https://github.com/whosonfirst/whosonfirst-data) that can be publicly edited, and is working on integrating it into the geocoder.  
 
 ## Walkthrough summary
 
 In this walkthrough, you learned the basics of adding the Mapzen Search geocoding engine to a Leaflet map. If you want to learn more about Mapzen Search, review the [documentation](index.md).
 
-Because the geocoder is still under development and considered experimental, if you are getting unexpected search results, please add an issue to the [Pelias GitHub repository](https://github.com/pelias/pelias/issues). The developers can investigate and determine if the problem is caused by software or data, and work to fix it either way.
+Because the geocoder is still under development and considered experimental, if you are getting unexpected search results, please add an issue to the [Pelias GitHub repository](https://github.com/pelias/pelias/issues). The developers can investigate and decide if the problem is caused by software or data, and work to fix it either way.
 
 To take your map even further, you can follow along with some additional Mapzen tutorials. One exercise you can try is to use [Mapzen's Tangram rendering engine](https://mapzen.com/documentation/turn-by-turn/add-routing-to-a-map/#add-a-tangram-map-to-the-frame) and vector tiles to draw the data on the map, instead of the OpenStreetMap raster tile layer you used in this walkthrough. When you get your map the way you want, you might be interested in [putting your map on the web](https://mapzen.com/documentation/tangram/walkthrough/#put-your-tangram-map-on-the-web) so you can share your work with others.
 
diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md
index d2976b0..7b191a3 100644
--- a/api-keys-rate-limits.md
+++ b/api-keys-rate-limits.md
@@ -1,8 +1,8 @@
 # API keys and rate limits
 
-## Obtain an API key
+## Get 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.
+To use the Mapzen Search service, you must first get 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.
@@ -10,7 +10,7 @@ To use the Mapzen Search service, you must first obtain a free developer API key
 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.
+Because Mapzen Search is a free, shared service, there are limitations on the numbers of requests to prevent individual users from degrading system performance.
 
 Mapzen Search allows you a maximum of:
 
@@ -54,4 +54,4 @@ If you exceed your limits, the service will respond with the status code `429 To
 ```
 
 ## 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.
+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.
diff --git a/autocomplete.md b/autocomplete.md
index d3d0f8d..5b9bbf7 100644
--- a/autocomplete.md
+++ b/autocomplete.md
@@ -1,6 +1,6 @@
 # Search with autocomplete
 
-If you are building an end-user application, you can use the `/autocomplete` endpoint alongside `/search` to enable real-time feedback. This type-ahead functionality helps users find what they are looking for more easily, without requiring them to fully specify their search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list below.
+If you are building an end-user application, you can use the `/autocomplete` endpoint alongside `/search` to enable real-time feedback. This type-ahead functionality helps users find what they are looking for, without requiring them to fully specify their search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list below.
 
 To build a query with autocomplete, you need [a free, API developer key](https://mapzen.com/developers) and a `text` parameter, representing what a user has typed into your application so far. Optionally, you can specify a geographic point where the search is focused, this will allow users to see more local places in the results.
 
@@ -8,9 +8,9 @@ To build a query with autocomplete, you need [a free, API developer key](https:/
 
 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 frequently 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.** 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/)
 
-**Responses are asynchronous.** There is no guarantee that 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. You must account for this behavior by storing the `requested_at` timestamps for each request and discarding older responses when they arrive late.
 
 ## Global scope, local focus
 
diff --git a/data-sources.md b/data-sources.md
index da1b15e..df22b8e 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -28,15 +28,15 @@ Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2.
 
 ## OpenAddresses
 
-[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with currently over 200 million addresses. OpenAddresses data comes exclusively from regional authorities such as federal, state, or local governments. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses.
+[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses.
 
-OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (i.e. no building names or other metadata), it's a great resource for global geocoding.
+OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
 
 As OpenAddresses is sourced from regional governments, its data is in the public domain.
 
 ## Geonames
 
-[Geonames](http://www.geonames.org/) is an aggregation of numerous authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. While Geonames does not contain any shape data (such as country borders), it does have a powerful and well defined hierarchy to describe the relationships between different records. Currently, this custom hierarchy makes it harder to use in combination with data from other sources, but the Mapzen [Who's On First](http://whosonfirst.mapzen.com/) project will help by providing concordance between Geonames and other datasets.
+[Geonames](http://www.geonames.org/) is an aggregation of many authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. While Geonames does not contain any shape data (such as country borders), it does have a powerful and well defined hierarchy to describe the relationships between different records. This custom hierarchy makes it harder to use in combination with data from other sources, but the Mapzen [Who's On First](http://whosonfirst.mapzen.com/) project will help by providing concordance between Geonames and other datasets.
 
 In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search.
 
diff --git a/get-started.md b/get-started.md
index 34ab151..fc32aba 100644
--- a/get-started.md
+++ b/get-started.md
@@ -1,11 +1,11 @@
 # 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 a [free, developer API key](api-keys-rate-limits.md). You might use this functionality in any app that has a geographic component, 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 [free, developer 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. 
+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 modify, and contributions are welcomed.
+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.
diff --git a/glossary.md b/glossary.md
index 14f8d42..a619fcf 100644
--- a/glossary.md
+++ b/glossary.md
@@ -2,16 +2,16 @@
 
 ## Common search and geocoding terms
 
-- **geocoding** - the process of converting an address or the name of a landmark or business into a latitude, longitude pair. Sometimes referred to as forward geocoding. Use the `search` endpoint to perform this.
-- **reverse geocoding** - the process of converting a latitude, longitude pair into the name and address of the nearest place. Use the `reverse` endpoint to perform this.
+- **geocoding** - the process of converting an address or the name of a landmark or business into a latitude, longitude pair. Sometimes referred to as forward geocoding. Use the `search` endpoint to do this.
+- **reverse geocoding** - the process of converting a latitude, longitude pair into the name and address of the nearest place. Use the `reverse` endpoint to do this.
 - **coarse geocoding** - adds regions and administrative boundaries to the geocoding process. Forward coarse geocoding limits a search to a particular region, while reverse coarse geocoding converts 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.
 - **gazetteer** - a directory of geographical places, with a stable identifier and some number of descriptive properties about that location.
 
 ## Mapzen Search API and developer terms
 
 - **API endpoint** - an architectural style for accessing web resources through a URL. In Mapzen Search, available endpoints include `search`, `reverse`, and `autocomplete`. You can construct a URL to send queries and receive responses from Mapzen Search.
-- **API key** - an code that identifies the developer account without providing a password. Mapzen Search requires the use of a free, API key to interact with the search service.
-- **autocomplete** - enables real-time feedback when entering text for a search, typically, where users start typing and a drop-down list appears where they can choose the term from the list below. Use the `autocomplete` endpoint to perform this.
+- **API key** - an code that identifies the developer account without providing a password. Mapzen Search requires a free, API key to interact with the search service.
+- **autocomplete** - enables real-time feedback when entering text for a search, typically, where users start typing and a drop-down list appears where they can choose the term from the list below. Use the `autocomplete` endpoint to do this.
 - **data source** - the datasets available to Mapzen Search. Only data sources that have open-source licenses are used.
 - **focus** - option to make places closer to a particular location be prioritized and appear higher in the search results list. After all nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization.
 - **layer** - types of places available to Mapzen Search and arranged in a hierarchy, such as an address, a venue, a neighbourhood, or a country.
@@ -22,4 +22,4 @@
 - **bounding box** - a rectangular area defined by two longitudes and two latitudes (the minimum and the maximum latitude, longitude).
 - **cross-origin resource sharing (CORS)** - standard allowing a web browser and server to accept requests across domains. Without CORS, browsers may not allow cross-site requests because they could be malicious.
 - **latitude** - the distance of a point north or south of the equator. In Mapzen Search, latitudes are expressed in decimal degrees.
-- **longitude** - the distance of a point east or west. In Mapzen Search, longitudes are reported in relation to the Prime Meridian and expressed in decimal degrees.
+- **longitude** - the distance of a point east or west. In Mapzen Search, longitudes are in relation to the Prime Meridian and expressed in decimal degrees.
diff --git a/http-status-codes.md b/http-status-codes.md
index c72364f..f817b88 100644
--- a/http-status-codes.md
+++ b/http-status-codes.md
@@ -11,7 +11,7 @@ The following status codes are returned from the geocoding service:
 - `500 Internal Server Error`: Generic fatal error.
 - `502 Bad Gateway`: Connection was lost to the Elasticsearch cluster.
 
-In all cases above, the response body will be valid geoJSON.
+In all cases above, the response body will be valid GeoJSON.
 
 ## Rate limiter
 The rate limiter returns the status codes `403 Forbidden` and `429 Too Many Requests`.
diff --git a/index.md b/index.md
index 24a2eee..71d3332 100644
--- a/index.md
+++ b/index.md
@@ -1,5 +1,5 @@
-[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 [developer API key](api-keys-rate-limits.md). You might use this functionality in any app that has a geographic component, 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 [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.
 
-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. 
+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.
diff --git a/place.md b/place.md
index d8e51b8..93defdd 100644
--- a/place.md
+++ b/place.md
@@ -8,7 +8,7 @@ To get started with a `/place` search, you need a [free, developer API key](http
 * layer - the type of place, such as a venue, address, or country.
 * id - the identification number of the item
 
-If you have all of those, join them together with semicolons and pass them in with the `ids` parameter.
+If you have all those, join them together with semicolons and pass them in with the `ids` parameter.
 
 For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap (OSM):
 
@@ -24,7 +24,7 @@ The results are returned in the order requested.
 
 One reason you'd want to do this is to exclude a particular dataset from being searched; you would include all the other data sources you do want to search.
 
-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.
+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 JSON does not allow a 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
 
diff --git a/response.md b/response.md
index d9d329e..a38a391 100644
--- a/response.md
+++ b/response.md
@@ -19,7 +19,7 @@ The top-level structure to every response looks like this:
 
 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.
+Each item in this list will contain all the information needed to find it in human-readable format in the `properties` block, as well as computer friendly coordinates in the `geometry` property.
 
 ```json
 {
@@ -59,7 +59,7 @@ Each item in this list will contain all the information needed to identify it in
 This is a "global id" that can be used to reference a result with the [/place](place.md) endpoint. It consists of an identifier for the dataset, a layer, and finally an `id` for the individual record. This `id` corresponds to stable ids from datasets wherever possible (such as the ID of an OpenStreetMap Node or Way), but not all datasets have them.
 
 ### Label
-The `label` is a human-friendly representation of the place, ready to be displayed to an end user.  The label field attempts to use a format that is appropriate for the region the result is in, although Mapzen Search only supports a few countries at the moment.
+The `label` is a human-friendly representation of the place, ready to be displayed to an end user.  The label field attempts to use a format that is right for the region the result is in, although Mapzen Search only supports a few countries at the moment.
 
 ### Confidence
 The confidence score is an estimation of how accurately this result matches the query.
@@ -68,7 +68,7 @@ For the `/reverse` endpoint, the confidence score is determined solely by its di
 
 For the `/search` endpoint, it primarily takes into account how well properties in the result match what was expected from parsing the input text. For example, if the input text looks like an address, but the house number of the result doesn't match the house number that was parsed from the input text, the confidence score will be lower.
 
-Additionally, the confidence score can optionally be biased relative to other results, just like test scores in a classroom might be graded on a curve. This takes into account both the property matches described above and the distance between results. This relative scoring is enabled on Mapzen Search, but can be disabled when hosting your own Pelias instance.
+Additionally, the confidence score can optionally be biased along with other results, like test scores in a classroom might be graded on a curve. This takes into account both the property matches described above and the distance between results. This relative scoring is enabled on Mapzen Search, but can be turned off when hosting your own Pelias instance.
 
 ## Result count
 
diff --git a/reverse.md b/reverse.md
index df8fde9..8c00026 100644
--- a/reverse.md
+++ b/reverse.md
@@ -20,7 +20,7 @@ Notice that the first result is the Eiffel Tower (well, Tour Eiffel). The output
 
 ## Reverse geocoding parameters
 
-Similar to other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results.
+Like other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results.
 
 Parameter | Type | Required | Default | Example
 --- | --- | --- | --- | ---
@@ -34,7 +34,7 @@ Parameter | Type | Required | Default | Example
 
 ### 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:
+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-XXXXXXX&point.lat=48.858268&point.lon=2.294471&___size=1___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&size=1)
 
@@ -62,7 +62,7 @@ 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.
+Each result returned has an associated confidence score. 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
 --- | ---
diff --git a/search.md b/search.md
index 95f7576..e42fd87 100644
--- a/search.md
+++ b/search.md
@@ -19,7 +19,7 @@ All Mapzen Search requests share the same format:
 
 ![Searching globally](/images/world_all.png)
 
-In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To accomplish this, build a query where the `text` parameter is set to the item you want to find.
+In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To do 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`.
 
@@ -49,7 +49,7 @@ In the example above, you will find the name of each matched locations in a prop
 * 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:
+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-XXXXXXX&___text=yMcA___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=yMcA)
 
@@ -74,7 +74,7 @@ If you want 25 results, you can build the query where `size` is 25.
 
 ## 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.
+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 supports three types: country, rectangle, and circle.
 
 ### Search within a particular country
 
@@ -92,7 +92,7 @@ Now, you want to search for YMCA again, but this time only in Great Britain. To
 | `text` | YMCA |
 | `boundary.country` | GBR |
 
-Note that all the results reside within Great Britain:
+Note that all the results are within Great Britain:
 
 > * YMCA, Bargoed Community, United Kingdom
 * YMCA, Orpington, Greater London
@@ -105,7 +105,7 @@ Note that all the results reside within Great Britain:
 * 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.
+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-XXXXXXX&text=YMCA&___boundary.country=USA___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&boundary.country=USA)
 
@@ -185,7 +185,7 @@ You can see the results have fewer than the standard 10 items because there are
 
 ![Searching within multiple regions](/images/overlapping_boundaries.gif)
 
-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.
+If you're going to try 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.
 
 ## 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.
@@ -237,7 +237,7 @@ Going back to the YMCA search you conducted with a focus around a point in Sydne
 | `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.
+The results below look different from the ones you saw before 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 helped by the focus parameter.
 
 > * YMCA, Redfern, New South Wales [distance: 3.836]
 * YMCA, St Ives (NSW), New South Wales [distance: 14.844]
@@ -285,7 +285,7 @@ With Mapzen Search, you can filter by:
 * `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:
+The search examples so far have returned a mix of results from all the data sources available to Mapzen Search. Here are the sources being searched:
 
 | source | name | short name |
 |---|---|---|
@@ -330,7 +330,7 @@ If you wanted to combine several data sources together, set `sources` to a comma
 Each of these data sources has properties, licenses, and strengths. You can learn more about the [data sources for Mapzen Search](data-sources.md).
 
 ### 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:
+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 help coarse geocoding. Here's a list of the types of places you could find in the results, sorted by granularity:
 
 |layer|description|
 |----|----|
diff --git a/transition-from-beta.md b/transition-from-beta.md
index d1dded8..58fb533 100644
--- a/transition-from-beta.md
+++ b/transition-from-beta.md
@@ -73,7 +73,7 @@ Most parameters (and options) for search have been renamed:
 | `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.
+`layers` used to be 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 help improve clarity.
 
 | Beta           |           V1 |       Represents |
 | -------------- | ------------ | ---------------- |
@@ -120,7 +120,7 @@ And the `sources` values are:
 | `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.
+Coarse search (looking for countries, regions, counties, localities, neighbourhoods), were 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>`
@@ -133,7 +133,7 @@ You can also call the coarse layers directly, namely, `country`, `region`, `coun
 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`:
+The `/autocomplete` endpoint serves as a renamed `/suggest` to show 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) |
 | ---------- | ------------- | --------------------- |
@@ -190,7 +190,7 @@ Instead, Mapzen Search supports [Cross-Origin Resource Sharing](https://develope
 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 (such as users' searches or users' location data).
+Mapzen Search continues to support HTTPS and traditional HTTP. We encourage you to use HTTPS instead of HTTP, especially when handling sensitive personal information (such as users' searches or users' location data).
 
 ## What's happening to pelias.mapzen.com?
 The beta API available at pelias.mapzen.com will be available 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.
diff --git a/use-cors.md b/use-cors.md
index 6adfa31..c250ce1 100644
--- a/use-cors.md
+++ b/use-cors.md
@@ -1,14 +1,14 @@
 # Load 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.
+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 the authentication context of the logged in user, so a malicious web page could try 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.
+`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 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.
+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 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
 
@@ -66,7 +66,7 @@ interactive demo: http://jsfiddle.net/missinglink/nchh8a9j/
 
 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.
+Instead of responding with 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.
 

From 2154359bcaa20ade85caaca1e3f6c81c1876b089 Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Thu, 24 Mar 2016 14:54:33 -0400
Subject: [PATCH 02/27] Adds sources parameter codes on Sources page

---
 data-sources.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/data-sources.md b/data-sources.md
index df22b8e..1f54b9c 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -4,6 +4,8 @@ Mapzen Search is powered by several major open data sets and owes a tremendous d
 
 ## OpenStreetMap
 
+`sources=openstreetmap` | `sources=osm`
+
 [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.
 
 With its coverage of roads as well as rich metadata, OpenStreetMap is arguably the most valuable dataset used by Mapzen Search for general usage.
@@ -12,6 +14,8 @@ All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/l
 
 ## Quattroshapes
 
+`sources=quattroshapes` | `sources=qs`
+
 [Quattroshapes](http://quattroshapes.com/) provides global coverage of location data for:
 
 - countries
@@ -28,6 +32,8 @@ Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2.
 
 ## OpenAddresses
 
+`sources=openaddresses` | `sources=osm`
+
 [OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses.
 
 OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
@@ -36,6 +42,8 @@ As OpenAddresses is sourced from regional governments, its data is in the public
 
 ## Geonames
 
+`sources=geonames` | `sources=gn`
+
 [Geonames](http://www.geonames.org/) is an aggregation of many authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. While Geonames does not contain any shape data (such as country borders), it does have a powerful and well defined hierarchy to describe the relationships between different records. This custom hierarchy makes it harder to use in combination with data from other sources, but the Mapzen [Who's On First](http://whosonfirst.mapzen.com/) project will help by providing concordance between Geonames and other datasets.
 
 In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search.

From d3911b97acd45d8167e783f2b30ba5ff723f142d Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Mon, 28 Mar 2016 13:26:11 -0400
Subject: [PATCH 03/27] Deprecates quattroshapes

---
 data-sources.md | 32 ++++++++++++++------------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/data-sources.md b/data-sources.md
index 1f54b9c..cb47fe2 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -12,24 +12,6 @@ With its coverage of roads as well as rich metadata, OpenStreetMap is arguably t
 
 All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/licenses/odbl/), a [share-alike](https://en.wikipedia.org/wiki/Share-alike) license which also requires attribution.
 
-## Quattroshapes
-
-`sources=quattroshapes` | `sources=qs`
-
-[Quattroshapes](http://quattroshapes.com/) provides global coverage of location data for:
-
-- countries
-- regions (states/provinces)
-- counties
-- localities (cities, towns, hamlets, villages)
-- neighborhoods (in many places)
-
-Originally assembled by Foursquare, Quattroshapes provides not only the organizational hierarchy for nearly any point or address worldwide (town > local government > province > country), but also the borders for each of these places.
-
-Mapzen Search uses data from Quattroshapes to apply a consistent hierarchy to our data from other sources, so you can be sure that points of interest have consistent data about the cities, regions, and countries in which they are located.
-
-Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2.0/), allowing its use for any purpose with proper attribution.
-
 ## OpenAddresses
 
 `sources=openaddresses` | `sources=osm`
@@ -49,3 +31,17 @@ As OpenAddresses is sourced from regional governments, its data is in the public
 In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search.
 
 Geonames data is licensed [CC BY](http://creativecommons.org/licenses/by/3.0/).
+
+
+# Deprecated Sources
+Certain data sources have previously been supported by Mapzen Search but are no longer offered part of the core service and have been superseded by a new data source.
+
+## Quattroshapes
+
+`sources=quattroshapes` | `sources=qs`
+
+Quattroshapes was previously used by Mapzen Search and its use was discontinued in April 2016.
+
+It has been replaced by Who's on First, which continues to provide global administrative place data (countries, regions, counties, cities) and administrative lookup (_"what country, region, and city is this address part of?"_).
+
+Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2.0/), allowing its use for any purpose with proper attribution.

From 29a1934c09622f5fb4b836e8845dfe45cc68e873 Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Mon, 28 Mar 2016 13:41:47 -0400
Subject: [PATCH 04/27] updated licenses for existing sources

---
 data-sources.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/data-sources.md b/data-sources.md
index cb47fe2..552abfc 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -2,6 +2,8 @@
 
 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.
 
+Attribution is required for many of our data providers. Some license information is provided, but you are responsible for researching each project to follow their license terms.
+
 ## OpenStreetMap
 
 `sources=openstreetmap` | `sources=osm`
@@ -20,7 +22,7 @@ All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/l
 
 OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
 
-As OpenAddresses is sourced from regional governments, its data is in the public domain.
+OpenAddresses is sourced from regional governments. Many of these sources require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses.html). Mapzen Search does not import OpenAddresses sources marked as Share-Alike by the OpenAddresses project.
 
 ## Geonames
 
@@ -30,7 +32,7 @@ As OpenAddresses is sourced from regional governments, its data is in the public
 
 In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search.
 
-Geonames data is licensed [CC BY](http://creativecommons.org/licenses/by/3.0/).
+Geonames data is licensed [CC-BY-3.0](http://creativecommons.org/licenses/by/3.0/).
 
 
 # Deprecated Sources
@@ -44,4 +46,4 @@ Quattroshapes was previously used by Mapzen Search and its use was discontinued
 
 It has been replaced by Who's on First, which continues to provide global administrative place data (countries, regions, counties, cities) and administrative lookup (_"what country, region, and city is this address part of?"_).
 
-Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2.0/), allowing its use for any purpose with proper attribution.
+Quattroshapes data is licensed [CC-BY-2.0](http://creativecommons.org/licenses/by/2.0/).

From 9172b1c0aaefac475c35487f1c1ee4b635997945 Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Mon, 28 Mar 2016 14:45:35 -0400
Subject: [PATCH 05/27] Adds WoF as a source

---
 data-sources.md | 36 +++++++++++++++++++++++++++---------
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/data-sources.md b/data-sources.md
index 552abfc..5ca019f 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -4,6 +4,33 @@ Mapzen Search is powered by several major open data sets and owes a tremendous d
 
 Attribution is required for many of our data providers. Some license information is provided, but you are responsible for researching each project to follow their license terms.
 
+## OpenAddresses
+
+`sources=openaddresses` | `sources=osm`
+
+[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses.
+
+OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
+
+OpenAddresses is sourced from regional governments. Many of these sources require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project.
+
+## Who's on First
+
+`sources=whosonfirst` | `sources=wof`
+
+[Who's on First](https://whosonfirst.mapzen.com) is an open data directory of worldwide "administrative places" created by Mapzen. It is our primary provider of:
+- Countries
+- Regions (e.g. States, Provinces)
+- Counties
+- Localities (cities, towns, hamlets)
+- Neighbourhoods
+
+Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonames, and OpenAddresses, we use Who's on First to provide standardized fields for the country, region, locality, and neighbourhood (in addition to any other matching levels the place may fall within like counties or macro-regions).
+
+[License](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md)
+
+
+
 ## OpenStreetMap
 
 `sources=openstreetmap` | `sources=osm`
@@ -14,15 +41,6 @@ With its coverage of roads as well as rich metadata, OpenStreetMap is arguably t
 
 All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/licenses/odbl/), a [share-alike](https://en.wikipedia.org/wiki/Share-alike) license which also requires attribution.
 
-## OpenAddresses
-
-`sources=openaddresses` | `sources=osm`
-
-[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses.
-
-OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
-
-OpenAddresses is sourced from regional governments. Many of these sources require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses.html). Mapzen Search does not import OpenAddresses sources marked as Share-Alike by the OpenAddresses project.
 
 ## Geonames
 

From 239883d54c1bdf4ebce02fbc6dabe6701523c4bb Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Mon, 28 Mar 2016 14:50:04 -0400
Subject: [PATCH 06/27] Adds layers to each source description

---
 data-sources.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/data-sources.md b/data-sources.md
index 5ca019f..7158322 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -8,6 +8,9 @@ Attribution is required for many of our data providers. Some license information
 
 `sources=openaddresses` | `sources=osm`
 
+Layers:
+- `address`
+
 [OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses.
 
 OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
@@ -18,6 +21,16 @@ OpenAddresses is sourced from regional governments. Many of these sources requir
 
 `sources=whosonfirst` | `sources=wof`
 
+Layers:
+- `country`
+- `region`
+- `county`
+- `locality`
+- `localadmin`
+- `neighbourhood`
+- `coarse` (alias for simultaneously using all of the above)
+
+
 [Who's on First](https://whosonfirst.mapzen.com) is an open data directory of worldwide "administrative places" created by Mapzen. It is our primary provider of:
 - Countries
 - Regions (e.g. States, Provinces)
@@ -35,6 +48,10 @@ Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonam
 
 `sources=openstreetmap` | `sources=osm`
 
+Layers:
+- `address`
+- `venue`
+
 [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.
 
 With its coverage of roads as well as rich metadata, OpenStreetMap is arguably the most valuable dataset used by Mapzen Search for general usage.
@@ -46,6 +63,16 @@ All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/l
 
 `sources=geonames` | `sources=gn`
 
+Layers:
+- `venue`
+- `country`
+- `region`
+- `county`
+- `locality`
+- `localadmin`
+- `neighbourhood`
+- `coarse` (alias for simultaneously using all of the above)
+
 [Geonames](http://www.geonames.org/) is an aggregation of many authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. While Geonames does not contain any shape data (such as country borders), it does have a powerful and well defined hierarchy to describe the relationships between different records. This custom hierarchy makes it harder to use in combination with data from other sources, but the Mapzen [Who's On First](http://whosonfirst.mapzen.com/) project will help by providing concordance between Geonames and other datasets.
 
 In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search.

From 8769be172bc97fe853cfafdbb6c5ca32d8f6a9b1 Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Tue, 29 Mar 2016 06:41:13 -0400
Subject: [PATCH 07/27] Search Page de-quattroshaped

Still outstanding:
- `layers` for macrocounty and macroregion?
---
 search.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/search.md b/search.md
index e42fd87..b960993 100644
--- a/search.md
+++ b/search.md
@@ -291,7 +291,7 @@ The search examples so far have returned a mix of results from all the data sour
 |---|---|---|
 | [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` |
 | [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` |
-| [Quattroshapes](http://quattroshapes.com/) | `quattroshapes` | `qs` |
+| [Who's on First](https://whosonfirst.mapzen.com) | 'whosonfirst' | 'wof' |
 | [GeoNames](http://www.geonames.org/) | `geonames` | `gn` |
 
 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.

From 9ac6d3754888b5a29ceccd604a0eb9e255fb1133 Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Tue, 29 Mar 2016 06:49:44 -0400
Subject: [PATCH 08/27] Reverse gets layers and sources list

---
 reverse.md | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/reverse.md b/reverse.md
index 8c00026..4974880 100644
--- a/reverse.md
+++ b/reverse.md
@@ -16,7 +16,7 @@ To get started with reverse geocoding, you need a [free, developer API key](http
 
 >[/v1/reverse?api_key=search-XXXXXXX&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&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.
+Notice that the first result is the Eiffel Tower (well, _Tour Eiffel_). The output is the standard GeoJSON format.
 
 ## Reverse geocoding parameters
 
@@ -44,12 +44,32 @@ The default value for `size` is `10` and the maximum value is `40`. Specifying a
 
 By default, reverse geocoding returns results from any [data source](data-sources.md) 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:
 
+| source | name | short name |
+|---|---|---|
+| [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` |
+| [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` |
+| [Who's on First](https://whosonfirst.mapzen.com) | 'whosonfirst' | 'wof' |
+| [GeoNames](http://www.geonames.org/) | `geonames` | `gn` |
+
 >[/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&sources=osm)
 
-### Filter by layers
+### Filter by layers (data type)
 
 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):
 
+|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|
+|`localadmin`|local administrative boundaries|
+|`neighbourhood`|social communities, neighbourhoods|
+|`coarse`|alias for simultaneously using `country`, `region`, `county`, `locality`, `localadmin`, and `neighbourhood`|
+
+
 >[/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&layers=locality)
 
 ### Filter by country
@@ -60,9 +80,9 @@ If you are performing a reverse geocode near a country boundary, and are only in
 
 Note that `UK` is not a valid ISO 3166-1 alpha-2 country code.
 
-## Confidence scores for the results
+## Distance Confidence scores for the results
 
-Each result returned has an associated confidence score. 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.
+Each result returned has a distance from the query point and an associated confidence score. 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
 --- | ---

From f39cd26ce2c0b18b7ce0f827f236c57b66223b9a Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Tue, 29 Mar 2016 07:01:44 -0400
Subject: [PATCH 09/27] response + reverse distance

---
 response.md | 70 ++++++++++++++++++++++++++++++-----------------------
 reverse.md  |  2 +-
 2 files changed, 41 insertions(+), 31 deletions(-)

diff --git a/response.md b/response.md
index a38a391..2743f30 100644
--- a/response.md
+++ b/response.md
@@ -23,45 +23,55 @@ Each item in this list will contain all the information needed to find it in hum
 
 ```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
+  "type": "Feature",
+  "geometry": {
+    "type": "Point",
+    "coordinates": [
+      -73.990425,
+      40.744131
     ]
+  },
+  "properties": {
+    "id": "way:265038872",
+    "gid": "openstreetmap:address:way:265038872",
+    "layer": "address",
+    "source": "openstreetmap",
+    "name": "30 West 26th Street",
+    "housenumber": "30",
+    "street": "West 26th Street",
+    "postalcode": "10010",
+    "confidence": 0.875,
+    "country": "United States",
+    "country_id": "85633793",
+    "country_a": "USA",
+    "region": "New York",
+    "region_id": "85688543",
+    "region_a": "NY",
+    "county": "New York County",
+    "county_id": "102081863",
+    "localadmin": "Manhattan",
+    "localadmin_id": "404522731",
+    "locality": "New York",
+    "locality_id": "85977539",
+    "neighbourhood": "Flatiron District",
+    "neighbourhood_id": "85869245",
+    "label": "30 West 26th Street, Manhattan, NY, USA"
   }
-}
 ```
 
+Additionally, `/reverse` queries will have a `distance` parameter, which is the distance, in meters, from the query point.
+
 ## Notable features
 
-### GID
-This is a "global id" that can be used to reference a result with the [/place](place.md) endpoint. It consists of an identifier for the dataset, a layer, and finally an `id` for the individual record. This `id` corresponds to stable ids from datasets wherever possible (such as the ID of an OpenStreetMap Node or Way), but not all datasets have them.
+### `gid`
+This is a "global id" that can be used to reference a result with the [/place](place.md) endpoint. It consists of an identifier for the dataset, a layer, and finally an `id` for the individual record. This `id` corresponds to stable ids from datasets wherever possible (such as the ID of an OpenStreetMap Node or Way). Not all datasets have stable ID's (in particular OpenAddresses records), so for OpenAddresses, we include the name of the source dataset in OpenAddresses as a part of the ID scheme.
+
+The `gid` is also used to retrieve full details on a particular result from the `place` endpoint. [Full details](place.md) on ID schemes are part of the `/place` endpoint.
 
-### Label
+### `label`
 The `label` is a human-friendly representation of the place, ready to be displayed to an end user.  The label field attempts to use a format that is right for the region the result is in, although Mapzen Search only supports a few countries at the moment.
 
-### Confidence
+### `confidence`
 The confidence score is an estimation of how accurately this result matches the query.
 
 For the `/reverse` endpoint, the confidence score is determined solely by its distance from the coordinate specified. Closer results get a higher score.
diff --git a/reverse.md b/reverse.md
index 4974880..b300701 100644
--- a/reverse.md
+++ b/reverse.md
@@ -82,7 +82,7 @@ Note that `UK` is not a valid ISO 3166-1 alpha-2 country code.
 
 ## Distance Confidence scores for the results
 
-Each result returned has a distance from the query point and an associated confidence score. 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.
+Each result returned has a distance from the query point (in meters) and an associated confidence score. 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
 --- | ---

From 0ec1bf3ec18486b845c971d08e80efdaf5cbcb3f Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Tue, 29 Mar 2016 16:15:52 -0400
Subject: [PATCH 10/27] Run through Retext. All same as before now passing

---
 data-sources.md | 12 ++++++------
 place.md        |  2 +-
 search.md       |  2 +-
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/data-sources.md b/data-sources.md
index 7158322..0fb411a 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -28,17 +28,17 @@ Layers:
 - `locality`
 - `localadmin`
 - `neighbourhood`
-- `coarse` (alias for simultaneously using all of the above)
+- `coarse` (alias for simultaneously using all the above)
 
 
 [Who's on First](https://whosonfirst.mapzen.com) is an open data directory of worldwide "administrative places" created by Mapzen. It is our primary provider of:
 - Countries
-- Regions (e.g. States, Provinces)
+- Regions (for example: States, Provinces)
 - Counties
 - Localities (cities, towns, hamlets)
 - Neighbourhoods
 
-Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonames, and OpenAddresses, we use Who's on First to provide standardized fields for the country, region, locality, and neighbourhood (in addition to any other matching levels the place may fall within like counties or macro-regions).
+Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonames, and OpenAddresses, we use Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. Other matching levels the place may fall within `macro-county` or `macro-region` taxonomy from Who's on Firsts.
 
 [License](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md)
 
@@ -71,7 +71,7 @@ Layers:
 - `locality`
 - `localadmin`
 - `neighbourhood`
-- `coarse` (alias for simultaneously using all of the above)
+- `coarse` (alias for simultaneously using all the above)
 
 [Geonames](http://www.geonames.org/) is an aggregation of many authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. While Geonames does not contain any shape data (such as country borders), it does have a powerful and well defined hierarchy to describe the relationships between different records. This custom hierarchy makes it harder to use in combination with data from other sources, but the Mapzen [Who's On First](http://whosonfirst.mapzen.com/) project will help by providing concordance between Geonames and other datasets.
 
@@ -81,13 +81,13 @@ Geonames data is licensed [CC-BY-3.0](http://creativecommons.org/licenses/by/3.0
 
 
 # Deprecated Sources
-Certain data sources have previously been supported by Mapzen Search but are no longer offered part of the core service and have been superseded by a new data source.
+Certain data sources used to be supported by Mapzen Search but are no longer offered part of the core service and have been superseded by a new data source.
 
 ## Quattroshapes
 
 `sources=quattroshapes` | `sources=qs`
 
-Quattroshapes was previously used by Mapzen Search and its use was discontinued in April 2016.
+Quattroshapes used to be supported by Mapzen Search and its use was discontinued in April 2016.
 
 It has been replaced by Who's on First, which continues to provide global administrative place data (countries, regions, counties, cities) and administrative lookup (_"what country, region, and city is this address part of?"_).
 
diff --git a/place.md b/place.md
index 93defdd..fbac615 100644
--- a/place.md
+++ b/place.md
@@ -16,7 +16,7 @@ https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:venue: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 OSM and `30 West 26th St, New York, NY` in OpenAddresses:
+To search for more than one `/place` in a request, join multiple values together and separate them with a comma. For example, this /place query looks up the Eiffel Tower in OpenStreetMap and `30 West 26th St, New York, NY` in OpenAddresses:
 
 https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:venue:5013364,oa:address:65cf57e4eb5548eca9bb548fb1461633
 
diff --git a/search.md b/search.md
index b960993..fb77ca0 100644
--- a/search.md
+++ b/search.md
@@ -160,7 +160,7 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary
 
 Sometimes you don't have a rectangle to work with, but rather you have a point on earth&mdash;for example, your location coordinates&mdash;and a maximum distance within which acceptable results can be located.
 
-In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` represents your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers.
+In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` 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-XXXXXXX&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35)
 

From efc1283b2f0dc69e53205d6605f2f34cad4c9a50 Mon Sep 17 00:00:00 2001
From: rmglennon <rhonda@mapzen.com>
Date: Fri, 1 Apr 2016 14:00:41 -0700
Subject: [PATCH 11/27] minor formatting changes to data-sources

---
 data-sources.md | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/data-sources.md b/data-sources.md
index 0fb411a..784888e 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -11,11 +11,11 @@ Attribution is required for many of our data providers. Some license information
 Layers:
 - `address`
 
-[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses.
+[OpenAddresses](http://openaddresses.io/) is a collection of over 200 million addresses around the world. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses.
 
-OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
+OpenAddresses is by far the largest dataset by number of records used by Mapzen Search. Even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
 
-OpenAddresses is sourced from regional governments. Many of these sources require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project.
+Many of the sources used in OpenAddresses require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project.
 
 ## Who's on First
 
@@ -30,20 +30,17 @@ Layers:
 - `neighbourhood`
 - `coarse` (alias for simultaneously using all the above)
 
-
-[Who's on First](https://whosonfirst.mapzen.com) is an open data directory of worldwide "administrative places" created by Mapzen. It is our primary provider of:
+[Who's on First](https://whosonfirst.mapzen.com) is an open-data directory of worldwide administrative places created by Mapzen. It is the primary provider of:
 - Countries
-- Regions (for example: States, Provinces)
+- Regions (for example: states, provinces)
 - Counties
 - Localities (cities, towns, hamlets)
 - Neighbourhoods
 
-Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonames, and OpenAddresses, we use Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. Other matching levels the place may fall within `macro-county` or `macro-region` taxonomy from Who's on Firsts.
+Additionally, for addresses, venues, and points of interest coming from OpenStreetMap, Geonames, and OpenAddresses, Mapzen Search uses Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. Other matching levels the place may fall within `macro-county` or `macro-region` taxonomy from Who's on Firsts.
 
 [License](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md)
 
-
-
 ## OpenStreetMap
 
 `sources=openstreetmap` | `sources=osm`
@@ -58,7 +55,6 @@ With its coverage of roads as well as rich metadata, OpenStreetMap is arguably t
 
 All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/licenses/odbl/), a [share-alike](https://en.wikipedia.org/wiki/Share-alike) license which also requires attribution.
 
-
 ## Geonames
 
 `sources=geonames` | `sources=gn`
@@ -79,8 +75,7 @@ In the meantime, Geonames still provides a wide variety of useful data that help
 
 Geonames data is licensed [CC-BY-3.0](http://creativecommons.org/licenses/by/3.0/).
 
-
-# Deprecated Sources
+# Deprecated sources
 Certain data sources used to be supported by Mapzen Search but are no longer offered part of the core service and have been superseded by a new data source.
 
 ## Quattroshapes

From bae12ca5644abbfa28e6866e956d69417acd26d7 Mon Sep 17 00:00:00 2001
From: rmglennon <rhonda@mapzen.com>
Date: Fri, 1 Apr 2016 14:01:57 -0700
Subject: [PATCH 12/27] remove qs from place query

---
 place.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/place.md b/place.md
index fbac615..e86065b 100644
--- a/place.md
+++ b/place.md
@@ -2,7 +2,7 @@
 
 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:
+To get started with a `/place` search, you need a [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, or country.
@@ -35,4 +35,3 @@ 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`

From c530af93f60382f83bfa08c817515ad4bf78b87d Mon Sep 17 00:00:00 2001
From: rmglennon <rhonda@mapzen.com>
Date: Fri, 1 Apr 2016 14:22:35 -0700
Subject: [PATCH 13/27] formatting, update leaflet plug-in URL

---
 response.md | 2 +-
 reverse.md  | 2 +-
 use-cors.md | 6 +++---
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/response.md b/response.md
index 2743f30..f89869b 100644
--- a/response.md
+++ b/response.md
@@ -64,7 +64,7 @@ Additionally, `/reverse` queries will have a `distance` parameter, which is the
 ## Notable features
 
 ### `gid`
-This is a "global id" that can be used to reference a result with the [/place](place.md) endpoint. It consists of an identifier for the dataset, a layer, and finally an `id` for the individual record. This `id` corresponds to stable ids from datasets wherever possible (such as the ID of an OpenStreetMap Node or Way). Not all datasets have stable ID's (in particular OpenAddresses records), so for OpenAddresses, we include the name of the source dataset in OpenAddresses as a part of the ID scheme.
+This is a "global id" that can be used to reference a result with the [/place](place.md) endpoint. It consists of an identifier for the dataset, a layer, and finally an `id` for the individual record. This `id` corresponds to stable ids from datasets wherever possible (such as the ID of an OpenStreetMap Node or Way). Not all datasets have stable ID's (in particular OpenAddresses records), so for OpenAddresses, Mapzen Search includes the name of the source dataset in OpenAddresses as a part of the ID scheme.
 
 The `gid` is also used to retrieve full details on a particular result from the `place` endpoint. [Full details](place.md) on ID schemes are part of the `/place` endpoint.
 
diff --git a/reverse.md b/reverse.md
index b300701..cd35197 100644
--- a/reverse.md
+++ b/reverse.md
@@ -12,7 +12,7 @@ With reverse geocoding with Mapzen Search, you can look up all sorts of informat
 * 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:
+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-XXXXXXX&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471)
 
diff --git a/use-cors.md b/use-cors.md
index c250ce1..3151352 100644
--- a/use-cors.md
+++ b/use-cors.md
@@ -12,11 +12,11 @@ You don’t need to do anything special to use `CORS` with JavaScript in a moder
 
 For a full list of supported browsers see: http://caniuse.com/#feat=cors
 
-### Add a Pelias search box to a Leaflet map
+### Add a search box to a Leaflet map
 
-Mapzen provides a plug-in that adds a Pelias search box to any [Leaflet](http://leafletjs.com/)-powered map.
+Mapzen provides a plug-in that adds a search box to any [Leaflet](http://leafletjs.com/)-powered map.
 
-See https://github.com/pelias/leaflet-geocoder for installation instructions and a live demo.
+See https://github.com/mapzen/leaflet-geocoder for installation instructions and a live demo. There is also a [tutorial](add-search-to-a-map.md) available.
 
 ### Loading data with jQuery
 

From ab0900deabe4a92d28038d00cec02262147f6243 Mon Sep 17 00:00:00 2001
From: rmglennon <rhonda@mapzen.com>
Date: Fri, 1 Apr 2016 14:39:34 -0700
Subject: [PATCH 14/27] formatting, add w3c link, we to mapzen

---
 data-sources.md         | 4 ++--
 transition-from-beta.md | 4 ++--
 use-cors.md             | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/data-sources.md b/data-sources.md
index 784888e..d6c56db 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -2,7 +2,7 @@
 
 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.
 
-Attribution is required for many of our data providers. Some license information is provided, but you are responsible for researching each project to follow their license terms.
+Attribution is required for many of the Mapzen Search data providers. Some license information is listed here, but you are responsible for researching each project to follow their license terms.
 
 ## OpenAddresses
 
@@ -30,7 +30,7 @@ Layers:
 - `neighbourhood`
 - `coarse` (alias for simultaneously using all the above)
 
-[Who's on First](https://whosonfirst.mapzen.com) is an open-data directory of worldwide administrative places created by Mapzen. It is the primary provider of:
+[Who's on First](https://whosonfirst.mapzen.com) is an open-data directory of worldwide administrative places. Created by Mapzen, it is the primary provider of:
 - Countries
 - Regions (for example: states, provinces)
 - Counties
diff --git a/transition-from-beta.md b/transition-from-beta.md
index 58fb533..9643385 100644
--- a/transition-from-beta.md
+++ b/transition-from-beta.md
@@ -71,7 +71,7 @@ Most parameters (and options) for search have been renamed:
 | `size` | `count` | Number of responses. Minimum: 1, maximum: 50 |
 | `layers` | `layers` (SEE BELOW) | While the parameter remains the same, the options have changed. See the table below for a 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)|
+| `details` | Deprecated (for the moment) | `details=false` used to respond with a minimized set of elements. Mapzen is 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` used to be 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 help improve clarity.
 
@@ -190,7 +190,7 @@ Instead, Mapzen Search supports [Cross-Origin Resource Sharing](https://develope
 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 instead of HTTP, especially when handling sensitive personal information (such as users' searches or users' location data).
+Mapzen Search continues to support HTTPS and traditional HTTP. You are encouraged to use HTTPS instead of HTTP, especially when handling sensitive personal information (such as users' searches or users' location data).
 
 ## What's happening to pelias.mapzen.com?
 The beta API available at pelias.mapzen.com will be available 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.
diff --git a/use-cors.md b/use-cors.md
index 3151352..faa61f4 100644
--- a/use-cors.md
+++ b/use-cors.md
@@ -6,9 +6,9 @@ Fortunately, techniques have since been developed that allow developers to secur
 
 ## 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 supported in modern Chrome, Firefox, Safari, and Internet Explorer (10+) web browsers. It became an official W3C Recommendation on the 16th January 2014.
+`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 supported in modern Chrome, Firefox, Safari, and Internet Explorer (10+) web browsers. It became a [W3C Recommendation](https://www.w3.org/TR/cors/) in 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 like you were performing it within the context of your own domain.
+You don’t need to do anything special to use `CORS` with JavaScript in a modern browser. Your web browser and the Mapzen Search servers will automatically negotiate the cross-origin request. For example, to make a `CORS` request with `jQuery`, you’d make your request 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
 

From 3583ae6eeed817b54e83998446e93cd3e0842a88 Mon Sep 17 00:00:00 2001
From: rmglennon <rhonda@mapzen.com>
Date: Fri, 1 Apr 2016 15:30:20 -0700
Subject: [PATCH 15/27] remove free, add bullet list to index

---
 api-keys-rate-limits.md |  4 ++--
 autocomplete.md         |  2 +-
 get-started.md          |  2 +-
 glossary.md             |  2 +-
 index.md                | 10 ++++++++++
 search.md               |  2 +-
 transition-from-beta.md |  2 +-
 7 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md
index 7b191a3..480da01 100644
--- a/api-keys-rate-limits.md
+++ b/api-keys-rate-limits.md
@@ -2,7 +2,7 @@
 
 ## Get an API key
 
-To use the Mapzen Search service, you must first get a free developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys.
+To use the Mapzen Search service, you must first get a 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.
@@ -10,7 +10,7 @@ To use the Mapzen Search service, you must first get a free developer API key. S
 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 system performance.
+Because Mapzen Search is a shared service, there are limitations on the numbers of requests to prevent individual users from degrading system performance.
 
 Mapzen Search allows you a maximum of:
 
diff --git a/autocomplete.md b/autocomplete.md
index 5b9bbf7..f7d2345 100644
--- a/autocomplete.md
+++ b/autocomplete.md
@@ -2,7 +2,7 @@
 
 If you are building an end-user application, you can use the `/autocomplete` endpoint alongside `/search` to enable real-time feedback. This type-ahead functionality helps users find what they are looking for, without requiring them to fully specify their search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list below.
 
-To build a query with autocomplete, you need [a free, API developer key](https://mapzen.com/developers) and a `text` parameter, representing what a user has typed into your application so far. Optionally, you can specify a geographic point where the search is focused, this will allow users to see more local places in the results.
+To build a query with autocomplete, you need an [API key](https://mapzen.com/developers) and a `text` parameter, representing what a user has typed into your application so far. Optionally, you can specify a geographic point where the search is focused, this will allow users to see more local places in the results.
 
 ## User experience guidelines
 
diff --git a/get-started.md b/get-started.md
index fc32aba..0f50fa8 100644
--- a/get-started.md
+++ b/get-started.md
@@ -1,6 +1,6 @@
 # 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 a [free, developer 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.
+[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.
 
diff --git a/glossary.md b/glossary.md
index a619fcf..88a9e92 100644
--- a/glossary.md
+++ b/glossary.md
@@ -10,7 +10,7 @@
 ## Mapzen Search API and developer terms
 
 - **API endpoint** - an architectural style for accessing web resources through a URL. In Mapzen Search, available endpoints include `search`, `reverse`, and `autocomplete`. You can construct a URL to send queries and receive responses from Mapzen Search.
-- **API key** - an code that identifies the developer account without providing a password. Mapzen Search requires a free, API key to interact with the search service.
+- **API key** - an code that identifies the developer account without providing a password. Mapzen Search requires an API key to interact with the search service.
 - **autocomplete** - enables real-time feedback when entering text for a search, typically, where users start typing and a drop-down list appears where they can choose the term from the list below. Use the `autocomplete` endpoint to do this.
 - **data source** - the datasets available to Mapzen Search. Only data sources that have open-source licenses are used.
 - **focus** - option to make places closer to a particular location be prioritized and appear higher in the search results list. After all nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization.
diff --git a/index.md b/index.md
index 71d3332..2eb86b3 100644
--- a/index.md
+++ b/index.md
@@ -3,3 +3,13 @@
 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.
+
+## 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 maps
+- API with generous rate limits
diff --git a/search.md b/search.md
index fb77ca0..288c2cb 100644
--- a/search.md
+++ b/search.md
@@ -4,7 +4,7 @@ Geospatial search, commonly referred to as geocoding, is the process of matching
 
 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.
+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 web service.
 
 All Mapzen Search requests share the same format:
 
diff --git a/transition-from-beta.md b/transition-from-beta.md
index 9643385..7ab5b7b 100644
--- a/transition-from-beta.md
+++ b/transition-from-beta.md
@@ -9,7 +9,7 @@ The changes aren't too drastic and should be implementable in an afternoon or a
 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](https://mapzen.com/developers) and generate one (or more) for all your search needs.
+The first big change is the introduction of API keys. Like all other Mapzen APIs, Search now requires an API key. You can register at the [Mapzen Developer Portal](https://mapzen.com/developers) and generate one (or more) for all your search needs.
 
 Mapzen Search API keys allow you:
 

From d333c83abb695fe9316fea7bb340c7b380728934 Mon Sep 17 00:00:00 2001
From: rmglennon <rhonda@mapzen.com>
Date: Fri, 1 Apr 2016 15:59:36 -0700
Subject: [PATCH 16/27] fix typo in api key definition

---
 glossary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/glossary.md b/glossary.md
index 88a9e92..983fa14 100644
--- a/glossary.md
+++ b/glossary.md
@@ -10,7 +10,7 @@
 ## Mapzen Search API and developer terms
 
 - **API endpoint** - an architectural style for accessing web resources through a URL. In Mapzen Search, available endpoints include `search`, `reverse`, and `autocomplete`. You can construct a URL to send queries and receive responses from Mapzen Search.
-- **API key** - an code that identifies the developer account without providing a password. Mapzen Search requires an API key to interact with the search service.
+- **API key** - a code that identifies the developer account without providing a password. Mapzen Search requires an API key to interact with the search service.
 - **autocomplete** - enables real-time feedback when entering text for a search, typically, where users start typing and a drop-down list appears where they can choose the term from the list below. Use the `autocomplete` endpoint to do this.
 - **data source** - the datasets available to Mapzen Search. Only data sources that have open-source licenses are used.
 - **focus** - option to make places closer to a particular location be prioritized and appear higher in the search results list. After all nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization.

From ffc285d275d680c1f0ff1462aeee4f5a650a0933 Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Mon, 11 Apr 2016 14:24:34 -0400
Subject: [PATCH 17/27] Updated to WoF bbox + [admin]_gid

---
 data-sources.md |  8 ++++--
 index.md        |  2 +-
 response.md     | 72 +++++++++++++++++++++++++------------------------
 3 files changed, 44 insertions(+), 38 deletions(-)

diff --git a/data-sources.md b/data-sources.md
index d6c56db..bda034a 100644
--- a/data-sources.md
+++ b/data-sources.md
@@ -15,7 +15,7 @@ Layers:
 
 OpenAddresses is by far the largest dataset by number of records used by Mapzen Search. Even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding.
 
-Many of the sources used in OpenAddresses require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project.
+Many of the sources used in OpenAddresses require [attribution](https://mapzen.com/rights/). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project.
 
 ## Who's on First
 
@@ -23,7 +23,9 @@ Many of the sources used in OpenAddresses require [attribution (LINK NOT LIVE)](
 
 Layers:
 - `country`
+- `macroregion`
 - `region`
+- `macrocounty`
 - `county`
 - `locality`
 - `localadmin`
@@ -32,12 +34,14 @@ Layers:
 
 [Who's on First](https://whosonfirst.mapzen.com) is an open-data directory of worldwide administrative places. Created by Mapzen, it is the primary provider of:
 - Countries
+- Macroregions (e.g. England is a Macroregion within the United Kingdom)
 - Regions (for example: states, provinces)
+- Macro-counties (e.g. [Departments of France](https://en.wikipedia.org/wiki/Departments_of_France))
 - Counties
 - Localities (cities, towns, hamlets)
 - Neighbourhoods
 
-Additionally, for addresses, venues, and points of interest coming from OpenStreetMap, Geonames, and OpenAddresses, Mapzen Search uses Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. Other matching levels the place may fall within `macro-county` or `macro-region` taxonomy from Who's on Firsts.
+Additionally, for addresses, venues, and points of interest coming from OpenStreetMap, Geonames, and OpenAddresses, Mapzen Search uses Who's on First to provide standardized fields for the country, region, locality, and neighbourhood.
 
 [License](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md)
 
diff --git a/index.md b/index.md
index 2eb86b3..d54254f 100644
--- a/index.md
+++ b/index.md
@@ -1,4 +1,4 @@
-[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 [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). 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.
 
 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.
 
diff --git a/response.md b/response.md
index f89869b..ae9bdee 100644
--- a/response.md
+++ b/response.md
@@ -21,42 +21,41 @@ The `features` property of the result is where you will find the list of results
 
 Each item in this list will contain all the information needed to find it in human-readable format in the `properties` block, as well as computer friendly coordinates in the `geometry` property.
 
-```json
+``` json
 {
-  "type": "Feature",
-  "geometry": {
-    "type": "Point",
-    "coordinates": [
-      -73.990425,
-      40.744131
-    ]
-  },
-  "properties": {
-    "id": "way:265038872",
-    "gid": "openstreetmap:address:way:265038872",
-    "layer": "address",
-    "source": "openstreetmap",
-    "name": "30 West 26th Street",
-    "housenumber": "30",
-    "street": "West 26th Street",
-    "postalcode": "10010",
-    "confidence": 0.875,
-    "country": "United States",
-    "country_id": "85633793",
-    "country_a": "USA",
-    "region": "New York",
-    "region_id": "85688543",
-    "region_a": "NY",
-    "county": "New York County",
-    "county_id": "102081863",
-    "localadmin": "Manhattan",
-    "localadmin_id": "404522731",
-    "locality": "New York",
-    "locality_id": "85977539",
-    "neighbourhood": "Flatiron District",
-    "neighbourhood_id": "85869245",
-    "label": "30 West 26th Street, Manhattan, NY, USA"
-  }
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          -0.125422,
+          51.501581
+        ]
+      },
+      "properties": {
+        "id": "101750367",
+        "gid": "whosonfirst:locality:101750367",
+        "layer": "locality",
+        "source": "whosonfirst",
+        "name": "London",
+        "confidence": 0.949,
+        "country": "United Kingdom",
+        "country_gid": "whosonfirst:country:85633159",
+        "country_a": "GBR",
+        "macroregion": "England",
+        "macroregion_gid": "whosonfirst:macroregion:404227469",
+        "region": "City of Westminster",
+        "region_gid": "whosonfirst:region:85684061",
+        "locality": "London",
+        "locality_gid": "whosonfirst:locality:101750367",
+        "label": "London, England, United Kingdom"
+      },
+      "bbox": [
+        -0.4984345,
+        51.297207,
+        0.27894,
+        51.6843015
+      ]
+    },
 ```
 
 Additionally, `/reverse` queries will have a `distance` parameter, which is the distance, in meters, from the query point.
@@ -80,6 +79,9 @@ For the `/search` endpoint, it primarily takes into account how well properties
 
 Additionally, the confidence score can optionally be biased along with other results, like test scores in a classroom might be graded on a curve. This takes into account both the property matches described above and the distance between results. This relative scoring is enabled on Mapzen Search, but can be turned off when hosting your own Pelias instance.
 
+### `bbox`
+`Feature`s coming from _Who's on First_ and OpenStreetMap ways will often have their own `"bbox"` elements. This `"bbox"` is at the same level as `"properties"`. If present, it describes the geographic extent of the feature (e.g. the screen size necessary to show all of California without needing to send the precise polygon geometry). This should be treated as separate from the `bbox` that describes the entire `FeatureCollection`.
+
 ## 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.

From d9de9312f83c28700b234202894fe51a57986c4b Mon Sep 17 00:00:00 2001
From: Riordan <dr@daveriordan.com>
Date: Wed, 13 Apr 2016 15:48:46 -0400
Subject: [PATCH 18/27] Changes license from MIT (which applies to code only)
 to CC-BY-4.0 to apply to creative works

---
 LICENSE.md | 188 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 167 insertions(+), 21 deletions(-)

diff --git a/LICENSE.md b/LICENSE.md
index 2a2ae2c..e94fcdd 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,21 +1,167 @@
-The MIT License (MIT)
-
-Copyright (c) 2015 pelias
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Copyright 2015-2016 Mapzen
+
+Licensed under a [Creative Commons Attribution 4.0 International](http://creativecommons.org/licenses/by/4.0/) License (CC-BY-4.0).
+
+
+## creative commons
+
+# Attribution 4.0 International
+
+Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
+
+### Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
+
+* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors).
+
+* __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees).
+
+## Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
+
+### Section 1 – Definitions.
+
+a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
+
+b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
+
+c. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
+
+d. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
+
+e. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
+
+f. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
+
+g. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
+
+h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License.
+
+i. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
+
+j. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
+
+k. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
+
+### Section 2 – Scope.
+
+a. ___License grant.___
+
+    1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
+
+        A. reproduce and Share the Licensed Material, in whole or in part; and
+
+        B. produce, reproduce, and Share Adapted Material.
+
+    2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
+
+    3. __Term.__ The term of this Public License is specified in Section 6(a).
+
+    4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
+
+    5. __Downstream recipients.__
+
+        A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
+
+        B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
+
+    6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
+
+b. ___Other rights.___
+
+    1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
+
+    2. Patent and trademark rights are not licensed under this Public License.
+
+    3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
+
+### Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the following conditions.
+
+a. ___Attribution.___
+
+    1. If You Share the Licensed Material (including in modified form), You must:
+
+        A. retain the following if it is supplied by the Licensor with the Licensed Material:
+
+            i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
+
+            ii. a copyright notice;
+
+            iii. a notice that refers to this Public License;
+
+            iv. a notice that refers to the disclaimer of warranties;
+
+            v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
+
+        B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
+
+        C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
+
+    2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
+
+    3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
+
+    4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License.
+
+### Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
+
+a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
+
+b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and
+
+c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
+
+### Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__
+
+b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__
+
+c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
+
+### Section 6 – Term and Termination.
+
+a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
+
+b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
+
+    1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
+
+    2. upon express reinstatement by the Licensor.
+
+    For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
+
+c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
+
+d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
+
+### Section 7 – Other Terms and Conditions.
+
+a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
+
+b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
+
+### Section 8 – Interpretation.
+
+a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
+
+b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
+
+c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
+
+d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
+
+```
+Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
+
+Creative Commons may be contacted at creativecommons.org
+```
+

From fc1e8b1a98f906f246fc58dd008742d6d65b75b8 Mon Sep 17 00:00:00 2001
From: Diana Shkolnikov <diana@mapzen.com>
Date: Wed, 13 Apr 2016 16:14:06 -0400
Subject: [PATCH 19/27] Create release-notes.md

Place to hold all release notes, organized by date of release.
---
 release-notes.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 release-notes.md

diff --git a/release-notes.md b/release-notes.md
new file mode 100644
index 0000000..3ee0b80
--- /dev/null
+++ b/release-notes.md
@@ -0,0 +1,14 @@
+# Mapzen Search API Release Notes 
+
+## April 08, 2016
+
+### Changes
+
+* Switched from `Quattroshapes` to `WhosOnFirst` as the canonical source for administrative hierarchies and corresponding geometries.
+* No longer importing `Quattroshapes` data since `WhosOnFirst` contains all those records and more. Going forward, any use of `quattroshapes` or `qs` in queries will resolve to `whosonfirst` or `wof` automatically.
+* New `bbox` property has been added to individual results, for which geometry was available in the original source. This does not affect POI and address data.
+* Drastic improvements have been made to the label generation logic.
+* `id` and `gid` format has changed to make the ids more unique.
+* New id format resolves previously outstanding bugs related to `geonames` ids being invalid for lookup via the `/place` endpoint.
+* Addition place types have been introduced, such as `macroregion`, `macrocounty`, and `borough`.
+* `gid` values have been added for each parent in the admin hierarchies of results.

From b8ca0a0fdc7fe9268a49135a75ff25e12df0e747 Mon Sep 17 00:00:00 2001
From: Diana Shkolnikov <diana@mapzen.com>
Date: Wed, 13 Apr 2016 16:16:00 -0400
Subject: [PATCH 20/27] Remove Mapzen Search since it's already visible

---
 release-notes.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/release-notes.md b/release-notes.md
index 3ee0b80..c8add14 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -1,4 +1,4 @@
-# Mapzen Search API Release Notes 
+# Release Notes 
 
 ## April 08, 2016
 

From 8828a1068645689192286acd4299fe01488c3be0 Mon Sep 17 00:00:00 2001
From: Diana Shkolnikov <diana@mapzen.com>
Date: Wed, 13 Apr 2016 16:36:11 -0400
Subject: [PATCH 21/27] Add paragraph of summary above bullet points

---
 release-notes.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/release-notes.md b/release-notes.md
index c8add14..626db80 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -2,7 +2,7 @@
 
 ## April 08, 2016
 
-### Changes
+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. See the detailed list of changes below for more specifics.
 
 * Switched from `Quattroshapes` to `WhosOnFirst` as the canonical source for administrative hierarchies and corresponding geometries.
 * No longer importing `Quattroshapes` data since `WhosOnFirst` contains all those records and more. Going forward, any use of `quattroshapes` or `qs` in queries will resolve to `whosonfirst` or `wof` automatically.

From c6194dc0fb835fb8923749d326b0f201eb7f3841 Mon Sep 17 00:00:00 2001
From: Diana Shkolnikov <diana@mapzen.com>
Date: Wed, 13 Apr 2016 16:59:57 -0400
Subject: [PATCH 22/27] Update release-notes.md

---
 release-notes.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/release-notes.md b/release-notes.md
index 626db80..79ff837 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -1,6 +1,4 @@
-# Release Notes 
-
-## April 08, 2016
+## 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. See the detailed list of changes below for more specifics.
 

From 6a355aa6316c8276be64223624ba8aa420a17c5e Mon Sep 17 00:00:00 2001
From: Diana Shkolnikov <diana@mapzen.com>
Date: Mon, 18 Apr 2016 12:42:45 -0400
Subject: [PATCH 23/27] Update release-notes.md

---
 release-notes.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/release-notes.md b/release-notes.md
index 79ff837..7a05175 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -1,3 +1,10 @@
+## 18 April 2016
+
+* Address parsing now works without spaces after commas. This was our bad. Feel free to leave those spaces out as long as you provide commas to delimit admin parts.
+* Further streamlining of labels. You can expect the labels to a have more consistent and minimal feel. If the results are coming from New York, expect boroughs such as Manhattan, Brooklyn, Queens, etc. to be part of the label. You're welcome New Yorkers! :heart:
+* Fixed a bug where specifying `layers=macrocounty` would fail due to a typo in the API code. You can see how easy it is to mistype `macrocounty` and not notice that `macrocountry` is incorrect. #onlyhuman
+
+
 ## 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. See the detailed list of changes below for more specifics.

From 89216be82e2062bdce33a42589ed68ae0ba16581 Mon Sep 17 00:00:00 2001
From: Diana Shkolnikov <diana@mapzen.com>
Date: Tue, 19 Apr 2016 07:36:44 -0400
Subject: [PATCH 24/27] Update release-notes.md

---
 release-notes.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/release-notes.md b/release-notes.md
index 7a05175..e9a4d85 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -7,7 +7,9 @@
 
 ## 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. See the detailed list of changes below for more specifics.
+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.
 
 * Switched from `Quattroshapes` to `WhosOnFirst` as the canonical source for administrative hierarchies and corresponding geometries.
 * No longer importing `Quattroshapes` data since `WhosOnFirst` contains all those records and more. Going forward, any use of `quattroshapes` or `qs` in queries will resolve to `whosonfirst` or `wof` automatically.
@@ -15,5 +17,8 @@ This release marks the official integration of the Mapzen `Who's on First` data
 * Drastic improvements have been made to the label generation logic.
 * `id` and `gid` format has changed to make the ids more unique.
 * New id format resolves previously outstanding bugs related to `geonames` ids being invalid for lookup via the `/place` endpoint.
-* Addition place types have been introduced, such as `macroregion`, `macrocounty`, and `borough`.
+* Additional place-types have been introduced, such as `macroregion`, `macrocounty`, and `borough`.
 * `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.
+

From fabc9197dc7831eaeb581862e7a82a1bf0a8fba7 Mon Sep 17 00:00:00 2001
From: Diana Shkolnikov <diana@mapzen.com>
Date: Tue, 19 Apr 2016 08:26:15 -0400
Subject: [PATCH 25/27] Update autocomplete.md (#103)

Add new autocomplete sources and layers patameters
---
 autocomplete.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/autocomplete.md b/autocomplete.md
index f7d2345..eccfb7e 100644
--- a/autocomplete.md
+++ b/autocomplete.md
@@ -50,6 +50,71 @@ without `focus.point` you will find the most popular restaurants first:
 2)	Hard Rock Café, San Giljan, Malta
 ```
 
+## Filters
+
+You can filter the results in several ways: the original data source and/or the type of record. 
+
+### Sources
+
+The `sources` parameter allows you to specify from which data sources you'd like to receive results. The sources are as follows
+
+* `openstreetmap` or `osm`
+* `openaddresses` or `oa`
+* `geonames` or `gn`
+* `whosonfirst` or `wof`
+
+> /v1/autocomplete?api_key=search-XXXXXXX&sources=openaddresses&text=pennsylvania
+
+with `sources=openaddresses` you will only find addresses on Pennsylvania Ave or Street:
+```
+1) 8 R Pennsylvania Avenue, Amity, PA, USA
+2) 7 Pennsylvania Avenue, Amity, PA, USA
+3) 9 Pennsylvania Avenue, Cherry, PA, USA
+```
+
+without `sources=openaddresses` you will find the most popular Pennsylvanias first:
+```
+1) Pennsylvania, USA
+2) Pennsylvania Avenue Heights, Washington, DC, USA
+3) Pennsylvania, Satsuma, AL, USA
+```
+
+### Layers
+We refer to the type of record as its `layer`. We index all records into the following layers
+
+* `venue`
+* `address`
+* `microhood`
+* `neighbourhood`
+* `macrohood`
+* `county`
+* `macrocounty`
+* `localadmin`
+* `locality`
+* `borough`
+* `region`
+* `country`
+
+We also allow users to refer to all the administrative hierarchy layers with a single alias, `coarse`.
+
+> /v1/autocomplete?api_key=search-XXXXXXX&layers=coarse&text=starbuck
+
+with `layers=coarse` you will see only administrative areas with names containing Starbuck
+
+```
+1) Starbuckville, NY, USA
+2) Starbuck, MN, USA
+3) Starbuck, WA, USA
+```
+
+with `layers=venue` you will see only the venues by that name
+
+```
+1) Starbucks, Braunschweig, Germany
+2) Starbucks, Islip, NY, USA
+3) Starbucks, Austin, TX, USA
+```
+
 ## Available autocomplete parameters
 
 | Parameter | Type | Required | Default | Example |
@@ -58,3 +123,5 @@ without `focus.point` you will find the most popular restaurants first:
 | `text` | string | yes | none | `Union Square` |
 | `focus.point.lat` | floating point number | no | none | `48.581755` |
 | `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 |

From 3319ebca0a96db1075102505cb81317dddce356d Mon Sep 17 00:00:00 2001
From: Albin Larsson <albin.post@gmail.com>
Date: Thu, 28 Apr 2016 16:35:18 +0200
Subject: [PATCH 26/27] Minor formatting fix

---
 reverse.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reverse.md b/reverse.md
index cd35197..b56845d 100644
--- a/reverse.md
+++ b/reverse.md
@@ -48,7 +48,7 @@ By default, reverse geocoding returns results from any [data source](data-source
 |---|---|---|
 | [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` |
 | [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` |
-| [Who's on First](https://whosonfirst.mapzen.com) | 'whosonfirst' | 'wof' |
+| [Who's on First](https://whosonfirst.mapzen.com) | `whosonfirst` | `wof` |
 | [GeoNames](http://www.geonames.org/) | `geonames` | `gn` |
 
 >[/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&sources=osm)

From dd00c45949746377f099efd444a510160b72e78e Mon Sep 17 00:00:00 2001
From: Julian Simioni <julian@mapzen.com>
Date: Fri, 29 Apr 2016 16:20:26 -0400
Subject: [PATCH 27/27] Relase notes for 2016-4-29 release

---
 release-notes.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/release-notes.md b/release-notes.md
index e9a4d85..95ae1ab 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -1,3 +1,11 @@
+## 29 April 2016
+
+* A big improvements to autocomplete results coming from numerous bug fixes and improvements! More details can be found in the pull requests: [pelias/schema#127](https://github.com/pelias/schema/pull/127) and [pelias/api#526](https://github.com/pelias/api/pull/526). Some highlights include:
+ - Single digit housenumbers like `8 Main St` can be found more easily
+ - Support for searching for the street name before the house number, as is common in many European countries, is improved.
+ - Searches that end in common words no longer return no results. These were being treated as stopwords internally in Elasticsearch. Now queries such as `Moscone West` will work better
+* [Remove OpenAddresses records with 0 housenumbers in US/CA](https://github.com/pelias/openaddresses/pull/92)
+
 ## 18 April 2016
 
 * Address parsing now works without spaces after commas. This was our bad. Feel free to leave those spaces out as long as you provide commas to delimit admin parts.