From ed892189ff7f025ab8bb5abe39becc9b0d6569cd Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 25 Sep 2015 16:51:29 -0700 Subject: [PATCH 01/13] Minor rewrites and doc site formatting --- getting-started/001-api.md | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/getting-started/001-api.md b/getting-started/001-api.md index 03ebb18..b33ff80 100644 --- a/getting-started/001-api.md +++ b/getting-started/001-api.md @@ -1,26 +1,22 @@ -API Keys -========= +# API keys and rate limits -# Obtaining an API Key +## Obtain an API key -To use the Mapzen Search service, you must first obtain a free developer API key from Mapzen. Sign in at https://mapzen.com/developers to create and manage your API keys. +To use the Mapzen Search service, you must first obtain a free, developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys. -Mapzen Search is a free, shared geocoding service. As such, there are limitations on requests to prevent individual users from degrading the overall system performance. +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. +3. Create a new key for Mapzen Search, and optionally, give it a name so you can remember the purpose of the project. +4. Copy the key into your code. -Go to https://mapzen.com/developers. -Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first. -Create a new key for Mapzen Search, and optionally, give it a name so you can remember the purpose of the project. -Keep the web page open so you can copy the key into the code later. +## Rate limits +Because Mapzen Search is a free, shared service, there are limitations on the numbers of requests to prevent individual users from degrading the overall system performance. - -# Rate Limits -As Mapzen Search is a free, shared service, we have rate limits that restrict the maximum number of requests per second and per day. - -Our free API keys allow you a maximum of: +Mapzen Search allows you a maximum of: - 3 requests per second - 30,000 requests per day -If you need more capacity, you can get in touch with [search@mapzen.com](mailto:search@mapzen.com), or set up your own instance of [Pelias](https://github.com/pelias/pelias), which we provide with access to all of the same data we use to power Mapzen Search. +If you need more capacity, contact [search@mapzen.com](mailto:search@mapzen.com). You can also set up your own instance of [Pelias](https://github.com/pelias/pelias), which has access to the same data used in Mapzen Search. -# Taking Care -Mapzen Search works over HTTPS in addition to HTTP. We strongly encourage you to use HTTPS for all requests, especially for queries involving potentially sensitive information, like a user's location or search query. +## Security +Mapzen Search works over HTTPS, in addition to HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query. From 01461afef7975fd544f6023f5f26fee2665bab37 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 25 Sep 2015 19:09:46 -0700 Subject: [PATCH 02/13] Updates for formatting, spelling, headings --- getting-started/002-search.md | 46 +++++++++++++++-------------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 587e9c5..089f869 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -1,19 +1,17 @@ -`SEARCH`, or Looking for Places -======= +# Mapzen Search: Finding places -Geospacial search, frequently reffered to as **geocoding** is the process of matching an address to its corresponding geographic coordinates. There's nothing inherent in the words we use to describe an address that conveys its location at some coordinates on earth, i.e. *[lat,lon]*. Making the leap from text to coordinates is an intricate and challenging process. Lucky for you, we've done all the hard work and made it accessible via a really simple and free web service. +Geospatial search, frequently referred to as geocoding, is the process of matching an address to its corresponding geographic coordinates. There's nothing inherent in the words we use to describe an address that conveys its location at some coordinates on earth, i.e. *[lat,lon]*. Making the leap from text to coordinates is an intricate and challenging process. Lucky for you, we've done all the hard work and made it accessible though a free web service. -:school: :barber: :bank: :us: :house_with_garden: :hospital: ......... :computer: +## Build a query +The Mapzen Search request takes the form of `https://search.mapzen.com/v1/search?api_key={your-api-key}`, where the JSON inputs inside the `{}` include search parameters such as the text to find and filtering options. Note that you must append your own Mapzen Search API key to the URL, following &api_key= at the end. -## Search the World +## Search the world ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_all.png) -In the simplest search, all you provide is the text you'd like to match in any part of the location details. So to accomplish this, you just set the `text` parameter to whatever you want to find. Let's see a few examples. +In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To accomplish this, build a query where the `text` is set to the item you want to find. -#### Example time - -Let's search for **YMCA**. Here's what you'd need to append to the base URL of the service, **search.mapzen.com**. +For example, if you want to find a [YMCA](https://en.wikipedia.org/wiki/YMCA) facility, here's what you'd need to append to the base URL of the service, `search.mapzen.com`. > [/v1/search?api_key={YOUR-KEY}&___text=YMCA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA) @@ -37,20 +35,19 @@ If you clicked on the query link above, you probably saw some cool **GeoJSON**, * YMCA, Jefferson, OH * YMCA, Belleville, IL -Note that the results are spread out throughout the world. Since we haven't told the service anything about our current location or any other geographic context. +Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search. -## Narrowing your Search... +## Narrow your search -Sometimes it's necessary to limit the search to a portion of the world. This can be useful if you're looking for places in a particular region, or country, or only want to look in the immediate viscinity of a user with a known location. Different usecases call for different specifications of this bounding region. We currently support three types: **rectangle**, **circle**, and **country**. +If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. Mapzen Search currently supports three types: country, rectangle, and country. -### ...to a specific country +### Search within a particular country ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_country.png) -Sometimes your usecase might require that all the search results are from a particular country. Well, we've got that covered! You just need to set the `boundary.country` parameter value to the **alpha-2** or **alpha-3** [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1). +Sometimes your work might require that all the search results be from a particular country. To do this, you can set the `boundary.country` parameter value to the alpha-2 or alpha-3 [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1). -#### Example time -Let's search for **YMCA** again, but this time only in **Great Britain**. We'll need to know that the **alpha-3** code for **Great Britain** is ***GBR*** and set the parameters like this: +Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is *GBR* and set the parameters like this: > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.country=GBR___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.country=GBR) @@ -73,7 +70,7 @@ Note that all the results reside within Great Britain: * YMCA, Lenton Abbey, Nottinghamshire * YMCA, Old Clee, Lincolnshire -Now you can try the same search request with different country codes and see the results change. +If you attempt the same search request with different country codes, you can see how the results change. > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.country=USA___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.country=USA) @@ -90,14 +87,12 @@ Results in the United States: * YMCA, Bremerton, WA * YMCA, Westerly, RI - -### ...to a rectangular region +### Search within a rectangular region ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_rect.png) - + In the case where you need to specify the boundary using a rectangle, all we need is a pair of coordinates on earth. Here are a few examples: -#### Example time Let's say you wanted to find museums in the state of **Texas**. You'd need to set the `boundary.rect.*` parameter grouping to values representing the bounding box around **Texas**: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5 ***PRO TIP:*** *You can lookup a bounding box for a known region [here](http://boundingbox.klokantech.com/)* @@ -124,14 +119,14 @@ Let's say you wanted to find museums in the state of **Texas**. You'd need to se * YMCA, Los Alamos, NM * YMCA, Tulsa, OK -#### ...to a circular region +### Search within a circular region ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_circle.png) Sometimes you don't have a rectangle to work with, but rather you've got a point on earth, for example your location coordinates, and a maximum distance within which acceptable results can be located. #### Example time -Find all **YMCA** locations within a **35km** radius of a spot in **Ontario, Canada**, +Find all **YMCA** locations within a **35km** radius of a spot in **Ontario, Canada**, This time, we'll use the `boundary.circle.*` parameter grouping to get the job done. `boundary.circle.lat` and `boundary.circle.lon` should be set to your location in **Madrid**, while `boundary.circle.radius` should be set to the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in **kilometers**. > [/v1/search?api_key={YOUR_API_KEY}&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35) @@ -391,7 +386,7 @@ we had to split it out into its own section. ## Result count You may have noticed that there were **10** places in the results for all the previous search examples. -That's the _default_ number of results the API will return, unless otherwise specified. +That's the _default_ number of results the API will return, unless otherwise specified. #### Example time Want a **single** result? Just set the `size` parameter to the desired number: @@ -413,11 +408,10 @@ How about *25* results? | `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `size` | ***25*** | - + ### **cApiTaliZAtioN** You may have noticed already that cApiTaliZAtioN isn't a big deal for search. You can type **ymca** or **YMCA** or even **yMcA**. See for yourself by comparing the results of the previous search to the following: > [/v1/search?api_key={YOUR-KEY}&___text=yMcA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yMcA) - From d2678b85055c6a5da68f064ad91b2c233c8ec5ef Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 25 Sep 2015 20:07:25 -0700 Subject: [PATCH 03/13] Rectangle, circle sections for consistency with examples --- getting-started/002-search.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 089f869..1b713bb 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -70,7 +70,7 @@ Note that all the results reside within Great Britain: * YMCA, Lenton Abbey, Nottinghamshire * YMCA, Old Clee, Lincolnshire -If you attempt the same search request with different country codes, you can see how the results change. +If you attempt the same search request with different country codes, the results change to reflect YMCA locations within the country. > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.country=USA___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.country=USA) @@ -91,13 +91,13 @@ Results in the United States: ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_rect.png) -In the case where you need to specify the boundary using a rectangle, all we need is a pair of coordinates on earth. Here are a few examples: +To specify the boundary using a rectangle, you need latitude, longitude coordinates for two corners of the bounding box (the mininum and the maximum latitude, longitude). -Let's say you wanted to find museums in the state of **Texas**. You'd need to set the `boundary.rect.*` parameter grouping to values representing the bounding box around **Texas**: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5 +For example, to find a YMCA within the state of Texas, you can set the `boundary.rect.*` parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5 -***PRO TIP:*** *You can lookup a bounding box for a known region [here](http://boundingbox.klokantech.com/)* + Tip: You can look up a bounding box for a known region with this [web tool](http://boundingbox.klokantech.com/)* -> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51) + [/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51) | parameter | value | | :--- | :--- | @@ -123,11 +123,9 @@ Let's say you wanted to find museums in the state of **Texas**. You'd need to se ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_circle.png) -Sometimes you don't have a rectangle to work with, but rather you've got a point on earth, for example your location coordinates, and a maximum distance within which acceptable results can be located. +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. -#### Example time -Find all **YMCA** locations within a **35km** radius of a spot in **Ontario, Canada**, -This time, we'll use the `boundary.circle.*` parameter grouping to get the job done. `boundary.circle.lat` and `boundary.circle.lon` should be set to your location in **Madrid**, while `boundary.circle.radius` should be set to 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` 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. > [/v1/search?api_key={YOUR_API_KEY}&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35) @@ -139,7 +137,7 @@ This time, we'll use the `boundary.circle.*` parameter grouping to get the job d | `boundary.circle.lon` | ***-79.186484*** | | `boundary.circle.radius` | ***35*** | -You can see the results have fewer than the standard 10 items, because there aren't that many YMCA locations in the specified radius: +You can see the results have fewer than the standard 10 items because there are not that many YMCA locations in the specified radius: > * YMCA, Toronto, Ontario * YMCA, Markham, Ontario From ef714c27352ccb4d5e8f9f4fda43798d2e775a32 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 25 Sep 2015 20:08:48 -0700 Subject: [PATCH 04/13] Formatting for mkdocs --- getting-started/000-getting-started.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/getting-started/000-getting-started.md b/getting-started/000-getting-started.md index a9870a5..ac39416 100644 --- a/getting-started/000-getting-started.md +++ b/getting-started/000-getting-started.md @@ -1,5 +1,4 @@ -Getting Started with Mapzen Search -=================================== +Get started with Mapzen Search Mapzen Search is a modern geocoding and place search service based on [Pelias](https://github.com/pelias/pelias), an experimental open geocoder from [Mapzen](https://mapzen.com) and powered by open data. It's used to transform the way people talk about places - with names and addresses - into geographic coordinates. @@ -14,4 +13,4 @@ Mapzen Search can be used to: Mapzen Search offers: - Advanced Geocoding tools - Coarse Geocoding -- +- From 5441dee21d648d82144a8b07c210fd5ed12e4300 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 25 Sep 2015 20:27:39 -0700 Subject: [PATCH 05/13] Update priority section for consistency --- getting-started/002-search.md | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 1b713bb..5a5dc44 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -146,24 +146,22 @@ You can see the results have fewer than the standard 10 items because there are * Pinnacle Jr YMCA, Toronto, Ontario * Cooper Koo Family Cherry Street YMCA Centre, Toronto, Ontario -### We respect your boundaries +### Specify multiple boundaries -If you're going to attempt using multiple boundary types in a single search request, be aware that the results will come from the **intersection** of all the boundaries! So if you provide regions that don't overlap, you'll be looking at an empty set of results. You've been warned. Here's a visual of how it works: +If you're going to attempt using multiple boundary types in a single search request, be aware that the results will come from the intersection of all the boundaries. So if you provide regions that don't overlap, you'll be looking at an empty set of results. You've been warned. Here's an image of how it works: ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/overlapping_boundaries.gif) +## Prioritize results by proximity +Many usecases call for the ability to promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. If that's your conundrum, here's what to do. -## Prioritizing Nearby Places -Many usecases call for the ability to surface nearby results to the front of the list, while still allow important matches from further away to be visible. If that's your conundrum, here's what you've got to do. - -### ...around a point of focus +### Prioritize around a point ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/focus_point.png) -Search will focus on a given point anywhere on earth, and results within **~100km** will be prioritized higher, thereby surfacing highest in the list. Once all the nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization. +Search will focus on a given point anywhere on earth, and results within 100 kilometers will be prioritized higher, thereby surfacing highest in the list. Once all the nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization. -#### Example time -Let's find **YMCA** again, but this time near **Sydney Opera House, Australia** +To find YMCA again, but this time near the a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia. > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281) @@ -174,7 +172,7 @@ Let's find **YMCA** again, but this time near **Sydney Opera House, Australia** | `focus.point.lat` | ***-33.856680*** | | `focus.point.lon` | ***151.215281*** | -Looking at the results, you can see that the few locations closer to **Sydney** show up at the top of the list, sorted by distance. You also still get back a significant amount of remote locations, for a well balanced mix. Oh, and since you provided a focus point, we can now compute distance from that point for each result, so check that out in each feature. +Looking at the results, you can see that the few locations closer to this location show up at the top of the list, sorted by distance. You also still get back a significant amount of remote locations, for a well balanced mix. Because you provided a focus point, Mapzen Search can compute distance from that point for each resulting feature. > * YMCA, Redfern, New South Wales [distance: 3.836] * YMCA, St Ives (NSW), New South Wales [distance: 14.844] @@ -187,15 +185,14 @@ Looking at the results, you can see that the few locations closer to **Sydney** * YMCA, 's-Gravenhage, Zuid-Holland [distance: 16688.292] * YMCA, Loughborough, United Kingdom [distance: 16978.367] -## Prioritizing within Boundaries -Now that we've seen how to use boundary and focus to narrow down and sort your results, let's examine a few scenarios where they work well together. +## Combine boundary search and prioritization +Now that you have seen how to use boundary and focus to narrow and sort your results, you can examine a few scenarios where they work well together. ### Prioritize within a country **TBD: insert image here** -#### Example time -Let's revisit the YMCA search we conducted with a focus around the Sydney Opera House. When providing only `focus.point`, we saw results come back from distant parts of the world, as expected. But say you wanted to only see results from the country in which your focus point lies. Let's combine that same focus point, Sydney Opera House, with the country boundary of Australia. Check this out. +Going back to the YMCA search you conducted with a focus around a point in Sydney, the results came back from distant parts of the world, as expected. But say you wanted to only see results from the country in which your focus point lies. You can combine that same focus point in Sydney with the country boundary of Australia like this. > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281) @@ -207,7 +204,7 @@ Let's revisit the YMCA search we conducted with a focus around the Sydney Opera | `focus.point.lon` | 151.215281 | | `boundary.country` | ***AUS*** | -The results below look very different from the ones we saw previously with only a focus point specified. These results are all from within Australia. You'll note the closest results show up at the beginning of the list, which is facilitated by the focus parameter. Pretty spectacular, right!? +The results below look very different from the ones you saw previously with only a focus point specified. These results are all from within Australia. You'll note the closest results show up at the top of the list, which is facilitated by the focus parameter. > * YMCA, Redfern, New South Wales [distance: 3.836] * YMCA, St Ives (NSW), New South Wales [distance: 14.844] @@ -220,11 +217,11 @@ The results below look very different from the ones we saw previously with only * YMCA, Sadadeen, Northern Territory [distance: 2026.731] * YMCA, Ararat, Victoria [distance: 841.022] -### Prioritize within a circular boundary +### Prioritize within a circular region **TBD: insert image here** -Let's say you're looking for the **nearest** YMCA locations, and are willing to travel no further than **50km** from your current location. You'd like the results to be sorted by distance from current location, in order to make your selection process easier. We can get this behavior by using `focus.point` in combination with `boundary.circle.*`. We can reuse the `focus.point.*` values as the `boundary.circle.lat` and `boundary.circle.lon`, and simply specify the required `boundary.circle.radius` value in kilometers. +If you are looking for the nearest YMCA locations, and are willing to travel no farther than 50 kilometers from your current location, you likely would want the results to be sorted by distance from current location to make your selection process easier. You can get this behavior by using `focus.point` in combination with `boundary.circle.*`. You can use the `focus.point.*` values as the `boundary.circle.lat` and `boundary.circle.lon`, and add the required `boundary.circle.radius` value in kilometers. > [/v1/search?api_key={YOUR-KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&___boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50) @@ -238,7 +235,7 @@ Let's say you're looking for the **nearest** YMCA locations, and are willing to | `boundary.circle.lon` | ***151.215281*** | | `boundary.circle.radius` | ***50*** | -Check out the results. They are all less than 50km away from the focus point: +Looking at these results, they are all less than 50 kilometers away from the focus point: > * YMCA, Redfern, New South Wales [distance: 3.836] * YMCA, St Ives (NSW), New South Wales [distance: 14.844] @@ -247,7 +244,7 @@ Check out the results. They are all less than 50km away from the focus point: * Caringbah YMCA, Caringbah, New South Wales [distance: 22.543] * YMCA building, Loftus, New South Wales [distance: 25.756] -## Filtering your Search... +## Filter your search Mapzen search offers two types of options for selecting the dataset you want to search: * `sources` : the originating source of the data From 553f30eb47a12da7d17bdbb5058a3242ab06bba0 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 25 Sep 2015 20:57:26 -0700 Subject: [PATCH 06/13] Minor edits to filtering section --- getting-started/002-search.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 5a5dc44..e6050e1 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -246,12 +246,14 @@ Looking at these results, they are all less than 50 kilometers away from the foc ## Filter your search -Mapzen search offers two types of options for selecting the dataset you want to search: -* `sources` : the originating source of the data -* `layers` : the kind of place you're looking to find +Mapzen Search brings together data from multiple open sources and combines a variety of place types into a single database, allowing you options for selecting the dataset you want to search. -### ...by Data Source -Mapzen Search brings together data from various open sources. All the search examples we've seen so far, return a mix of results from all the different sources. Here's a list of what we import at this time: +With Mapzen Search, you can filter by: +* `sources`: the originating source of the data +* `layers`: the kind of place you want to find + +### Filter by data source +The search examples so far have returned a mix of results from all the data sources available to Mapzen Search. Here are the sources currently being searched: | source | name | short name | |---|---|---| @@ -260,10 +262,9 @@ Mapzen Search brings together data from various open sources. All the search exa | [Quattroshapes](http://quattroshapes.com/) | `quattroshapes` | `qs` | | [GeoNames](http://www.geonames.org/) | `geonames` | `ga` | -We've added a helpful `sources` parameter to the Search API, to allow users to select which of these data sources they want to include in their search. So if you're only intersted in searching **OpenAddressses**, for example, your query would look as follows. +****TO DO: Add a description of each of these.***** -#### Example time -Let's search for **YMCA** again but only within the **OpenAddresses** data source. +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. > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___sources=oa___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&sources=oa) @@ -273,7 +274,7 @@ Let's search for **YMCA** again but only within the **OpenAddresses** data sourc | `text` | YMCA | | `sources` | **oa** | -Since OpenAddresses is, as the name suggests, only address data, here's what you can expect to find: +Because OpenAddresses is, as the name suggests, only address data, here's what you can expect to find: > * 0 Ymca, New Brunswick * 0 Ymca Drive, Cary, NC @@ -286,7 +287,7 @@ Since OpenAddresses is, as the name suggests, only address data, here's what you * 101 Ymca Drive, Kannapolis, NC * 31440 Ymca Road, Washington, OH -If you wanted to combine several data sources together, you would simply set `sources` to a comma separated list of desired source names. Note that the order of the comma separated values does not impact sorting order of the results. They are still sorted based on the linguistic match quality to `text` and distance from `focus`, if one was specified. +If you wanted to combine several data sources together, set `sources` to a comma separated list of desired source names. Note that the order of the comma separated values does not impact sorting order of the results; they are still sorted based on the linguistic match quality to `text` and distance from `focus`, if you specified one. > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___sources=osm,gn___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&sources=oa) @@ -296,8 +297,11 @@ If you wanted to combine several data sources together, you would simply set `so | `text` | YMCA | | `sources` | **osm,gn** | -### ...by Data Type -Mapzen Search brings together a variety of place types into a single database. We refer to these place types as `layers`, and think of them as ranging from *fine* to *coarse*. Our layers are derived from the hierarchy created by the gazetteer [Who's on First](https://github.com/whosonfirst/whosonfirst-placetypes/blob/master/README.md) and can be used to facilitate *coarse* geocoding. Here's a list of the types of places you could find in our results, sorted by granularity: +### Filter by data type +In Mapzen Search, place types are referred to as `layers`, ranging from fine to coarse. The Mapzen Search layers are derived from the hierarchy created by the gazetteer [Who's on First](https://github.com/whosonfirst/whosonfirst-placetypes/blob/master/README.md) and can be used to facilitate coarse geocoding. Here's a list of the types of places you could find in the results, sorted by granularity: + + +****TO DO: Describe fine and coarse geocoding, gazeteer. *** |layer|description| |----|----| From 23d1d6809f9cf5883e219742bffc8528e133ea61 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Fri, 25 Sep 2015 20:57:51 -0700 Subject: [PATCH 07/13] Update heading format for mkdocs --- getting-started/003-reverse.md | 3 +-- getting-started/004-place.md | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index 45ee1f6..8b4226f 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -1,5 +1,4 @@ -Reverse Geocoding -================== +# Reverse geocoding Reverse geocoding is used for finding places near a latitude/longitude pair. Think of it as clicking on a map to see what's there when the map doesn't show it otherwise. For example, picture a map in your mind with building outlines but no labels then clicking on a building and being shown what business is there. That's reverse geocoding. diff --git a/getting-started/004-place.md b/getting-started/004-place.md index 0d63910..2935f6e 100644 --- a/getting-started/004-place.md +++ b/getting-started/004-place.md @@ -1,5 +1,4 @@ -Places -======= +# Search for places Place search is for when you have an ID and the source it came from and now you just need the details. From 58f29ab6483d2c7d35effb22c780c899d1f3da1a Mon Sep 17 00:00:00 2001 From: rmglennon Date: Sun, 27 Sep 2015 13:11:54 -0700 Subject: [PATCH 08/13] Updates, move response section to new topic --- getting-started/002-search.md | 107 +++------------------------------- 1 file changed, 8 insertions(+), 99 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index e6050e1..f34b553 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -22,7 +22,7 @@ Note the parameter values are set as follows: | `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | ***YMCA*** | -If you clicked on the query link above, you probably saw some cool **GeoJSON**, more on that later, with the following set of places in the results: +If you clicked on the query link above, you saw some GeoJSON with the following set of places in the results: > * YMCA, Bargoed Community, United Kingdom * YMCA, Nunspeet, Gelderland @@ -35,6 +35,10 @@ If you clicked on the query link above, you probably saw some cool **GeoJSON**, * YMCA, Jefferson, OH * YMCA, Belleville, IL +Spelling matters, but not capitalization when performing a query with Mapzen Search. You can type `ymca`, `YMCA`, or even `yMcA`. See for yourself by comparing the results of the previous search to the following: + +> [/v1/search?api_key={YOUR-KEY}&___text=yMcA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yMcA) + Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search. ## Narrow your search @@ -300,7 +304,6 @@ If you wanted to combine several data sources together, set `sources` to a comma ### Filter by data type In Mapzen Search, place types are referred to as `layers`, ranging from fine to coarse. The Mapzen Search layers are derived from the hierarchy created by the gazetteer [Who's on First](https://github.com/whosonfirst/whosonfirst-placetypes/blob/master/README.md) and can be used to facilitate coarse geocoding. Here's a list of the types of places you could find in the results, sorted by granularity: - ****TO DO: Describe fine and coarse geocoding, gazeteer. *** |layer|description| @@ -315,102 +318,8 @@ In Mapzen Search, place types are referred to as `layers`, ranging from fine to |`neighbourhood`|...ehm, neighbourhoods| |`coarse`|alias for simultaneously using `country`, `region`, `county`, `locality`, `localadmin`, and `neighbourhood`| -#### Example time - -*** COMING SOON*** - - -# Using Autocomplete & Search Together -For end-user applications, `/autocomplete` is intended to be used alongside `/search` to facilitate real-time feedback for user s - -## Results -Now that you've seen some examples of search, let's examine the results closer. -When requesting search results you will always get back `GeoJSON` results, unless something goes terribly wrong, in which case you'll get a really helpful error. - -> _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: - -```javascript -{ - "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. - -```javascript -{ - "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 section. -[Read more about the response format.](https://github.com/dianashk/pelias-doc/edit/master/getting-started/response.md) - -## Result count - -You may have noticed that there were **10** places in the results for all the previous search examples. -That's the _default_ number of results the API will return, unless otherwise specified. - -#### Example time -Want a **single** result? Just set the `size` parameter to the desired number: - -| parameter | value | -| :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | -| `text` | YMCA | -| `size` | ***1*** | - -> [/v1/search?api_key={YOUR-KEY}&text=stinky beach&___size=1___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&size=1) +****Add example**** -How about *25* results? -> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___size=25___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&size=25) - -| parameter | value | -| :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | -| `text` | YMCA | -| `size` | ***25*** | - - -### **cApiTaliZAtioN** -You may have noticed already that cApiTaliZAtioN isn't a big deal for search. -You can type **ymca** or **YMCA** or even **yMcA**. See for yourself by comparing the results of the previous search to the following: - -> [/v1/search?api_key={YOUR-KEY}&___text=yMcA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yMcA) +## Search with autocomplete +If you are building an end-user application, you can enable `/autocomplete` alongside the `/search` to add real-time feedback to help users find what they are looking for more easily, without requiring them to type the entire search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list. From 58801912ebd32770376eb728f546655c347655c0 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Sun, 27 Sep 2015 13:19:15 -0700 Subject: [PATCH 09/13] Formatting, change to code to json --- getting-started/005-response.md | 72 ++++++++++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/getting-started/005-response.md b/getting-started/005-response.md index 84df6f8..ca6c3f9 100644 --- a/getting-started/005-response.md +++ b/getting-started/005-response.md @@ -1,2 +1,70 @@ -Response Format -================ +# Search results + +When requesting results from Mapzen Search, you will always get back `GeoJSON` results, unless something goes terribly wrong, in which case you'll get an error message. + + Tip: You can go to http://geojson.org/geojson-spec.html to learn more about the GeoJSON data format specification. + +The top-level structure to every response looks like this: + +```json +{ + "geocoding":{...}, + "type":"FeatureCollection", + "features":[...], + "bbox":[...] +} +``` + +##List of `features` returned + +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. + +```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 + ] + } +} +``` + +## 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 five results. + +| parameter | value | +| :--- | :--- | +| `api_key` | [get yours here](https://mapzen.com/developers) | +| `text` | YMCA | +| `size` | ***5*** | + +> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___size=1___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&size=5) + +If you want 25 results, you can build the query where `size` is 25. + +> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___size=25___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&size=25) From 0d800d52a982f50738c66bd256b4717e0122438a Mon Sep 17 00:00:00 2001 From: rmglennon Date: Sun, 27 Sep 2015 14:21:09 -0700 Subject: [PATCH 10/13] Format reverse topic, copy from response --- getting-started/003-reverse.md | 91 ++++++++++++++------------------- getting-started/005-response.md | 6 +-- 2 files changed, 41 insertions(+), 56 deletions(-) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index 8b4226f..e09bd0f 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -1,70 +1,76 @@ # Reverse geocoding -Reverse geocoding is used for finding places near a latitude/longitude pair. Think of it as clicking on a map to see what's there when the map doesn't show it otherwise. For example, picture a map in your mind with building outlines but no labels then clicking on a building and being shown what business is there. That's reverse geocoding. +Reverse geocoding is used for finding places or addresses near a latitude,longitude pair&mdashlike clicking on a map to see what's there when the map doesn't show it otherwise. For example, picture a map showing building outlines but no labels, then clicking on a building and being shown the name of the business. That's reverse geocoding. -With reverse geocoding, you can lookup all sorts of information about a point on a map, including: +With reverse geocoding with Mapzen Search, you can look up all sorts of information about points on a map, including: * addresses -* points of interest (businesses, museums, parks, etc) +* points of interest (businesses, museums, parks, and so on) * neighborhoods * cities * states * postal areas * countries -So [go get an API key](https://mapzen.com/developers) and let's get started. +## Basic reverse geocoding search -## The Basics - -To get started with reverse geocoding, all you need is an API key and a latitude/longitude pair specified with the parameters `point.lat` and `point.lon`, respectively. For example, the Eiffel Tower in Paris, France is at the latitude/longitude pair `48.858268,2.294471`. The reverse geocode query for this would be: +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: >[/v1/reverse?api\_key={YOUR-KEY}&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471) -Notice that the first result is the Eiffel Tower (well, Tour Eiffel). It's as easy as that! 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. + +## Additional parameters for reverse geocoding -## Advanced Usage +Similar to other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results. -Like other entry points, reverse geocoding can use additional parameters to refine results. +Parameter | Type | Required | Default | Example +--- | --- | --- | --- | --- +`api_key` | string | yes | none | [get yours here!](https://mapzen.com/developers) +`point.lat` | floating point number | yes | none | `48.858268` +`point.lon` | floating point number | yes | none | `2.294471` +`size` | integer | no | `10` | `3` +`layers` | comma-delimited string array | no | none (all layers) | `oa,gn` +`sources` | comma-delimited string array | no | none (all sources) | `address,locality` +`boundary.country` | ISO-3166 alpha-2 or alpha-3 | no | none | `FR` ### Size -The most basic parameter for filtering is `size` that is used to limit the number of results returned. In the previous request that returned the Eiffel Tower (or 'Tour Eiffel', to be exact), notice that other results were returned including "Bureau de Gustave Eiffel" (a museum) and "Le Jules Verne" (a restaurant). To limit a reverse geocode to only the first result, just pass the `size` parameter: +A basic parameter for filtering is `size`, which is used to limit the number of results returned. In the previous request that returned the Eiffel Tower (or 'Tour Eiffel', to be exact), notice that other results were returned including "Bureau de Gustave Eiffel" (a museum) and "Le Jules Verne" (a restaurant). To limit a reverse geocode to only the first result, pass the `size` parameter: >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___size=1___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&size=1) -The default value for `size` is `10` and the maximum value is `40`. Specifying a value greater than `40` will override to `40` and return a warning in the response metadata. +The default value for `size` is `10` and the maximum value is `40`. Specifying a value greater than `40` will override to `40` and return a warning in the response metadata. -### Sources +### Filter by data source -By default, reverse geocoding will return results from any source. 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 OSM: +By default, reverse geocoding returns results from any source 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: >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&sources=osm) -For more information on the data each source provides, see [this link](http://source link). +***TO DO: Add correct link**** For more information on the data each source provides, see [this link](http://source link). -### Layers +### Filter by layers -Without specifying further, reverse geocoding doesn't restrict results to a particular type (street, venue, neighbourhood, etc). 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): +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): >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&layers=locality) -For more information on what the different layers mean, see [this link](http://layers link). +***TO DO: Add correct link**** For more information on what the different layers mean, see [this link](http://layers link). -### Country +### Filter by country -Let's say you're reverse geocoding close a country boundary but you are only interested in results from one country and not the other. In that case, you would specify the 2- or 3-character ISO code of the country you're interested in to only get those results back. For example, the latitude/longitude pair `47.270521,9.530846` is right on the boundary of Austria, Liechtenstein, and Switzerland. Without specifying a `boundary.country` parameter value, the first 10 results returned would be from all 3 countries. By specifying `boundary.country=LIE`, all 10 results will be from Liechtenstein. Here's the request in action: +If you are performing a reverse geocode near a country boundary, and are only interested in results from one country and not the other, you can specify a country code. You can set the `boundary.country` parameter value to the alpha-2 or alpha-3 [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1). For example, the latitude,longitude pair `47.270521,9.530846` is on the boundary of Austria, Liechtenstein, and Switzerland. Without specifying a `boundary.country`, the first 10 results returned may come from all three countries. By including `boundary.country=LIE`, all 10 results will be from Liechtenstein. Here's the request in action: >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=47.270521&point.lon=9.530846&___boundary.country=LIE___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=47.270521&point.lon=9.530846&boundary.country=LIE) -Please click here for the full list of ISO 3166-1 alpha-2 and alpha-3 country codes. - -Also note that `UK` is not a valid ISO 3166-1 alpha-2 country code. +Note that `UK` is not a valid ISO 3166-1 alpha-2 country code. -## Confidence Scores +## Confidence scores for the results -Each result returned has an associated confidence score. Currently confidence scores are calculated based on the distance from the result to the supplied `point.lat` and `point.lon`. +Each result returned has an associated confidence score. Currently 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 +Distance from `point.lat`/`point.lon` | Confidence score --- | --- < 1m | 1.0 < 10m | 0.9 @@ -73,42 +79,21 @@ distance from `point.lat`/`point.lon` | Confidence Score < 1km | 0.6 >= 1km | 0.5 -Confidence scoring for reverse geocode results is likely to change to take into account different data sources and layers. - -## Parameters - -This section provides a quick reference for parameters applicable to reverse geocoding requests. - -parameter | type | required | default | example ---- | --- | --- | --- | --- -`api_key` | string | yes | none | [get yours here!](https://mapzen.com/developers) -`point.lat` | floating point number | yes | none | `48.858268` -`point.lon` | floating point number | yes | none | `2.294471` -`size` | integer | no | `10` | `3` -`layers` | comma-delimited string array | no | none (all layers) | `oa,gn` -`sources` | comma-delimited string array | no | none (all sources) | `address,locality` -`boundary.country` | ISO-3166 alpha-2 or alpha-3 | no | none | `FR` - -## Example Requests +## Example requests This section shows how the various parameters can be combined to form complex use cases. -#### All results near the Tower of London - ->[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493) - -#### Only OpenStreetMap results near the Tower of London +* All results near the Tower of London >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493) +* Only OpenStreetMap results near the Tower of London >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&sources=osm) -#### Only street addresses near the Tower of London - +* Only street addresses near the Tower of London >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address) -#### Only OpenStreetMap street addresses near the Tower of London - +* Only OpenStreetMap street addresses near the Tower of London >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm) -#### Only the first OpenStreetMap address near the Tower of London +* Only the first OpenStreetMap address near the Tower of London >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1) diff --git a/getting-started/005-response.md b/getting-started/005-response.md index ca6c3f9..c55c871 100644 --- a/getting-started/005-response.md +++ b/getting-started/005-response.md @@ -55,15 +55,15 @@ Each item in this list will contain all the information needed to identify it in ## 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 five results. +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. | parameter | value | | :--- | :--- | | `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | -| `size` | ***5*** | +| `size` | ***1*** | -> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___size=1___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&size=5) +> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___size=1___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&size=1) If you want 25 results, you can build the query where `size` is 25. From b16c5850524954989aa0baa23dcebb96ca769b48 Mon Sep 17 00:00:00 2001 From: rmglennon Date: Sun, 27 Sep 2015 15:00:43 -0700 Subject: [PATCH 11/13] Reorg headings in place, add TO DO comments --- getting-started/003-reverse.md | 4 +--- getting-started/004-place.md | 35 +++++++++++++++++----------------- 2 files changed, 18 insertions(+), 21 deletions(-) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index e09bd0f..a119940 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -12,15 +12,13 @@ With reverse geocoding with Mapzen Search, you can look up all sorts of informat * postal areas * countries -## Basic reverse geocoding search - 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: >[/v1/reverse?api\_key={YOUR-KEY}&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&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. -## Additional parameters for reverse geocoding +reverse geocoding Similar to other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results. diff --git a/getting-started/004-place.md b/getting-started/004-place.md index 2935f6e..c06fe81 100644 --- a/getting-started/004-place.md +++ b/getting-started/004-place.md @@ -1,39 +1,38 @@ -# Search for places +# Search an ID to get details on a place -Place search is for when you have an ID and the source it came from and now you just need the details. +When you know an identification number and the source it came from, you can use Mapzen Search to get details on the location. -Once you have [an API key](https://mapzen.com/developers), continue on. +To get started with a place search, you need a [free, developer API key](https://mapzen.com/developers) and these three pieces of information: -## The Basics +* source - the data source, such as OpenStreetMap +* layer - the type of place, such as a venue, address, country. +* id - the identification number of the item -A place search requires 3 pieces of information: +If you have all of those, join them together with semicolon and pass them in with the `ids` parameter. -1. source -2. layer -3. id +For example, this `/place` query looks up the Eiffel Tower in OSM: -Once you have all 3 of those, simply join them together with semicolon and pass in on the ids parameter. +http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:venue:5013364 -For example, this /place query looks up the Eiffel Tower in OSM: +***From Rhonda -- looks like this returns a radio station in Michigan? Also need to redo the query to include production server and the reader's API key*** -http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:venue:5013364 +*** From Rhonda -- what are some examples of when you would use a /place search? When would you have this info and need to get the details? What would you do with it.*** -## Advanced Usage +## Search for multiple places in a query -To request more than 1 /place lookup in one request, simply join multiple values together delimited by 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 OSM and `30 West 26th St, New York, NY` in OpenAddresses: http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:country:5013364,oa:address:65cf57e4eb5548eca9bb548fb1461633 The results are returned in the order requested. -## Caveats +***From Rhonda -- is there another example where you might do multiple requests at the same time...in other words, more related locations?*** -If you enter a `source:layer:id` combination that cannot be found then the `features` array in the response will continue a different number of elements than the number of requests. This will be most noticeable in multi-id requests since your request may have 3 ids requested but only 2 results returned. The reason for this is that the `features` section of the response is GeoJSON-compliant and there is currently no way to convey an exception condition (not even an empty JSON element, `{}`). For this reason, if your application is dependent upon the results mapping directly to the individual input requests in order, then you'll have to do your own bookkeeping to handle with exception conditions. +Keep in mind that if you enter a `source:layer:id` combination that cannot be found, then the `features` array in the response contains a different number of elements than the number of requests. This will be most noticeable in requests with multiple IDs, as your request may have three IDs requested but only two results returned. The reason for this is that the `features` section of the response is GeoJSON-compliant and there is currently no way to convey an exception condition (not even an empty JSON element, `{}`). For this reason, if your application is dependent upon the results mapping directly to the individual input requests in order, then you'll have to do your own bookkeeping to handle with exception conditions. -## Valid combinations +## Valid combinations of place searches -Some combinations of `sources` and `layers` are valid while others aren't. Please use the following table for reference: +Some combinations of `sources` and `layers` are valid while others are not. This table shows valid combinations. source | layers --- | --- From 85ee2a05605ce21fb53307cd6b2c5aa7db1972df Mon Sep 17 00:00:00 2001 From: rmglennon Date: Sun, 27 Sep 2015 15:12:10 -0700 Subject: [PATCH 12/13] tweaks to first paragraph --- getting-started/002-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index f34b553..ed101f5 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -1,6 +1,6 @@ # Mapzen Search: Finding places -Geospatial search, frequently referred to as geocoding, is the process of matching an address to its corresponding geographic coordinates. There's nothing inherent in the words we use to describe an address that conveys its location at some coordinates on earth, i.e. *[lat,lon]*. Making the leap from text to coordinates is an intricate and challenging process. Lucky for you, we've done all the hard work and made it accessible though a free web service. +Geospatial search, frequently referred to as geocoding, is the process of matching an address to its corresponding geographic coordinates. There's nothing inherent in the words we use to describe an address that conveys its position at some coordinates on earth, such as a 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. ## Build a query The Mapzen Search request takes the form of `https://search.mapzen.com/v1/search?api_key={your-api-key}`, where the JSON inputs inside the `{}` include search parameters such as the text to find and filtering options. Note that you must append your own Mapzen Search API key to the URL, following &api_key= at the end. From cf96b3c84cf9e268118fcedc5f98d677208f935c Mon Sep 17 00:00:00 2001 From: rmglennon Date: Mon, 28 Sep 2015 09:47:21 -0700 Subject: [PATCH 13/13] Address feedback in comments --- getting-started/002-search.md | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index ed101f5..1d7ea11 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -1,15 +1,25 @@ # Mapzen Search: Finding places -Geospatial search, frequently referred to as geocoding, is the process of matching an address to its corresponding geographic coordinates. There's nothing inherent in the words we use to describe an address that conveys its position at some coordinates on earth, such as a 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. +Geospatial search, commonly referred to as geocoding, is the process of matching an address to its corresponding geographic coordinates. -## Build a query -The Mapzen Search request takes the form of `https://search.mapzen.com/v1/search?api_key={your-api-key}`, where the JSON inputs inside the `{}` include search parameters such as the text to find and filtering options. Note that you must append your own Mapzen Search API key to the URL, following &api_key= at the end. +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. + +All Mapzen Search requests share the same format: + + ``` + https://search.mapzen.com/v1/search?text=London&api_key=search-xxxxxx + \___/ \_______________/\__/\_____/\__________/\___________________/ + | | / | | | + scheme domain version path query authentication token +``` ## Search the world ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_all.png) -In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To accomplish this, build a query where the `text` is set to the item you want to find. +In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To accomplish this, build a query where the `text` parameter is set to the item you want to find. For example, if you want to find a [YMCA](https://en.wikipedia.org/wiki/YMCA) facility, here's what you'd need to append to the base URL of the service, `search.mapzen.com`. @@ -22,7 +32,11 @@ Note the parameter values are set as follows: | `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | ***YMCA*** | -If you clicked on the query link above, you saw some GeoJSON with the following set of places in the results: +Clicking the link above will open a file containing the best matching results for the text `YMCA`. You will notice the data is in a computer-friendly format called [GeoJSON](http://geojson.org/), which may be hard for humans to read in some browsers. + +If you are having trouble seeing the JSON in your browser, you can install a browser extension for [Chrome](https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en) or [Firefox](https://addons.mozilla.org/en-us/firefox/addon/jsonview/) that will make it easier for you to read. + +In the example above, you will find the name of each matched locations in a property named `'label'`. The top 10 labels returned were: > * YMCA, Bargoed Community, United Kingdom * YMCA, Nunspeet, Gelderland @@ -43,7 +57,7 @@ Note that the results are spread out throughout the world because you have not g ## Narrow your search -If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. Mapzen Search currently supports three types: country, rectangle, and country. +If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. Mapzen Search currently supports three types: country, rectangle, and circle. ### Search within a particular country @@ -74,7 +88,7 @@ Note that all the results reside within Great Britain: * YMCA, Lenton Abbey, Nottinghamshire * YMCA, Old Clee, Lincolnshire -If you attempt the same search request with different country codes, the results change to reflect YMCA locations within the country. +If you attempt the same search request with different country codes, the results change to reflect YMCA locations within this region. > [/v1/search?api_key={YOUR-KEY}&text=YMCA&___boundary.country=USA___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA&boundary.country=USA) @@ -95,7 +109,7 @@ Results in the United States: ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_rect.png) -To specify the boundary using a rectangle, you need latitude, longitude coordinates for two corners of the bounding box (the mininum and the maximum latitude, longitude). +To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the mininum and the maximum latitude, longitude). For example, to find a YMCA within the state of Texas, you can set the `boundary.rect.*` parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5 @@ -157,13 +171,13 @@ If you're going to attempt using multiple boundary types in a single search requ ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/overlapping_boundaries.gif) ## Prioritize results by proximity -Many usecases call for the ability to promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. If that's your conundrum, here's what to do. +Many use cases call for the ability to promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. Mapzen Search allows you to prioritize results within geographic boundaries, including around a point, within a country, or within a region. ### Prioritize around a point ![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/focus_point.png) -Search will focus on a given point anywhere on earth, and results within 100 kilometers will be prioritized higher, thereby surfacing highest in the list. Once all the nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization. +By specifying a `focus.point`, nearby places will be scored higher depending on how close they are to the `focus.point` so that places with higher scores will appear higher in the results list. The effect of this scoring boost diminishes to zero after 100 kilometers away from the `focus.point`. After all the nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization. To find YMCA again, but this time near the a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia.