From 2154359bcaa20ade85caaca1e3f6c81c1876b089 Mon Sep 17 00:00:00 2001 From: Riordan Date: Thu, 24 Mar 2016 14:54:33 -0400 Subject: [PATCH 01/16] Adds sources parameter codes on Sources page --- data-sources.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/data-sources.md b/data-sources.md index df22b8e..1f54b9c 100644 --- a/data-sources.md +++ b/data-sources.md @@ -4,6 +4,8 @@ Mapzen Search is powered by several major open data sets and owes a tremendous d ## OpenStreetMap +`sources=openstreetmap` | `sources=osm` + [OpenStreetMap](https://www.openstreetmap.org/) is a community-driven, editable map of the world. It prioritizes local knowledge and individual contributions over bulk imports, which often means it has excellent coverage even in remote areas where no large-scale mapping efforts have been attempted. OpenStreetMap contains information on landmarks, buildings, roads, and natural features. With its coverage of roads as well as rich metadata, OpenStreetMap is arguably the most valuable dataset used by Mapzen Search for general usage. @@ -12,6 +14,8 @@ All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/l ## Quattroshapes +`sources=quattroshapes` | `sources=qs` + [Quattroshapes](http://quattroshapes.com/) provides global coverage of location data for: - countries @@ -28,6 +32,8 @@ Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2. ## OpenAddresses +`sources=openaddresses` | `sources=osm` + [OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses. OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding. @@ -36,6 +42,8 @@ As OpenAddresses is sourced from regional governments, its data is in the public ## Geonames +`sources=geonames` | `sources=gn` + [Geonames](http://www.geonames.org/) is an aggregation of many authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. While Geonames does not contain any shape data (such as country borders), it does have a powerful and well defined hierarchy to describe the relationships between different records. This custom hierarchy makes it harder to use in combination with data from other sources, but the Mapzen [Who's On First](http://whosonfirst.mapzen.com/) project will help by providing concordance between Geonames and other datasets. In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search. From d3911b97acd45d8167e783f2b30ba5ff723f142d Mon Sep 17 00:00:00 2001 From: Riordan Date: Mon, 28 Mar 2016 13:26:11 -0400 Subject: [PATCH 02/16] Deprecates quattroshapes --- data-sources.md | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/data-sources.md b/data-sources.md index 1f54b9c..cb47fe2 100644 --- a/data-sources.md +++ b/data-sources.md @@ -12,24 +12,6 @@ With its coverage of roads as well as rich metadata, OpenStreetMap is arguably t All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/licenses/odbl/), a [share-alike](https://en.wikipedia.org/wiki/Share-alike) license which also requires attribution. -## Quattroshapes - -`sources=quattroshapes` | `sources=qs` - -[Quattroshapes](http://quattroshapes.com/) provides global coverage of location data for: - -- countries -- regions (states/provinces) -- counties -- localities (cities, towns, hamlets, villages) -- neighborhoods (in many places) - -Originally assembled by Foursquare, Quattroshapes provides not only the organizational hierarchy for nearly any point or address worldwide (town > local government > province > country), but also the borders for each of these places. - -Mapzen Search uses data from Quattroshapes to apply a consistent hierarchy to our data from other sources, so you can be sure that points of interest have consistent data about the cities, regions, and countries in which they are located. - -Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2.0/), allowing its use for any purpose with proper attribution. - ## OpenAddresses `sources=openaddresses` | `sources=osm` @@ -49,3 +31,17 @@ As OpenAddresses is sourced from regional governments, its data is in the public In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search. Geonames data is licensed [CC BY](http://creativecommons.org/licenses/by/3.0/). + + +# Deprecated Sources +Certain data sources have previously been supported by Mapzen Search but are no longer offered part of the core service and have been superseded by a new data source. + +## Quattroshapes + +`sources=quattroshapes` | `sources=qs` + +Quattroshapes was previously used by Mapzen Search and its use was discontinued in April 2016. + +It has been replaced by Who's on First, which continues to provide global administrative place data (countries, regions, counties, cities) and administrative lookup (_"what country, region, and city is this address part of?"_). + +Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2.0/), allowing its use for any purpose with proper attribution. From 29a1934c09622f5fb4b836e8845dfe45cc68e873 Mon Sep 17 00:00:00 2001 From: Riordan Date: Mon, 28 Mar 2016 13:41:47 -0400 Subject: [PATCH 03/16] updated licenses for existing sources --- data-sources.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/data-sources.md b/data-sources.md index cb47fe2..552abfc 100644 --- a/data-sources.md +++ b/data-sources.md @@ -2,6 +2,8 @@ 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. +Attribution is required for many of our data providers. Some license information is provided, but you are responsible for researching each project to follow their license terms. + ## OpenStreetMap `sources=openstreetmap` | `sources=osm` @@ -20,7 +22,7 @@ All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/l OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding. -As OpenAddresses is sourced from regional governments, its data is in the public domain. +OpenAddresses is sourced from regional governments. Many of these sources require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses.html). Mapzen Search does not import OpenAddresses sources marked as Share-Alike by the OpenAddresses project. ## Geonames @@ -30,7 +32,7 @@ As OpenAddresses is sourced from regional governments, its data is in the public In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search. -Geonames data is licensed [CC BY](http://creativecommons.org/licenses/by/3.0/). +Geonames data is licensed [CC-BY-3.0](http://creativecommons.org/licenses/by/3.0/). # Deprecated Sources @@ -44,4 +46,4 @@ Quattroshapes was previously used by Mapzen Search and its use was discontinued It has been replaced by Who's on First, which continues to provide global administrative place data (countries, regions, counties, cities) and administrative lookup (_"what country, region, and city is this address part of?"_). -Quattroshapes data is licensed [CC BY](http://creativecommons.org/licenses/by/2.0/), allowing its use for any purpose with proper attribution. +Quattroshapes data is licensed [CC-BY-2.0](http://creativecommons.org/licenses/by/2.0/). From 9172b1c0aaefac475c35487f1c1ee4b635997945 Mon Sep 17 00:00:00 2001 From: Riordan Date: Mon, 28 Mar 2016 14:45:35 -0400 Subject: [PATCH 04/16] Adds WoF as a source --- data-sources.md | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/data-sources.md b/data-sources.md index 552abfc..5ca019f 100644 --- a/data-sources.md +++ b/data-sources.md @@ -4,6 +4,33 @@ Mapzen Search is powered by several major open data sets and owes a tremendous d Attribution is required for many of our data providers. Some license information is provided, but you are responsible for researching each project to follow their license terms. +## OpenAddresses + +`sources=openaddresses` | `sources=osm` + +[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses. + +OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding. + +OpenAddresses is sourced from regional governments. Many of these sources require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project. + +## Who's on First + +`sources=whosonfirst` | `sources=wof` + +[Who's on First](https://whosonfirst.mapzen.com) is an open data directory of worldwide "administrative places" created by Mapzen. It is our primary provider of: +- Countries +- Regions (e.g. States, Provinces) +- Counties +- Localities (cities, towns, hamlets) +- Neighbourhoods + +Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonames, and OpenAddresses, we use Who's on First to provide standardized fields for the country, region, locality, and neighbourhood (in addition to any other matching levels the place may fall within like counties or macro-regions). + +[License](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md) + + + ## OpenStreetMap `sources=openstreetmap` | `sources=osm` @@ -14,15 +41,6 @@ With its coverage of roads as well as rich metadata, OpenStreetMap is arguably t All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/licenses/odbl/), a [share-alike](https://en.wikipedia.org/wiki/Share-alike) license which also requires attribution. -## OpenAddresses - -`sources=openaddresses` | `sources=osm` - -[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses. - -OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding. - -OpenAddresses is sourced from regional governments. Many of these sources require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses.html). Mapzen Search does not import OpenAddresses sources marked as Share-Alike by the OpenAddresses project. ## Geonames From 239883d54c1bdf4ebce02fbc6dabe6701523c4bb Mon Sep 17 00:00:00 2001 From: Riordan Date: Mon, 28 Mar 2016 14:50:04 -0400 Subject: [PATCH 05/16] Adds layers to each source description --- data-sources.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/data-sources.md b/data-sources.md index 5ca019f..7158322 100644 --- a/data-sources.md +++ b/data-sources.md @@ -8,6 +8,9 @@ Attribution is required for many of our data providers. Some license information `sources=openaddresses` | `sources=osm` +Layers: +- `address` + [OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses. OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding. @@ -18,6 +21,16 @@ OpenAddresses is sourced from regional governments. Many of these sources requir `sources=whosonfirst` | `sources=wof` +Layers: +- `country` +- `region` +- `county` +- `locality` +- `localadmin` +- `neighbourhood` +- `coarse` (alias for simultaneously using all of the above) + + [Who's on First](https://whosonfirst.mapzen.com) is an open data directory of worldwide "administrative places" created by Mapzen. It is our primary provider of: - Countries - Regions (e.g. States, Provinces) @@ -35,6 +48,10 @@ Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonam `sources=openstreetmap` | `sources=osm` +Layers: +- `address` +- `venue` + [OpenStreetMap](https://www.openstreetmap.org/) is a community-driven, editable map of the world. It prioritizes local knowledge and individual contributions over bulk imports, which often means it has excellent coverage even in remote areas where no large-scale mapping efforts have been attempted. OpenStreetMap contains information on landmarks, buildings, roads, and natural features. With its coverage of roads as well as rich metadata, OpenStreetMap is arguably the most valuable dataset used by Mapzen Search for general usage. @@ -46,6 +63,16 @@ All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/l `sources=geonames` | `sources=gn` +Layers: +- `venue` +- `country` +- `region` +- `county` +- `locality` +- `localadmin` +- `neighbourhood` +- `coarse` (alias for simultaneously using all of the above) + [Geonames](http://www.geonames.org/) is an aggregation of many authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. While Geonames does not contain any shape data (such as country borders), it does have a powerful and well defined hierarchy to describe the relationships between different records. This custom hierarchy makes it harder to use in combination with data from other sources, but the Mapzen [Who's On First](http://whosonfirst.mapzen.com/) project will help by providing concordance between Geonames and other datasets. In the meantime, Geonames still provides a wide variety of useful data that helps augment the other datasets used by Mapzen Search. From 8769be172bc97fe853cfafdbb6c5ca32d8f6a9b1 Mon Sep 17 00:00:00 2001 From: Riordan Date: Tue, 29 Mar 2016 06:41:13 -0400 Subject: [PATCH 06/16] Search Page de-quattroshaped Still outstanding: - `layers` for macrocounty and macroregion? --- search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/search.md b/search.md index e42fd87..b960993 100644 --- a/search.md +++ b/search.md @@ -291,7 +291,7 @@ The search examples so far have returned a mix of results from all the data sour |---|---|---| | [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` | | [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` | -| [Quattroshapes](http://quattroshapes.com/) | `quattroshapes` | `qs` | +| [Who's on First](https://whosonfirst.mapzen.com) | 'whosonfirst' | 'wof' | | [GeoNames](http://www.geonames.org/) | `geonames` | `gn` | If you use the `sources` parameter, you can choose which of these data sources to include in your search. So if you're only interested in finding a YMCA in data from OpenAddresses, for example, you can build a query specifying that data source. From 9ac6d3754888b5a29ceccd604a0eb9e255fb1133 Mon Sep 17 00:00:00 2001 From: Riordan Date: Tue, 29 Mar 2016 06:49:44 -0400 Subject: [PATCH 07/16] Reverse gets layers and sources list --- reverse.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/reverse.md b/reverse.md index 8c00026..4974880 100644 --- a/reverse.md +++ b/reverse.md @@ -16,7 +16,7 @@ To get started with reverse geocoding, you need a [free, developer API key](http >[/v1/reverse?api_key=search-XXXXXXX&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471) -Notice that the first result is the Eiffel Tower (well, Tour Eiffel). The output is the standard GeoJSON format. +Notice that the first result is the Eiffel Tower (well, _Tour Eiffel_). The output is the standard GeoJSON format. ## Reverse geocoding parameters @@ -44,12 +44,32 @@ The default value for `size` is `10` and the maximum value is `40`. Specifying a By default, reverse geocoding returns results from any [data source](data-sources.md) available to Mapzen Search. To filter results by source, specify one or more valid source names in a comma-delimited list using the `sources` parameter. For example, the following request returns only results from OpenStreetMap: +| source | name | short name | +|---|---|---| +| [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` | +| [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` | +| [Who's on First](https://whosonfirst.mapzen.com) | 'whosonfirst' | 'wof' | +| [GeoNames](http://www.geonames.org/) | `geonames` | `gn` | + >[/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&sources=osm) -### Filter by layers +### Filter by layers (data type) Without specifying further, reverse geocoding doesn't restrict results to a particular type (street, venue, neighbourhood, and so on). If your application is only concerned with, say, which city a latitude, longitude is closest to, then use the `layers` parameter. For example, the following request returns only results that are localities (cities and towns): +|layer|description| +|----|----| +|`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| +|`localadmin`|local administrative boundaries| +|`neighbourhood`|social communities, neighbourhoods| +|`coarse`|alias for simultaneously using `country`, `region`, `county`, `locality`, `localadmin`, and `neighbourhood`| + + >[/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471&layers=locality) ### Filter by country @@ -60,9 +80,9 @@ If you are performing a reverse geocode near a country boundary, and are only in Note that `UK` is not a valid ISO 3166-1 alpha-2 country code. -## Confidence scores for the results +## Distance Confidence scores for the results -Each result returned has 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 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 --- | --- From f39cd26ce2c0b18b7ce0f827f236c57b66223b9a Mon Sep 17 00:00:00 2001 From: Riordan Date: Tue, 29 Mar 2016 07:01:44 -0400 Subject: [PATCH 08/16] response + reverse distance --- response.md | 70 ++++++++++++++++++++++++++++++----------------------- reverse.md | 2 +- 2 files changed, 41 insertions(+), 31 deletions(-) diff --git a/response.md b/response.md index a38a391..2743f30 100644 --- a/response.md +++ b/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", - "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 + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -73.990425, + 40.744131 ] + }, + "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 -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. +### `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). 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. diff --git a/reverse.md b/reverse.md index 4974880..b300701 100644 --- a/reverse.md +++ b/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 --- | --- From 0ec1bf3ec18486b845c971d08e80efdaf5cbcb3f Mon Sep 17 00:00:00 2001 From: Riordan Date: Tue, 29 Mar 2016 16:15:52 -0400 Subject: [PATCH 09/16] Run through Retext. All same as before now passing --- data-sources.md | 12 ++++++------ place.md | 2 +- search.md | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/data-sources.md b/data-sources.md index 7158322..0fb411a 100644 --- a/data-sources.md +++ b/data-sources.md @@ -28,17 +28,17 @@ Layers: - `locality` - `localadmin` - `neighbourhood` -- `coarse` (alias for simultaneously using all of the above) +- `coarse` (alias for simultaneously using all the above) [Who's on First](https://whosonfirst.mapzen.com) is an open data directory of worldwide "administrative places" created by Mapzen. It is our primary provider of: - Countries -- Regions (e.g. States, Provinces) +- Regions (for example: States, Provinces) - Counties - Localities (cities, towns, hamlets) - Neighbourhoods -Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonames, and OpenAddresses, we use Who's on First to provide standardized fields for the country, region, locality, and neighbourhood (in addition to any other matching levels the place may fall within like counties or macro-regions). +Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonames, and OpenAddresses, we use Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. Other matching levels the place may fall within `macro-county` or `macro-region` taxonomy from Who's on Firsts. [License](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md) @@ -71,7 +71,7 @@ Layers: - `locality` - `localadmin` - `neighbourhood` -- `coarse` (alias for simultaneously using all of the above) +- `coarse` (alias for simultaneously using all the above) [Geonames](http://www.geonames.org/) is an aggregation of many authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. While Geonames does not contain any shape data (such as country borders), it does have a powerful and well defined hierarchy to describe the relationships between different records. This custom hierarchy makes it harder to use in combination with data from other sources, but the Mapzen [Who's On First](http://whosonfirst.mapzen.com/) project will help by providing concordance between Geonames and other datasets. @@ -81,13 +81,13 @@ Geonames data is licensed [CC-BY-3.0](http://creativecommons.org/licenses/by/3.0 # Deprecated Sources -Certain data sources have previously been supported by Mapzen Search but are no longer offered part of the core service and have been superseded by a new data source. +Certain data sources used to be supported by Mapzen Search but are no longer offered part of the core service and have been superseded by a new data source. ## Quattroshapes `sources=quattroshapes` | `sources=qs` -Quattroshapes was previously used by Mapzen Search and its use was discontinued in April 2016. +Quattroshapes used to be supported by Mapzen Search and its use was discontinued in April 2016. It has been replaced by Who's on First, which continues to provide global administrative place data (countries, regions, counties, cities) and administrative lookup (_"what country, region, and city is this address part of?"_). diff --git a/place.md b/place.md index 93defdd..fbac615 100644 --- a/place.md +++ b/place.md @@ -16,7 +16,7 @@ https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:venue:5013364 ## Search for multiple places in a query -To search for more than one `/place` in a request, join multiple values together and separate them with a comma. For example, this /place query looks up the Eiffel Tower in OSM and `30 West 26th St, New York, NY` in OpenAddresses: +To search for more than one `/place` in a request, join multiple values together and separate them with a comma. For example, this /place query looks up the Eiffel Tower in OpenStreetMap and `30 West 26th St, New York, NY` in OpenAddresses: https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:venue:5013364,oa:address:65cf57e4eb5548eca9bb548fb1461633 diff --git a/search.md b/search.md index b960993..fb77ca0 100644 --- a/search.md +++ b/search.md @@ -160,7 +160,7 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary Sometimes you don't have a rectangle to work with, but rather you have a point on earth—for example, your location coordinates—and a maximum distance within which acceptable results can be located. -In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` represents your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers. +In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` is your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers. > [/v1/search?api_key=search-XXXXXXX&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35) From efc1283b2f0dc69e53205d6605f2f34cad4c9a50 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 1 Apr 2016 14:00:41 -0700 Subject: [PATCH 10/16] minor formatting changes to data-sources --- data-sources.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/data-sources.md b/data-sources.md index 0fb411a..784888e 100644 --- a/data-sources.md +++ b/data-sources.md @@ -11,11 +11,11 @@ Attribution is required for many of our data providers. Some license information Layers: - `address` -[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with over 200 million addresses. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses. +[OpenAddresses](http://openaddresses.io/) is a collection of over 200 million addresses around the world. Data in OpenAddresses only comes from national, state, and local governments, so this data is highly authoritative. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses. -OpenAddresses is by far the largest dataset by number of records used by Mapzen Search, so even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding. +OpenAddresses is by far the largest dataset by number of records used by Mapzen Search. Even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding. -OpenAddresses is sourced from regional governments. Many of these sources require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project. +Many of the sources used in OpenAddresses require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project. ## Who's on First @@ -30,20 +30,17 @@ Layers: - `neighbourhood` - `coarse` (alias for simultaneously using all the above) - -[Who's on First](https://whosonfirst.mapzen.com) is an open data directory of worldwide "administrative places" created by Mapzen. It is our primary provider of: +[Who's on First](https://whosonfirst.mapzen.com) is an open-data directory of worldwide administrative places created by Mapzen. It is the primary provider of: - Countries -- Regions (for example: States, Provinces) +- Regions (for example: states, provinces) - Counties - Localities (cities, towns, hamlets) - Neighbourhoods -Additionally, for addresses and venues (POI's) coming from OpenStreetMap, Geonames, and OpenAddresses, we use Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. Other matching levels the place may fall within `macro-county` or `macro-region` taxonomy from Who's on Firsts. +Additionally, for addresses, venues, and points of interest coming from OpenStreetMap, Geonames, and OpenAddresses, Mapzen Search uses Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. Other matching levels the place may fall within `macro-county` or `macro-region` taxonomy from Who's on Firsts. [License](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md) - - ## OpenStreetMap `sources=openstreetmap` | `sources=osm` @@ -58,7 +55,6 @@ With its coverage of roads as well as rich metadata, OpenStreetMap is arguably t All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/licenses/odbl/), a [share-alike](https://en.wikipedia.org/wiki/Share-alike) license which also requires attribution. - ## Geonames `sources=geonames` | `sources=gn` @@ -79,8 +75,7 @@ In the meantime, Geonames still provides a wide variety of useful data that help Geonames data is licensed [CC-BY-3.0](http://creativecommons.org/licenses/by/3.0/). - -# Deprecated Sources +# Deprecated sources Certain data sources used to be supported by Mapzen Search but are no longer offered part of the core service and have been superseded by a new data source. ## Quattroshapes From bae12ca5644abbfa28e6866e956d69417acd26d7 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 1 Apr 2016 14:01:57 -0700 Subject: [PATCH 11/16] remove qs from place query --- place.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/place.md b/place.md index fbac615..e86065b 100644 --- a/place.md +++ b/place.md @@ -2,7 +2,7 @@ When you know an identification number and the source it came from, you can use Mapzen Search to get details on the location. -To get started with a `/place` search, you need a [free, developer API key](https://mapzen.com/developers) and these three pieces of information: +To get started with a `/place` search, you need a [developer API key](https://mapzen.com/developers) and these three pieces of information: * source - the data source, such as OpenStreetMap * layer - the type of place, such as a venue, address, or country. @@ -35,4 +35,3 @@ source | layers `osm` or `openstreetmap` | `venue`, `address` `oa` or `openaddresses` | `address` `gn` or `geonames` | `venue`, `address`, `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse` -`qs` or `quattroshapes` | `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse` From c530af93f60382f83bfa08c817515ad4bf78b87d Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 1 Apr 2016 14:22:35 -0700 Subject: [PATCH 12/16] formatting, update leaflet plug-in URL --- response.md | 2 +- reverse.md | 2 +- use-cors.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/response.md b/response.md index 2743f30..f89869b 100644 --- a/response.md +++ b/response.md @@ -64,7 +64,7 @@ Additionally, `/reverse` queries will have a `distance` parameter, which is the ## 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). 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. +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, Mapzen Search includes 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. diff --git a/reverse.md b/reverse.md index b300701..cd35197 100644 --- a/reverse.md +++ b/reverse.md @@ -12,7 +12,7 @@ With reverse geocoding with Mapzen Search, you can look up all sorts of informat * postal areas * countries -To get started with reverse geocoding, you need a [free, developer API key](https://mapzen.com/developers) and a latitude, longitude pair in decimal degrees specified with the parameters `point.lat` and `point.lon`, respectively. For example, the Eiffel Tower in Paris, France, is located at `48.858268,2.294471`. The reverse geocode query for this would be: +To get started with reverse geocoding, you need a [developer API key](https://mapzen.com/developers) and a latitude, longitude pair in decimal degrees specified with the parameters `point.lat` and `point.lon`, respectively. For example, the Eiffel Tower in Paris, France, is located at `48.858268,2.294471`. The reverse geocode query for this would be: >[/v1/reverse?api_key=search-XXXXXXX&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=48.858268&point.lon=2.294471) diff --git a/use-cors.md b/use-cors.md index c250ce1..3151352 100644 --- a/use-cors.md +++ b/use-cors.md @@ -12,11 +12,11 @@ You don’t need to do anything special to use `CORS` with JavaScript in a moder For a full list of supported browsers see: http://caniuse.com/#feat=cors -### Add a Pelias search box to a Leaflet map +### Add a search box to a Leaflet map -Mapzen provides a plug-in that adds a Pelias search box to any [Leaflet](http://leafletjs.com/)-powered map. +Mapzen provides a plug-in that adds a search box to any [Leaflet](http://leafletjs.com/)-powered map. -See https://github.com/pelias/leaflet-geocoder for installation instructions and a live demo. +See https://github.com/mapzen/leaflet-geocoder for installation instructions and a live demo. There is also a [tutorial](add-search-to-a-map.md) available. ### Loading data with jQuery From ab0900deabe4a92d28038d00cec02262147f6243 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 1 Apr 2016 14:39:34 -0700 Subject: [PATCH 13/16] formatting, add w3c link, we to mapzen --- data-sources.md | 4 ++-- transition-from-beta.md | 4 ++-- use-cors.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/data-sources.md b/data-sources.md index 784888e..d6c56db 100644 --- a/data-sources.md +++ b/data-sources.md @@ -2,7 +2,7 @@ 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. -Attribution is required for many of our data providers. Some license information is provided, but you are responsible for researching each project to follow their license terms. +Attribution is required for many of the Mapzen Search data providers. Some license information is listed here, but you are responsible for researching each project to follow their license terms. ## OpenAddresses @@ -30,7 +30,7 @@ Layers: - `neighbourhood` - `coarse` (alias for simultaneously using all the above) -[Who's on First](https://whosonfirst.mapzen.com) is an open-data directory of worldwide administrative places created by Mapzen. It is the primary provider of: +[Who's on First](https://whosonfirst.mapzen.com) is an open-data directory of worldwide administrative places. Created by Mapzen, it is the primary provider of: - Countries - Regions (for example: states, provinces) - Counties diff --git a/transition-from-beta.md b/transition-from-beta.md index 58fb533..9643385 100644 --- a/transition-from-beta.md +++ b/transition-from-beta.md @@ -71,7 +71,7 @@ Most parameters (and options) for search have been renamed: | `size` | `count` | Number of responses. Minimum: 1, maximum: 50 | | `layers` | `layers` (SEE BELOW) | While the parameter remains the same, the options have changed. See the table below for a description.| | `bbox` | `boundary.rect.min_lon`, `boundary.rect.min_lat`, `boundary.rect.max_lon`, `boundary.rect.max_lat`| Bounding box parameters are now individually specified to prevent error.| -| `details` | Deprecated (for the moment) | `details=false` used to respond with a minimized set of elements. We are reevaluating which elements of the response document make most sense for minimization. If you've got opinions, let us know at [search@mapzen.com](mailto:search@mapzen.com)| +| `details` | Deprecated (for the moment) | `details=false` used to respond with a minimized set of elements. Mapzen is reevaluating which elements of the response document make most sense for minimization. If you've got opinions, let us know at [search@mapzen.com](mailto:search@mapzen.com)| `layers` used to be opaque about many of the kinds of places they represented (particularly the administrative layers). `layers` were also used to retrieve places from a particular source. `sources` is now a separate parameter from `layers` to help improve clarity. @@ -190,7 +190,7 @@ Instead, Mapzen Search supports [Cross-Origin Resource Sharing](https://develope Mapzen Search is set to allow CORS requests from all domains. ### HTTPS -Mapzen Search continues to support HTTPS and traditional HTTP. We encourage you to use HTTPS instead of HTTP, especially when handling sensitive personal information (such as users' searches or users' location data). +Mapzen Search continues to support HTTPS and traditional HTTP. You are encouraged to use HTTPS instead of HTTP, especially when handling sensitive personal information (such as users' searches or users' location data). ## What's happening to pelias.mapzen.com? The beta API available at pelias.mapzen.com will be available through the end of November, 2015. Starting December 1, 2015, you will only be able to use search.mapzen.com or your own hosted version of Pelias. diff --git a/use-cors.md b/use-cors.md index 3151352..faa61f4 100644 --- a/use-cors.md +++ b/use-cors.md @@ -6,9 +6,9 @@ Fortunately, techniques have since been developed that allow developers to secur ## Cross-Origin Resource Sharing (CORS) -`CORS` is the recommended standard for allowing your web browser and a web server to negotiate and allow requests to be made across domain contexts. `CORS` is supported in modern Chrome, Firefox, Safari, and Internet Explorer (10+) web browsers. It became an official W3C Recommendation on the 16th January 2014. +`CORS` is the recommended standard for allowing your web browser and a web server to negotiate and allow requests to be made across domain contexts. `CORS` is supported in modern Chrome, Firefox, Safari, and Internet Explorer (10+) web browsers. It became a [W3C Recommendation](https://www.w3.org/TR/cors/) in 2014. -You don’t need to do anything special to use `CORS` with JavaScript in a modern browser. Your web browser and our servers will automatically negotiate the cross-origin request. For example, to make a `CORS` request with `jQuery`, you’d make your request like you were performing it within the context of your own domain. +You don’t need to do anything special to use `CORS` with JavaScript in a modern browser. Your web browser and the Mapzen Search servers will automatically negotiate the cross-origin request. For example, to make a `CORS` request with `jQuery`, you’d make your request like you were performing it within the context of your own domain. For a full list of supported browsers see: http://caniuse.com/#feat=cors From 3583ae6eeed817b54e83998446e93cd3e0842a88 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 1 Apr 2016 15:30:20 -0700 Subject: [PATCH 14/16] remove free, add bullet list to index --- api-keys-rate-limits.md | 4 ++-- autocomplete.md | 2 +- get-started.md | 2 +- glossary.md | 2 +- index.md | 10 ++++++++++ search.md | 2 +- transition-from-beta.md | 2 +- 7 files changed, 17 insertions(+), 7 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index 7b191a3..480da01 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -2,7 +2,7 @@ ## Get an API key -To use the Mapzen Search service, you must first get a free developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys. +To use the Mapzen Search service, you must first get a developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys. 1. Go to https://mapzen.com/developers. 2. Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first. @@ -10,7 +10,7 @@ To use the Mapzen Search service, you must first get a free developer API key. S 4. Copy the key into your code. ## Rate limits -Because Mapzen Search is a free, shared service, there are limitations on the numbers of requests to prevent individual users from degrading system performance. +Because Mapzen Search is a shared service, there are limitations on the numbers of requests to prevent individual users from degrading system performance. Mapzen Search allows you a maximum of: diff --git a/autocomplete.md b/autocomplete.md index 5b9bbf7..f7d2345 100644 --- a/autocomplete.md +++ b/autocomplete.md @@ -2,7 +2,7 @@ If you are building an end-user application, you can use the `/autocomplete` endpoint alongside `/search` to enable real-time feedback. This type-ahead functionality helps users find what they are looking for, without requiring them to fully specify their search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list below. -To build a query with autocomplete, you need [a free, API developer key](https://mapzen.com/developers) and a `text` parameter, representing what a user has typed into your application so far. Optionally, you can specify a geographic point where the search is focused, this will allow users to see more local places in the results. +To build a query with autocomplete, you need an [API key](https://mapzen.com/developers) and a `text` parameter, representing what a user has typed into your application so far. Optionally, you can specify a geographic point where the search is focused, this will allow users to see more local places in the results. ## User experience guidelines diff --git a/get-started.md b/get-started.md index fc32aba..0f50fa8 100644 --- a/get-started.md +++ b/get-started.md @@ -1,6 +1,6 @@ # Get started with Mapzen Search -[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and powered entirely by open data. To start integrating Mapzen Search to your apps, you need a [free, developer API key](api-keys-rate-limits.md). You might use this functionality in any app that has a geographic part, including ones that deliver goods, locate hotels or venues, or even provide local weather forecasts. +[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and powered entirely by open data. To start integrating Mapzen Search to your apps, you need an [API key](api-keys-rate-limits.md). You might use this functionality in any app that has a geographic part, including ones that deliver goods, locate hotels or venues, or even provide local weather forecasts. Through a process known as [geocoding](search.md), Mapzen Search allows you to use natural language to find a particular place by entering an address or the name of a landmark or business, and then translates the result in to the geographic coordinates used by computers. Mapzen Search accesses [global databases](data-sources.md) of place names and locations, but you can receive more locally relevant search results by limiting the search to a particular radius around a location (such as a cell phone), region, or country. With text [autocompletion capabilities](autocomplete.md), you can search for places and match against Mapzen Search data in real-time. diff --git a/glossary.md b/glossary.md index a619fcf..88a9e92 100644 --- a/glossary.md +++ b/glossary.md @@ -10,7 +10,7 @@ ## Mapzen Search API and developer terms - **API endpoint** - an architectural style for accessing web resources through a URL. In Mapzen Search, available endpoints include `search`, `reverse`, and `autocomplete`. You can construct a URL to send queries and receive responses from Mapzen Search. -- **API key** - an code that identifies the developer account without providing a password. Mapzen Search requires a free, API key to interact with the search service. +- **API key** - an code that identifies the developer account without providing a password. Mapzen Search requires an API key to interact with the search service. - **autocomplete** - enables real-time feedback when entering text for a search, typically, where users start typing and a drop-down list appears where they can choose the term from the list below. Use the `autocomplete` endpoint to do this. - **data source** - the datasets available to Mapzen Search. Only data sources that have open-source licenses are used. - **focus** - option to make places closer to a particular location be prioritized and appear higher in the search results list. After all nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization. diff --git a/index.md b/index.md index 71d3332..2eb86b3 100644 --- a/index.md +++ b/index.md @@ -3,3 +3,13 @@ Through a process known as [geocoding](search.md), Mapzen Search allows you to use natural language to find a particular place by entering an address or the name of a landmark or business, and then translates the result in to the geographic coordinates used by computers. Mapzen Search accesses [global databases](data-sources.md) of place names and locations, but you can receive more locally relevant search results by limiting the search to a particular radius around a location (such as a cell phone), region, or country. With text [autocompletion capabilities](autocomplete.md), you can search for places and match against Mapzen Search data in real-time. Mapzen Search also enables the opposite workflow, known as [reverse geocoding](reverse.md), to transform latitude and longitude values in to a list of places. This process attempts to find the name and address of the place nearest a longitude and latitude pair. For example, you can click a position on the map to learn which business is located there. + +## Features of Mapzen Search + +- Forward geocoding to find a place by searching for an address or name +- Reverse geocoding to find what is located at a certain coordinate location +- Autocomplete to give real-time result suggestions without having to type the whole location +- Global coverage with prioritized local results +- Open-source software using open data sources +- Plug-in for embedding search in a Leaflet-based maps +- API with generous rate limits diff --git a/search.md b/search.md index fb77ca0..288c2cb 100644 --- a/search.md +++ b/search.md @@ -4,7 +4,7 @@ Geospatial search, commonly referred to as geocoding, is the process of matching There's nothing inherent in the language we use to describe a physical address that allows us to convert that human readable sentence in to a format that a computer can understand, such as latitude & longitude. -Making the leap from text to coordinates is an intricate and challenging process. Lucky for you, Mapzen has done all the hard work and made it accessible though a free web service. +Making the leap from text to coordinates is an intricate and challenging process. Lucky for you, Mapzen has done all the hard work and made it accessible though a web service. All Mapzen Search requests share the same format: diff --git a/transition-from-beta.md b/transition-from-beta.md index 9643385..7ab5b7b 100644 --- a/transition-from-beta.md +++ b/transition-from-beta.md @@ -9,7 +9,7 @@ The changes aren't too drastic and should be implementable in an afternoon or a These changes also affect self-hosted users of Pelias upgrading from the beta to 1.0 (leaving aside API key restrictions), but these users can make the upgrade on their own time. ## API keys -The first big change is the introduction of API keys. Like all other Mapzen APIs, Search now requires a free API key. You can register at the [Mapzen Developer Portal](https://mapzen.com/developers) and generate one (or more) for all your search needs. +The first big change is the introduction of API keys. Like all other Mapzen APIs, Search now requires an API key. You can register at the [Mapzen Developer Portal](https://mapzen.com/developers) and generate one (or more) for all your search needs. Mapzen Search API keys allow you: From d333c83abb695fe9316fea7bb340c7b380728934 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 1 Apr 2016 15:59:36 -0700 Subject: [PATCH 15/16] fix typo in api key definition --- glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/glossary.md b/glossary.md index 88a9e92..983fa14 100644 --- a/glossary.md +++ b/glossary.md @@ -10,7 +10,7 @@ ## Mapzen Search API and developer terms - **API endpoint** - an architectural style for accessing web resources through a URL. In Mapzen Search, available endpoints include `search`, `reverse`, and `autocomplete`. You can construct a URL to send queries and receive responses from Mapzen Search. -- **API key** - an code that identifies the developer account without providing a password. Mapzen Search requires an API key to interact with the search service. +- **API key** - a code that identifies the developer account without providing a password. Mapzen Search requires an API key to interact with the search service. - **autocomplete** - enables real-time feedback when entering text for a search, typically, where users start typing and a drop-down list appears where they can choose the term from the list below. Use the `autocomplete` endpoint to do this. - **data source** - the datasets available to Mapzen Search. Only data sources that have open-source licenses are used. - **focus** - option to make places closer to a particular location be prioritized and appear higher in the search results list. After all nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization. From ffc285d275d680c1f0ff1462aeee4f5a650a0933 Mon Sep 17 00:00:00 2001 From: Riordan Date: Mon, 11 Apr 2016 14:24:34 -0400 Subject: [PATCH 16/16] Updated to WoF bbox + [admin]_gid --- data-sources.md | 8 ++++-- index.md | 2 +- response.md | 72 +++++++++++++++++++++++++------------------------ 3 files changed, 44 insertions(+), 38 deletions(-) diff --git a/data-sources.md b/data-sources.md index d6c56db..bda034a 100644 --- a/data-sources.md +++ b/data-sources.md @@ -15,7 +15,7 @@ Layers: OpenAddresses is by far the largest dataset by number of records used by Mapzen Search. Even though it only contains address data (as in no building names or other metadata), it's a great resource for global geocoding. -Many of the sources used in OpenAddresses require [attribution (LINK NOT LIVE)](https://www.mapzen.com/copyright/openaddresses). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project. +Many of the sources used in OpenAddresses require [attribution](https://mapzen.com/rights/). Mapzen Search _does not_ import OpenAddresses sources marked as Share-Alike by the OpenAddresses project. ## Who's on First @@ -23,7 +23,9 @@ Many of the sources used in OpenAddresses require [attribution (LINK NOT LIVE)]( Layers: - `country` +- `macroregion` - `region` +- `macrocounty` - `county` - `locality` - `localadmin` @@ -32,12 +34,14 @@ Layers: [Who's on First](https://whosonfirst.mapzen.com) is an open-data directory of worldwide administrative places. Created by Mapzen, it is the primary provider of: - Countries +- Macroregions (e.g. England is a Macroregion within the United Kingdom) - Regions (for example: states, provinces) +- Macro-counties (e.g. [Departments of France](https://en.wikipedia.org/wiki/Departments_of_France)) - Counties - Localities (cities, towns, hamlets) - Neighbourhoods -Additionally, for addresses, venues, and points of interest coming from OpenStreetMap, Geonames, and OpenAddresses, Mapzen Search uses Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. Other matching levels the place may fall within `macro-county` or `macro-region` taxonomy from Who's on Firsts. +Additionally, for addresses, venues, and points of interest coming from OpenStreetMap, Geonames, and OpenAddresses, Mapzen Search uses Who's on First to provide standardized fields for the country, region, locality, and neighbourhood. [License](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md) diff --git a/index.md b/index.md index 2eb86b3..d54254f 100644 --- a/index.md +++ b/index.md @@ -1,4 +1,4 @@ -[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and powered entirely by open data. To start integrating Mapzen Search to your apps, you need a [developer API key](api-keys-rate-limits.md). You might use this functionality in any app that has a geographic element, including ones that deliver goods, locate hotels or venues, or even provide local weather forecasts. +[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and powered entirely by open data. To start integrating Mapzen Search to your apps, you need a [Mapzen developer API key](api-keys-rate-limits.md). You might use this functionality in any app that has a geographic element, including ones that deliver goods, locate hotels or venues, or even provide local weather forecasts. Through a process known as [geocoding](search.md), Mapzen Search allows you to use natural language to find a particular place by entering an address or the name of a landmark or business, and then translates the result in to the geographic coordinates used by computers. Mapzen Search accesses [global databases](data-sources.md) of place names and locations, but you can receive more locally relevant search results by limiting the search to a particular radius around a location (such as a cell phone), region, or country. With text [autocompletion capabilities](autocomplete.md), you can search for places and match against Mapzen Search data in real-time. diff --git a/response.md b/response.md index f89869b..ae9bdee 100644 --- a/response.md +++ b/response.md @@ -21,42 +21,41 @@ The `features` property of the result is where you will find the list of results Each item in this list will contain all the information needed to find it in human-readable format in the `properties` block, as well as computer friendly coordinates in the `geometry` property. -```json +``` json { - "type": "Feature", - "geometry": { - "type": "Point", - "coordinates": [ - -73.990425, - 40.744131 - ] - }, - "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" - } + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -0.125422, + 51.501581 + ] + }, + "properties": { + "id": "101750367", + "gid": "whosonfirst:locality:101750367", + "layer": "locality", + "source": "whosonfirst", + "name": "London", + "confidence": 0.949, + "country": "United Kingdom", + "country_gid": "whosonfirst:country:85633159", + "country_a": "GBR", + "macroregion": "England", + "macroregion_gid": "whosonfirst:macroregion:404227469", + "region": "City of Westminster", + "region_gid": "whosonfirst:region:85684061", + "locality": "London", + "locality_gid": "whosonfirst:locality:101750367", + "label": "London, England, United Kingdom" + }, + "bbox": [ + -0.4984345, + 51.297207, + 0.27894, + 51.6843015 + ] + }, ``` Additionally, `/reverse` queries will have a `distance` parameter, which is the distance, in meters, from the query point. @@ -80,6 +79,9 @@ For the `/search` endpoint, it primarily takes into account how well properties 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` +`Feature`s coming from _Who's on First_ and OpenStreetMap ways will 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 (e.g. 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 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.