pelias
/
documentation
mirror of https://github.com/pelias/documentation.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

Merge remote-tracking branch 'diana/master' into docmerge. There will be conflicts.

pull/4/head
Riordan 9 years ago
parent
8d388ba55c df254e1c85
commit
9c9e947c7c
12 changed files with 623 additions and 55 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 443
      getting-started/002-search.md
  2. 113
      getting-started/003-reverse.md
  3. 42
      getting-started/004-place.md
  4. BIN
      getting-started/boundary_london.png
  5. BIN
      getting-started/focus_point.png
  6. BIN
      getting-started/overlapping_boundaries.gif
  7. BIN
      getting-started/world_all.png
  8. BIN
      getting-started/world_circle.png
  9. BIN
      getting-started/world_country.png
  10. BIN
      getting-started/world_rect.png
  11. 63
      tools/locmux.js
  12. 17
      tools/package.json

443
getting-started/002-search.md
Unescape View File

@ -1,90 +1,423 @@
Search
`SEARCH`, or Looking for Places
=======
Turning place names we can say into geographic coordinates computers can use
_____________________________________________________________________________________
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 [...].
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.
:school: :barber: :bank: :us: :house_with_garden: :hospital: ......... :computer:
# Using Search
## Looking For Places - Getting Started
{search text, global, no options}
## Search the World
`https://search.mapzen.com/v1/search?text={123 Fake Street, Springfield}&api_key={YOUR_API_KEY}`
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_all.png)
- 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
- Show + explain a response block
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.
## Sizing Your Results
- Example: size=1 for batch geocoding
- Example: size=40 to store lots of results
#### Example time
## 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.]
Let's search for **YMCA**. Here's what you'd need to append to the base URL of the service, **search.mapzen.com**.
Boundaries are mutually exclusive
> [/v1/search?api_key={YOUR-KEY}&___text=YMCA___](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YMCA)
- Country (country code)
- Rectangle (bbox)
- Circle (point, radius)
Note the parameter values are set as follows:
All results outside of the area will be discarded.
| parameter | value |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | ***YMCA*** |
## 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.
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:
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).
> * YMCA, Bargoed Community, United Kingdom
* YMCA, Nunspeet, Gelderland
* YMCA, Belleville, IL
* YMCA, Forest City, IA
* YMCA, Fargo, ND
* YMCA, Taipei, Taipei City
* YMCA, Orpington, Greater London
* YMCA, Frisco, TX
* YMCA, Jefferson, OH
* YMCA, Belleville, IL
- focus viewport api example (e.g. union square)
- focus point api example (NY union square)
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.
## Narrowing your Search...
### Combining Focused Results with Boundaries
- Focus within country example
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**.
- Focus within large bounding box example (e.g. maximum distance a user is willing to travel)
### ...to a specific country
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/world_country.png)
## Selecting Datasets
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).
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`)
#### 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:
### Selecting `Sources`
{list sources, not different licenses}
{combine source listing, e.g. open addresses + Geonames}
> [/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)
### Selecting Layers
| parameter | value |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA |
| `boundary.country` | ***GBR*** |
Note that all the results reside within Great Britain:
|Layer Name|Represents|
|----|----|
|`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`||
> * 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
Now you can try the same search request with different country codes and see 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)
Results in the United States:
> * 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
### ...to 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/)*
> [/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 |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `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*** |
> * YMCA, Austin, TX
* YMCA, Frisco, TX
* Y.M.C.A, Fort Worth, TX
* YMCA, Rockwall, TX
* YMCA, Missouri City, TX
* YMCA, Northshore, TX
* YMCA, Austin, TX
* YMCA, Tulsa, OK
* YMCA, Los Alamos, NM
* YMCA, Tulsa, OK
#### ...to 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**,
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)
| parameter | value |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA |
| `boundary.circle.lat` | ***43.818156*** |
| `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:
> * YMCA, Toronto, Ontario
* YMCA, Markham, Ontario
* YMCA, Toronto, Ontario
* Metro Central YMCA, Toronto, Ontario
* Pinnacle Jr YMCA, Toronto, Ontario
* Cooper Koo Family Cherry Street YMCA Centre, Toronto, Ontario
### We respect your 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:
![](https://github.com/dianashk/pelias-doc/blob/master/getting-started/overlapping_boundaries.gif)
## 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
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.
![](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.
#### Example time
Let's find **YMCA** again, but this time near **Sydney Opera House, Australia**
### 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.
> [/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)
| parameter | value |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA |
| `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.
- Coarse general
- Select cities
- Select localities in a country (with boundary.country)
> * YMCA, Redfern, New South Wales [distance: 3.836]
* YMCA, St Ives (NSW), New South Wales [distance: 14.844]
* YMCA, Epping (NSW), New South Wales [distance: 16.583]
* YMCA, Revesby, New South Wales [distance: 21.335]
* YMCA, Kochâang, South Gyeongsang [distance: 8071.436]
* YMCA, Center, IN [distance: 14882.675]
* YMCA, Lake Villa, IL [distance: 14847.667]
* YMCA, Onondaga, NY [distance: 15818.08]
* 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.
### 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.
> [/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)
| parameter | value |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA |
| `focus.point.lat` | -33.856680 |
| `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!?
> * YMCA, Redfern, New South Wales [distance: 3.836]
* YMCA, St Ives (NSW), New South Wales [distance: 14.844]
* YMCA, Epping (NSW), New South Wales [distance: 16.583]
* YMCA, Revesby, New South Wales [distance: 21.335]
* YMCA, Larrakeyah, Northern Territory [distance: 3144.296]
* YMCA, Kepnock, Queensland [distance: 1001.657]
* YMCA, Kings Meadows, Tasmania [distance: 917.144]
* YMCA, Katherine East, Northern Territory [distance: 2873.376]
* YMCA, Sadadeen, Northern Territory [distance: 2026.731]
* YMCA, Ararat, Victoria [distance: 841.022]
### Prioritize within a circular boundary
**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.
> [/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)
| parameter | value |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `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*** |
Check out the results. They are all less than 50km away from the focus point:
> * YMCA, Redfern, New South Wales [distance: 3.836]
* YMCA, St Ives (NSW), New South Wales [distance: 14.844]
* YMCA, Epping (NSW), New South Wales [distance: 16.583]
* YMCA, Revesby, New South Wales [distance: 21.335]
* Caringbah YMCA, Caringbah, New South Wales [distance: 22.543]
* YMCA building, Loftus, New South Wales [distance: 25.756]
## Filtering 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
### ...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:
| source | name | short name |
|---|---|---|
| [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` |
| [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` |
| [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.
#### Example time
Let's search for **YMCA** again but only within the **OpenAddresses** 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)
| parameter | value |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA |
| `sources` | **oa** |
Since 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
* 14843 Ymca Lane, Cormorant, MN
* 14660 Ymca Lane, Cormorant, MN
* 6221 Ymca Lane, Northampton County, VA
* 6223 Ymca Lane, Northampton County, VA
* 74 Ymca Road, Wairoa District, Hawke's Bay Region
* 108 Ymca Drive, Clinton, SC
* 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.
> [/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)
| parameter | value |
| :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `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:
|layer|description|
|----|----|
|`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`|***TBD***|
|`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)
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)

