diff --git a/getting-started/002-search.md b/getting-started/002-search.md index 26dcf87..5b07933 100644 --- a/getting-started/002-search.md +++ b/getting-started/002-search.md @@ -10,18 +10,18 @@ Geospacial search, frequently reffered to as **geocoding** is the process of mat 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. #### Find a venue -Let's search for **YMCA**. You would set the following parameters in your query url: +Let's search for **YMCA**. 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) + +Note the parameter values are set as follows: | parameter | value | | :--- | :--- | | `api_key` | [get yours here](https://mapzen.com/developers) | -| `text` | ***30 West 26th Street, New York, NY*** | - -> [/v1/search?api_key={YOUR-KEY}&___text=YMCA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA) - -_...go ahead, and click that link, we'll wait_ +| `text` | YMCA | -You probably saw some cool **GeoJSON**, more on that later, with the following places in the results: +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: > * YMCA, Bargoed Community, United Kingdom * YMCA, Nunspeet, Gelderland @@ -34,137 +34,68 @@ You probably saw some cool **GeoJSON**, more on that later, with the following p * YMCA, Jefferson, OH * YMCA, Belleville, IL -#### Find a venue -As mentioned above, query `text` can be a partial or full name of a place we're looking for. So here's an example of another way of finding that address we just searched for: - -| parameter | value | -| :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | -| `text` | ***Samsung Accelerator*** | - -> [/v1/search?api_key={YOUR-KEY}&___text=Samsung Accelerator___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=Samsung Accelerator) - -#### Or maybe a landmark, like *Yankee Stadium* - -| parameter | value | -| :--- | :--- | -| `text` | ***yankee stadium*** | -| `api_key` | [get yours here](https://mapzen.com/developers) | - - -> [/v1/search?api_key={YOUR-KEY}&___text=yankee stadium___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yankee stadium) - - -### **cApiTaliZAtioN** -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 by comparing the results of the previous search to the following: - -| parameter | value | -| :--- | :--- | -| `text` | ***YANKEE STADIUM*** | -| `api_key` | [get yours here](https://mapzen.com/developers) | - - -> [/v1/search?api_key={YOUR-KEY}&___text=YANKEE STADIUM___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YANKEE STADIUM) +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. -## 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: +## Narrowing your Search -```javascript -{ - "geocoding":{...}, - "type":"FeatureCollection", - "features":[...], - "bbox":[...] -} -``` +All this time you've been searching the entire world... -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. +![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_all.png) -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. +### What if you need results from only a... -```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 - ] - } -} -``` +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**. -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 +#### ...specific country -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. +![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_country.png) -#### Want a *single* result? +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). -Just set the `size` parameter to the desired number: +#### Find **YMCA** only within **Great Britain** +We'll need to know that the **alpha-3** code for **Great Britain** is ***GBR*** and set the parameters like this: | parameter | value | | :--- | :--- | -| `text` | stinky beach | -| `size` | ***1*** | | `api_key` | [get yours here](https://mapzen.com/developers) | +| `text` | YMCA | +| `boundary.country` | ***GBR*** | -> [/v1/search?api_key={YOUR-KEY}&text=stinky beach&___size=1___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach&size=1) +> [/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) +Note that all the results reside within Great Britain: -#### How about *25* results? +> * YMCA, Bargoed Community, United Kingdom +* YMCA, Orpington, Greater London +* YMCA, Erdington, West Midlands +* YMCA, Malvern CP, United Kingdom +* YMCA, Ancoats, Greater Manchester +* YMCA, Carmarthen Community, United Kingdom +* YMCA, Halebank, Cheshire +* YMCA, Brightlingsea CP, United Kingdom +* YMCA, Lenton Abbey, Nottinghamshire +* YMCA, Old Clee, Lincolnshire -| parameter | value | -| :--- | :--- | -| `text` | stinky beach | -| `size` | ***25*** | -| `api_key` | [get yours here](https://mapzen.com/developers) | - -> [/v1/search?api_key={YOUR-KEY}&text=stinky beach&___size=25___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach&size=25) +Now you can try the same search request with different country codes and see the results change. - -## Narrowing your Search +> [/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) -All this time you've been searching the entire world... +Results in the United States: -![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_all.png) +> * YMCA, Belleville, IL +* YMCA, Forest City, IA +* YMCA, Fargo, ND +* YMCA, Frisco, TX +* YMCA, Jefferson, OH +* YMCA, Belleville, IL +* YMCA, Chapel Hill, NC +* YMCA, West Lampeter, PA +* YMCA, Bremerton, WA +* YMCA, Westerly, RI -### What if you need results from only a... -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**. #### ...rectangular region @@ -224,35 +155,6 @@ This time, we'll use the `boundary.circle.*` parameter grouping to get the job d > [/v1/search?api_key={YOUR-KEY}&text=starbucks&___boundary.circle.lat=40.414149&boundary.circle.lon=-3.703755&boundary.circle.radius=3___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=starbucks&boundary.circle.lat=40.414149&boundary.circle.lon=-3.703755&boundary.circle.radius=3) -#### ...specific 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). - -##### Try searching for *San Francisco* in *Columbia* - -| parameter | value | -| :--- | :--- | -| `text` | san francisco | -| `boundary.country` | ***COL*** | -| `api_key` | [get yours here](https://mapzen.com/developers) | - -> [/v1/search?api_key={YOUR-KEY}&text=san francisco&___boundary.country=COL___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=san francisco&boundary.country=COL) - -Note that all the results have `country` set to **Columbia**. - -##### Now try searching for *San Francisco* in the *USA* - -| parameter | value | -| :--- | :--- | -| `text` | san francisco | -| `boundary.country` | ***US*** | -| `api_key` | [get yours here](https://mapzen.com/developers) | - -> [/v1/search?api_key={YOUR-KEY}&text=san francisco&___boundary.country=US___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=san francisco&boundary.country=US) - -You can see all the results are now from within the US, and the top place is **San Francisco, CA**. Awesome, right?! #### Boundary issues @@ -287,6 +189,100 @@ Search will focus on a given point anywhere on earth, and results within **~100k - focus viewport api example (e.g. union square) - focus point api example (NY union square) + + + + + +## 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. + +#### Want a *single* result? + +Just set the `size` parameter to the desired number: + +| parameter | value | +| :--- | :--- | +| `text` | stinky beach | +| `size` | ***1*** | +| `api_key` | [get yours here](https://mapzen.com/developers) | + +> [/v1/search?api_key={YOUR-KEY}&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? + +| parameter | value | +| :--- | :--- | +| `text` | stinky beach | +| `size` | ***25*** | +| `api_key` | [get yours here](https://mapzen.com/developers) | + +> [/v1/search?api_key={YOUR-KEY}&text=stinky beach&___size=25___](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach&size=25) + + + # TBD ### Combining Focused Results with Boundaries @@ -336,3 +332,19 @@ There are many cases where you're after not a point, but a general area, whether # Using Autocomplete & Search Together For end-user applications, `/autocomplete` is intended to be used alongside `/search` to facilitate real-time feedback for user s + + + +### **cApiTaliZAtioN** +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 by comparing the results of the previous search to the following: + +| parameter | value | +| :--- | :--- | +| `text` | ***YANKEE STADIUM*** | +| `api_key` | [get yours here](https://mapzen.com/developers) | + + +> [/v1/search?api_key={YOUR-KEY}&___text=YANKEE STADIUM___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YANKEE STADIUM) + +