From fab62a82d2b58fbc6cac1c64b2bec4b0053871e2 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 6 Oct 2015 15:44:16 -0400 Subject: [PATCH 1/5] Move label description to new notable features section --- response.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/response.md b/response.md index 7f13818..b7a11b3 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. Note the `label` property, which is a human-friendly representation of the place, ready to be displayed to an end-user. +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. ```json { @@ -53,6 +53,11 @@ Each item in this list will contain all the information needed to identify it in } ``` +## Notable Features + +### 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 we only support a few countries at the moment. + ## 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 5cd9dd30542fc536cff8984e525a6d80cf6cb587 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 6 Oct 2015 15:44:38 -0400 Subject: [PATCH 2/5] Add Gid to notable features --- response.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/response.md b/response.md index b7a11b3..4cfd5bb 100644 --- a/response.md +++ b/response.md @@ -55,6 +55,9 @@ Each item in this list will contain all the information needed to identify it in ## 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. + ### 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 we only support a few countries at the moment. From 3fe138f6ee4ff29599ae95d98711595b07445efe Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 6 Oct 2015 16:07:59 -0400 Subject: [PATCH 3/5] Add description of confidence score to notable features --- response.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/response.md b/response.md index 4cfd5bb..53cb3cf 100644 --- a/response.md +++ b/response.md @@ -61,6 +61,11 @@ This is a "global id" that can be used to reference a result with the [/place](/ ### 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 we only support a few countries at the moment. +### Confidence +The confidence score is an estimation of how accurately this result matches with what you are searching for. 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. + ## 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 0473571879a8b702290725c82858e7b669c1a6eb Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 6 Oct 2015 16:18:33 -0400 Subject: [PATCH 4/5] Describe confidence score for reverse geocoding --- response.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/response.md b/response.md index 53cb3cf..cec63b6 100644 --- a/response.md +++ b/response.md @@ -62,7 +62,11 @@ This is a "global id" that can be used to reference a result with the [/place](/ 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 we only support a few countries at the moment. ### Confidence -The confidence score is an estimation of how accurately this result matches with what you are searching for. 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. +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. + +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. From 61069ff10492db856de76a148bfa79cfbeba9955 Mon Sep 17 00:00:00 2001 From: Rhonda Glennon Date: Tue, 6 Oct 2015 14:43:02 -0700 Subject: [PATCH 5/5] Couple of style edits Made heading use sentence capitalization Changed we to Mapzen Search --- response.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/response.md b/response.md index cec63b6..8dfb19b 100644 --- a/response.md +++ b/response.md @@ -53,13 +53,13 @@ Each item in this list will contain all the information needed to identify it in } ``` -## Notable Features +## 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. ### 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 we only support 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 appropriate 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.