113
getting-started/003-reverse.md
Unescape View File

@ -1,2 +1,115 @@
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.
With reverse geocoding, you can lookup all sorts of information about a point on a map, including:
* addresses
* points of interest (businesses, museums, parks, etc)
* neighborhoods
* cities
* states
* postal areas
* countries
So [go get an API key](https://mapzen.com/developers) and let's get started.
## 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:
>[/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.
## Advanced Usage
Like other entry points, reverse geocoding can use additional parameters to refine results.
### 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:
>[/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.
### Sources
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:
>[/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).
### 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):
>[/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).
### 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:
>[/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 <a href="https://en.wikipedia.org/wiki/ISO_3166-1" target="\_blank">here</a> 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.
## Confidence Scores
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`.
distance from `point.lat`/`point.lon` | Confidence Score
--- | ---
&lt; 1m | 1.0
&lt; 10m | 0.9
&lt; 100m | 0.8
&lt; 250m | 0.7
&lt; 1km | 0.6
&gt;= 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` | <a href="https://en.wikipedia.org/wiki/ISO_3166-1" target="\_blank">ISO-3166 alpha-2 or alpha-3</a> | no | none | `FR`
## 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
>[/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
>[/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
>[/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
>[/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)

42
getting-started/004-place.md
Unescape View File

@ -1,2 +1,44 @@
Places
=======
Place search is for when you have an ID and the source it came from and now you just need the details.
Once you have [an API key](https://mapzen.com/developers), continue on.
## The Basics
A place search requires 3 pieces of information:
1. source
2. layer
3. id
Once you have all 3 of those, simply join them together with semicolon and pass in on the ids parameter.
For example, this /place query looks up the Eiffel Tower in OSM:
http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:venue:5013364
## Advanced Usage
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:
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
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.
## Valid combinations
Some combinations of `sources` and `layers` are valid while others aren't. Please use the following table for reference:
source | layers
--- | ---
`osm` or `openstreetmap` | `venue`, `address`
`oa` or `openaddresses` | `address`
`gn` or `geonames` | `venue`, `address`, `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse`
`qs` or `quattroshapes` | `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse`

BIN
getting-started/boundary_london.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 120 KiB

BIN
getting-started/focus_point.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 255 KiB

BIN
getting-started/overlapping_boundaries.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.1 MiB

BIN
getting-started/world_all.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 359 KiB

BIN
getting-started/world_circle.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 372 KiB

BIN
getting-started/world_country.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 364 KiB

BIN
getting-started/world_rect.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 373 KiB

63
tools/locmux.js
Unescape View File

@ -0,0 +1,63 @@
/**
* To run do as follows:
*
* $ npm install request
* $ node locmux.js 'text i want to search for'
*
* If you'd like more locations to be searched just add them to the list below.
*
*/
var request = require('request');
var colors = require('text-hex');
var async = require('async');
var locations = [
{
name: 'London',
lat: 51.507222,
lon: -0.1275
},
{
name: 'New York',
lat: 37.783333,
lon: -122.416667
}
];
var text = process.argv[2];
var geojsonio = true; //process.argv[2] === 'geojson';
var geojson = {
type: 'FeatureCollection',
features: []
};
async.forEach(locations, function (loc, cb) {
request.get('http://pelias.bigdev.mapzen.com/v1/search?text=' + text +
'&focus.point.lat=' + loc.lat + '&focus.point.lon=' + loc.lon, function (err, res) {
var results = JSON.parse(res.body);
if (!geojsonio) {
console.log('\n\n\nSearching for "' + text + '" near ' + loc.name);
console.log('> result count:', results.features.length);
}
results.features.forEach(function (feature) {
feature.properties['marker-color'] = colors(loc.name);
feature.properties.query = loc.name;
geojson.features.push(feature);
if (!geojsonio) {
console.log(feature.properties.label);
}
});
cb();
});
},
function () {
if (geojsonio) {
console.log(JSON.stringify(geojson));
}
});

17
tools/package.json
Unescape View File

@ -0,0 +1,17 @@
{
"name": "tools",
"version": "1.0.0",
"description": "",
"main": "locmux.js",
"scripts": {
"start": "node locmux.js geojson"
},
"author": "Diana Shkolnikov <dianashk@gmail.com>",
"license": "MIT",
"dependencies": {
"async": "^1.4.2",
"geojsonio-cli": "^0.1.2",
"request": "^2.62.0",
"text-hex": "0.0.0"
}
}
Write Preview
Loading…
Cancel
Save