stubbed out search + sections

getting-started/000-getting-started.md

@@ -5,8 +5,8 @@ Mapzen Search is a modern geocoding and place search service based on [Pelias](h
 
 [REWRITE]
 Mapzen Search can be used to:
-- geocode addresses, points of interest, neighborhoods, cities, and regions
+- geocode addresses, points of interest, neighbourhood, cities, and regions
 - power real-time search autocomplete for places
 - turn a list of addresses into coordinates to plot
 - Take location coordinates and turn them into human readable places, like an address
-- find the neighborhoods, cities, states, and countries of location coordinates to quickly classify where your data is coming from
+- find the neighbourhood, cities, states, and countries of location coordinates to quickly classify where your data is coming from

getting-started/001-api.md

@@ -21,3 +21,6 @@ Our free API keys allow you a maximum of:
 - 30,000 requests per day
 
 If you need more capacity, you can get in touch with [search@mapzen.com](mailto:search@mapzen.com), or set up your own instance of [Pelias](https://github.com/pelias/pelias), which we provide with access to all of the same data we use to power Mapzen Search.
+
+# Taking Care
+Mapzen Search works over HTTPS in addition to HTTP. We strongly encourage you to use HTTPS for all requests, especially for queries involving potentially sensitive information, like a user's location or search query.

getting-started/002-search.md

@@ -15,6 +15,7 @@ Geocoding is the process of matching an address to its corresponding geographic
 - Response is GeoJSON FeatureCollection
  - The FeatureCollection is an ordered array, ranked in order of likleyhood
  - Use directly in your application or test at GeoJSON.io
+ - Show + explain a response block
 
 ## Sizing Your Results
  - Example: size=1 for batch geocoding
@@ -58,7 +59,21 @@ Mapzen search offers two types of options for selecting the dataset you want bac
 
 ### Selecting Layers
 
-{layer options}
+
+|Layer Name|Represents|
+|----|----|
+|`venue`|Points of interest, businesses, things with walls|
+|`address`|Places with a street address|
+|`country`|Places that issue passports, nations, nation-states|
+|`region`|States and provinces|
+|`county`|Official governmental area; usually bigger than a locality, almost always smaller than a region|
+|`locality`|Towns, hamlets, cities, etc.|
+|`localadmin`|    |
+|`neighbourhood`||
+|`coarse`|Alias for simultaneously using `country`, `region`, `county`, `locality`, `localadmin`, and `neighbourhood`||
+
+Our 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.
+
 
 
 ### Coarse Geocoding (Neighborhoods, Cities, States, Countries)
@@ -71,6 +86,5 @@ There are many cases where you're after not a point, but a general area, whether
 - Select localities in a country (with boundary.country)
 
 
-
-
 # Using Autocomplete & Search Together
+For end-user applications, `/autocomplete` is intended to be used alongside `/search` to facilitate real-time feedback for user s

getting-started/004-data.md

@@ -1,5 +1,5 @@
-Data
-====
+Data Sources
+=============
 
 Mapzen Search is powered by several major open data sets and owes a tremendous debt of gratitude to the individuals and communities which produced them.
 

getting-started/005-place.md

@@ -0,0 +1,2 @@
+Places
+=======

getting-started/006-response.md

@@ -0,0 +1,2 @@
+Response Format
+================