@ -68,9 +68,10 @@ Additionally, [/reverse](reverse.md) queries will have a `distance` parameter, w
All results returned from Mapzen Search are points, and can be found in the `coordinates` array. Following the [GeoJSON specification](http://geojson.org/geojson-spec.html#positions), these coordinates are in **longitude, latitude** order.
All results returned from Mapzen Search are points, and can be found in the `coordinates` array. Following the [GeoJSON specification](http://geojson.org/geojson-spec.html#positions), these coordinates are in **longitude, latitude** order.
### `gid`
### `gid`
All places in Mapzen Search have a global identifier, known as a `gid`. Each matching record returned from a [/search](search.md), [/autocomplete](autocomplete.md), or [/reverse](reverse.md) geocoding request has a `gid` field.
All places in Mapzen Search have a global identifier, known as a `gid`. Each matching record returned from a [/search](search.md), [/autocomplete](autocomplete.md), or [/reverse](reverse.md) geocoding request has a `gid` field.
The `gid` consists of a `layer` (such as `address` or `country`), an identifier for the original data source (such as `openstreetmap` or `openaddresses`), and an `id` for the individual record corresponding to the original source idenfier, where possible. This information is also available as properties on the individual results as `layer`, `source`, and `source_id`.
The `gid` consists of a `layer` (such as `address` or `country`), an identifier for the original data source (such as `openstreetmap` or `openaddresses`), and an `id` for the individual record corresponding to the original source identifier, where possible. This information is also available as properties on the individual results as `layer`, `source`, and `source_id`.
#### :warning: Follow these guidelines regarding the `gid`:
#### :warning: Follow these guidelines regarding the `gid`:
@ -79,9 +80,11 @@ The `gid` consists of a `layer` (such as `address` or `country`), an identifier
- You should not attempt to parse `gid` strings for information or store them for future use. You should only use `gid` at the time when you receive the search results. One valid use for the `gid` is to retrieve full details on a particular result from the [/place](place.md) endpoint.
- You should not attempt to parse `gid` strings for information or store them for future use. You should only use `gid` at the time when you receive the search results. One valid use for the `gid` is to retrieve full details on a particular result from the [/place](place.md) 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.
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.
The confidence score is an estimation of how accurately this result matches the query.
For the [/reverse](reverse.md) endpoint, the confidence score is determined solely by its distance from the coordinate specified. Closer results get a higher score.
For the [/reverse](reverse.md) endpoint, the confidence score is determined solely by its distance from the coordinate specified. Closer results get a higher score.
@ -91,6 +94,7 @@ For the [/search](search.md) endpoint, it primarily takes into account how well
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.
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`
### `bbox`
Features from Who's on First and OpenStreetMap 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, such as 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`.
Features from Who's on First and OpenStreetMap 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, such as 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
## Result count
@ -103,8 +107,8 @@ By default, Mapzen Search results 10 places, unless otherwise specified. If you
rmglennon
8 years ago