You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

109 lines
4.1 KiB

`SEARCH`
=======
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 conveys its location at the coordinates `[ 51.503396, -0.12764 ]`. Instead this process [...].
:school: :barber: :bank: :us: :house_with_garden: :hospital: ......... :computer:
## Looking For Places - Getting Started
_{search text, global, no options}_
#### 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 **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?**
> [/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.]
Boundaries are mutually exclusive
- Country (country code)
- Rectangle (bbox)
- Circle (point, radius)
All results outside of the area will be discarded.
## Focusing Results Near Your End-Users
Mapzen Search can let your users search globally, while providing them with search results for the closest matching places first. All you have to do is provide Mapzen Search with some location context about where the search should be focused.
In many cases, you may have the location of the user's device (either through Device Location APIs or the HTML5 Location API) or the area of a map that the user is looking at (the map viewport).
- focus viewport api example (e.g. union square)
- focus point api example (NY union square)
### Combining Focused Results with Boundaries
- Focus within country example
- Focus within large bounding box example (e.g. maximum distance a user is willing to travel)
## Selecting Datasets
Mapzen search offers two types of options for selecting the dataset you want back:
1. the originating source of the data (`sources`)
2. the kind of place you're looking to geocode against (`layers`)
### Selecting `Sources`
{list sources, not different licenses}
{combine source listing, e.g. open addresses + Geonames}
### Selecting Layers
{layer options}
### Coarse Geocoding (Neighborhoods, Cities, States, Countries)
There are many cases where you're after not a point, but a general area, whether it's the name of a town, a neighborhood, a county, or a country.
- Coarse general
- Select cities
- Select localities in a country (with boundary.country)
# Using Autocomplete & Search Together