From 55fcbadb185b6d1a8ec4d7b5b4f08cf0b3a55d2e Mon Sep 17 00:00:00 2001
From: Diana Shkolnikov <diana@mapzen.com>
Date: Wed, 16 Sep 2015 20:01:59 -0400
Subject: [PATCH] Update 002-search.md

---
 getting-started/002-search.md | 71 ++++++++++++++++++++++++++++++-----
 1 file changed, 62 insertions(+), 9 deletions(-)

diff --git a/getting-started/002-search.md b/getting-started/002-search.md
index 68f511f..d03167a 100644
--- a/getting-started/002-search.md
+++ b/getting-started/002-search.md
@@ -19,7 +19,7 @@ Let's say you wanted to find **Stinky Beach**, you would simply query the search
 
 _...go ahead, and click that link, we'll wait_
 
-Maybe you'd like to find an **address**, like this:
+Maybe you'd like to find an address, like this:
 
 > [/v1/search?___text=30 west 26th street___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=30 west 26th street)
 
@@ -27,21 +27,74 @@ Or even a landmark, like **Yankee Stadium**:
 
 > [/v1/search?___text=yankee stadium___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yankee stadium)
 
-_You may have noticed already that cApiTaliZAtioN isn't a big deal for search._
-_You can type `yankee stadium` or `Yankee Stadium` or even `YANKEE STADIUM` if you're really excited about finding it._
-_See for yourself:_
+You may have noticed already that cApiTaliZAtioN isn't a big deal for search.
+You can type **yankee stadium** or **Yankee Stadium** or even **YANKEE STADIUM** if you're really excited about finding it.
+See for yourself:
 
 > [/v1/search?___text=YANKEE STADIUM___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YANKEE STADIUM)
 
 #### Results
 
-Now that you're back, you probably saw a `GeoJSON` formatted response on the other side of that click.
+Now that you've seen some examples of search, let's examine the results closer.
+When searching for **30 West 26th Street** you got back a `GeoJSON` formatted response.
 You'll always get back `GeoJSON` results, unless something goes terribly wrong, in which case you'll get a really helpful error.
 
-Now you know exactly where on the earth's sufrace **Stinky Beach** is located: `[ 139.86114, -37.33192 ]`
-You've also probably learned from the results of that request that this intriguing beach is located in **Australia**, more specifically in the **South Australia** region. You also have yourself a handy text label to use when talking to other humans about this place: **Stinky Beach, Nora Creina, South Australia**
-
-[Read more about the response format](https://github.com/dianashk/pelias-doc/edit/master/getting-started/response.md)
+You can go [here](link.to.geojson.spec.com) to learn more about the `GeoJSON` data format specification.
+We'll assume you're familiar with the general layout and only point out some important details here.
+
+You will find the following top-level structure to every response:
+
+```
+{
+  "geocoding":{...},
+  "type":"FeatureCollection",
+  "features":[...],
+  "bbox":[...]
+}
+```
+
+For the purposes of getting started quickly, let's keep our focus on the **features** property of the result.
+This is where you will find the list of results that best matched your input parameters.
+
+Each item in this list will contain all the information needed to identify it in human-readable format in the `properties` block, 
+as well as computer friendly coordinates in the `geometry` property. Note the `label` property, which is a human-friendly
+representation of the place, ready to be displayed to an end-user.
+
+```
+{  
+  "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
+    ]
+  }
+}
+```
+
+There is so much more to tell you about the plethora of data being returned for each search,
+we had to split it out into its own document.
+[Read more about the response format.](https://github.com/dianashk/pelias-doc/edit/master/getting-started/response.md)
 
 #### Result count