From 9fcbc0ed4def96cf1edea529651c9a986e00376c Mon Sep 17 00:00:00 2001 From: Diana Shkolnikov Date: Wed, 16 Sep 2015 18:01:08 -0400 Subject: [PATCH 1/7] Update 002-search.md --- getting-started/002-search.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 6582233..46c05db 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -10,7 +10,17 @@ Geocoding is the process of matching an address to its corresponding geographic ## Looking For Places - Getting Started {search text, global, no options} -`https://search.mapzen.com/v1/search?text={123 Fake Street, Springfield}&api_key={YOUR_API_KEY}` +So, let's say you wanted to find **Stinky Beach**, you'd just do this. + +> +> [/v1/search?___text=stinky beach___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach) +> + +_Go ahead, and click that link... we'll wait._ + +Now you know exactly where on the earth sufrace **Strinky Beach** is located: `[ 139.86114, -37.33192 ]` +You've also probably learned from the results of that request that this questionable beach is located in **Australia**, more specifically in the **South Australia** region. You also have yourself a handy text label to use when talking to other humans about this place: **Stinky Beach, Nora Creina, South Australia** + - Response is GeoJSON FeatureCollection - The FeatureCollection is an ordered array, ranked in order of likleyhood From 2e6acb09d7829aa28f5e938f26b51b4baa66842d Mon Sep 17 00:00:00 2001 From: Diana Shkolnikov Date: Wed, 16 Sep 2015 18:18:24 -0400 Subject: [PATCH 2/7] Update 002-search.md --- getting-started/002-search.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 46c05db..0b80871 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -1,25 +1,34 @@ -Search +`SEARCH` ======= -Turning place names we can say into geographic coordinates computers can use +Turning human recognizable place names into computer recognizable geographic coordinates _____________________________________________________________________________________ -Geocoding is the process of matching an address to its corresponding geographic coordinates. There's nothing inherent in the words "10 Downing Street, London, United Kingdom" that inherently conveys its location at the coordinates 51.503396, -0.12764. Instead this process [...]. +Geocoding is the process of matching an address to its corresponding geographic coordinates. There's nothing inherent in the words "10 Downing Street, London, United Kingdom" that conveys its location at the coordinates `[ 51.503396, -0.12764 ]`. Instead this process [...]. + +:school: :barber: :bank: :us: :house_with_garden: :hospital: ......... :computer: -# Using Search ## Looking For Places - Getting Started -{search text, global, no options} +_{search text, global, no options}_ + +##### The most basic scenario -So, let's say you wanted to find **Stinky Beach**, you'd just do this. +Let's say you wanted to find **Stinky Beach**, you would simply query the search API as follows: > > [/v1/search?___text=stinky beach___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach) > -_Go ahead, and click that link... we'll wait._ +_...go ahead, and click that link, we'll wait_ + +Now that you're back, you probably saw a `GeoJSON` formatted response on the other side of that click. +You'll always get back `GeoJSON` results, unless something goes terribly wrong, in which case you'll get a really helpful error. + +Now you know exactly where on the earth's sufrace **Strinky Beach** is located: `[ 139.86114, -37.33192 ]` +You've also probably learned from the results of that request that this intriguing beach is located in **Australia**, more specifically in the **South Australia** region. You also have yourself a handy text label to use when talking to other humans about this place: **Stinky Beach, Nora Creina, South Australia** + + -Now you know exactly where on the earth sufrace **Strinky Beach** is located: `[ 139.86114, -37.33192 ]` -You've also probably learned from the results of that request that this questionable beach is located in **Australia**, more specifically in the **South Australia** region. You also have yourself a handy text label to use when talking to other humans about this place: **Stinky Beach, Nora Creina, South Australia** - Response is GeoJSON FeatureCollection From b14c8fca058f0bbf6b669a9ea919918b6b73b3a7 Mon Sep 17 00:00:00 2001 From: Diana Shkolnikov Date: Wed, 16 Sep 2015 18:29:25 -0400 Subject: [PATCH 3/7] Update 002-search.md --- getting-started/002-search.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 0b80871..9385e71 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -11,34 +11,38 @@ Geocoding is the process of matching an address to its corresponding geographic ## Looking For Places - Getting Started _{search text, global, no options}_ -##### The most basic scenario +#### The most basic scenario Let's say you wanted to find **Stinky Beach**, you would simply query the search API as follows: -> > [/v1/search?___text=stinky beach___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach) -> _...go ahead, and click that link, we'll wait_ +#### Results + Now that you're back, you probably saw a `GeoJSON` formatted response on the other side of that click. You'll always get back `GeoJSON` results, unless something goes terribly wrong, in which case you'll get a really helpful error. -Now you know exactly where on the earth's sufrace **Strinky Beach** is located: `[ 139.86114, -37.33192 ]` +Now you know exactly where on the earth's sufrace **Stinky Beach** is located: `[ 139.86114, -37.33192 ]` You've also probably learned from the results of that request that this intriguing beach is located in **Australia**, more specifically in the **South Australia** region. You also have yourself a handy text label to use when talking to other humans about this place: **Stinky Beach, Nora Creina, South Australia** +[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 our **Stinky Beach** search. +That's the _default_ number of results the API will return, unless otherwise specified. +**Want a single result?** -- Response is GeoJSON FeatureCollection - - The FeatureCollection is an ordered array, ranked in order of likleyhood - - Use directly in your application or test at GeoJSON.io - -## Sizing Your Results - - Example: size=1 for batch geocoding - - Example: size=40 to store lots of results +> [/v1/search?text=stinky beach&___size=1___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach&size=1) +**How about 25 results?** + +> [/v1/search?text=stinky beach&___size=25___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach&size=25) + + ## Looking in a Particular Place (Using Boundaries) [Means to limit the scope of where you're looking, and to look only within a particular area. 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.] From 0fd5589036598b3aa744d8575a6154fd57149b6f Mon Sep 17 00:00:00 2001 From: Diana Shkolnikov Date: Wed, 16 Sep 2015 18:30:51 -0400 Subject: [PATCH 4/7] Update 002-search.md --- getting-started/002-search.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 9385e71..cca59cd 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -27,7 +27,7 @@ You'll always get back `GeoJSON` results, unless something goes terribly wrong, Now you know exactly where on the earth's sufrace **Stinky Beach** is located: `[ 139.86114, -37.33192 ]` You've also probably learned from the results of that request that this intriguing beach is located in **Australia**, more specifically in the **South Australia** region. You also have yourself a handy text label to use when talking to other humans about this place: **Stinky Beach, Nora Creina, South Australia** -[Read more about the response format](https://github.com/dianashk/pelias-doc/edit/master/getting-started/response.md +[Read more about the response format](https://github.com/dianashk/pelias-doc/edit/master/getting-started/response.md) #### Result count @@ -43,6 +43,15 @@ That's the _default_ number of results the API will return, unless otherwise spe > [/v1/search?text=stinky beach&___size=25___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach&size=25) + + + + + + + + + ## Looking in a Particular Place (Using Boundaries) [Means to limit the scope of where you're looking, and to look only within a particular area. 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.] From 3bb9351dd2e5b95a4e63b9e6decd01be203d7c5b Mon Sep 17 00:00:00 2001 From: Diana Shkolnikov Date: Wed, 16 Sep 2015 19:38:42 -0400 Subject: [PATCH 5/7] Update 002-search.md --- getting-started/002-search.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index cca59cd..68f511f 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -19,6 +19,20 @@ Let's say you wanted to find **Stinky Beach**, you would simply query the search _...go ahead, and click that link, we'll wait_ +Maybe you'd like to find an **address**, like this: + +> [/v1/search?___text=30 west 26th street___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=30 west 26th street) + +Or even a landmark, like **Yankee Stadium**: + +> [/v1/search?___text=yankee stadium___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yankee stadium) + +_You may have noticed already that cApiTaliZAtioN isn't a big deal for search._ +_You can type `yankee stadium` or `Yankee Stadium` or even `YANKEE STADIUM` if you're really excited about finding it._ +_See for yourself:_ + +> [/v1/search?___text=YANKEE STADIUM___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YANKEE STADIUM) + #### Results Now that you're back, you probably saw a `GeoJSON` formatted response on the other side of that click. From 55fcbadb185b6d1a8ec4d7b5b4f08cf0b3a55d2e Mon Sep 17 00:00:00 2001 From: Diana Shkolnikov Date: Wed, 16 Sep 2015 20:01:59 -0400 Subject: [PATCH 6/7] Update 002-search.md --- getting-started/002-search.md | 71 ++++++++++++++++++++++++++++++----- 1 file changed, 62 insertions(+), 9 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 68f511f..d03167a 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -19,7 +19,7 @@ Let's say you wanted to find **Stinky Beach**, you would simply query the search _...go ahead, and click that link, we'll wait_ -Maybe you'd like to find an **address**, like this: +Maybe you'd like to find an address, like this: > [/v1/search?___text=30 west 26th street___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=30 west 26th street) @@ -27,21 +27,74 @@ Or even a landmark, like **Yankee Stadium**: > [/v1/search?___text=yankee stadium___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yankee stadium) -_You may have noticed already that cApiTaliZAtioN isn't a big deal for search._ -_You can type `yankee stadium` or `Yankee Stadium` or even `YANKEE STADIUM` if you're really excited about finding it._ -_See for yourself:_ +You may have noticed already that cApiTaliZAtioN isn't a big deal for search. +You can type **yankee stadium** or **Yankee Stadium** or even **YANKEE STADIUM** if you're really excited about finding it. +See for yourself: > [/v1/search?___text=YANKEE STADIUM___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YANKEE STADIUM) #### Results -Now that you're back, you probably saw a `GeoJSON` formatted response on the other side of that click. +Now that you've seen some examples of search, let's examine the results closer. +When searching for **30 West 26th Street** you got back a `GeoJSON` formatted response. You'll always get back `GeoJSON` results, unless something goes terribly wrong, in which case you'll get a really helpful error. -Now you know exactly where on the earth's sufrace **Stinky Beach** is located: `[ 139.86114, -37.33192 ]` -You've also probably learned from the results of that request that this intriguing beach is located in **Australia**, more specifically in the **South Australia** region. You also have yourself a handy text label to use when talking to other humans about this place: **Stinky Beach, Nora Creina, South Australia** - -[Read more about the response format](https://github.com/dianashk/pelias-doc/edit/master/getting-started/response.md) +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: + +``` +{ + "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. + +``` +{ + "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 document. +[Read more about the response format.](https://github.com/dianashk/pelias-doc/edit/master/getting-started/response.md) #### Result count From b776441043b4df643d490ecb9b0c1f0b61f060bf Mon Sep 17 00:00:00 2001 From: Diana Shkolnikov Date: Thu, 17 Sep 2015 09:07:25 -0400 Subject: [PATCH 7/7] Update 002-search.md --- getting-started/002-search.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/getting-started/002-search.md b/getting-started/002-search.md index d03167a..debeed8 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -15,32 +15,31 @@ _{search text, global, no options}_ Let's say you wanted to find **Stinky Beach**, you would simply query the search API as follows: -> [/v1/search?___text=stinky beach___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach) +> [/v1/search?api_key={YOUR-KEY}&___text=stinky beach___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach) _...go ahead, and click that link, we'll wait_ Maybe you'd like to find an address, like this: -> [/v1/search?___text=30 west 26th street___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=30 west 26th street) +> [/v1/search?api_key={YOUR-KEY}&___text=30 west 26th street___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=30 west 26th street) Or even a landmark, like **Yankee Stadium**: -> [/v1/search?___text=yankee stadium___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yankee stadium) +> [/v1/search?api_key={YOUR-KEY}&___text=yankee stadium___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yankee stadium) You may have noticed already that cApiTaliZAtioN isn't a big deal for search. You can type **yankee stadium** or **Yankee Stadium** or even **YANKEE STADIUM** if you're really excited about finding it. See for yourself: -> [/v1/search?___text=YANKEE STADIUM___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YANKEE STADIUM) +> [/v1/search?api_key={YOUR-KEY}&___text=YANKEE STADIUM___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YANKEE STADIUM) #### Results Now that you've seen some examples of search, let's examine the results closer. -When searching for **30 West 26th Street** you got back a `GeoJSON` formatted response. -You'll always get back `GeoJSON` results, unless something goes terribly wrong, in which case you'll get a really helpful error. +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 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: