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 [...].
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.
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**.
Below is the region that will be searched. Museums located outside of this highlighted region will **NOT** be included in the results. The museums returned will be sorted based on how well they matched the `text` parameter, in this case **museum**.
**Or you wanted to find an address, such as 28 Main Ave., in New York City?**
> [/v1/search?api_key={YOUR-KEY}&text=28 Main Ave&___boundary.rect.min_lat=51.286839&boundary.rect.min_lon=-74.258904&boundary.rect.max_lat=40.477421&boundary.rect.max_lon=-73.700378___](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=28 Main Ave&boundary.rect.min_lat=51.286839&boundary.rect.min_lon=-74.258904&boundary.rect.max_lat=40.477421&boundary.rect.max_lon=-73.700378)
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}
|`venue`|Points of interest, businesses, things with walls|
|`address`|Places with a street address|
|`country`|Places that issue passports, nations, nation-states|
|`region`|States and provinces|
|`county`|Official governmental area; usually bigger than a locality, almost always smaller than a region|
|`locality`|Towns, hamlets, cities, etc.|
|`localadmin`| |
|`neighbourhood`||
|`coarse`|Alias for simultaneously using `country`, `region`, `county`, `locality`, `localadmin`, and `neighbourhood`||
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.
