response + reverse distance

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",
+  "type": "Feature",
-  "properties":{
+  "geometry": {
-    "gid":"...",
+    "type": "Point",
-    "layer":"address",
+    "coordinates": [
-    "source":"osm",
+      -73.990425,
-    "name":"30 West 26th Street",
+      40.744131
-    "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
     ]
+  },
+  "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
+### `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.
+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.

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