In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To accomplish this, build a query where the `text` parameter is set to the item you want to find.
@ -30,7 +30,7 @@ Note the parameter values are set as follows:
Clicking the link above will open a file containing the best matching results for the text `YMCA`. You will notice the data is in a computer-friendly format called [GeoJSON](http://geojson.org/), which may be hard for humans to read in some browsers.
@ -61,7 +61,7 @@ If you are looking for places in a particular region, or country, or only want t
### Search within a particular country
Sometimes your work might require that all the search results be from a particular country. To do this, you can 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).
@ -73,7 +73,7 @@ Now, you want to search for YMCA again, but this time only in Great Britain. To
Note that all the results reside within Great Britain:
@ -107,7 +107,7 @@ Results in the United States:
### Search within a rectangular region
To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the minimum and the maximum latitude, longitude).
@ -121,10 +121,10 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary
@ -139,7 +139,7 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary
### Search within a circular region
Sometimes you don't have a rectangle to work with, but rather you have a point on earth—for example, your location coordinates—and a maximum distance within which acceptable results can be located.
@ -151,9 +151,9 @@ In this example, you want to find all YMCA locations within a 35-kilometer radiu
You can see the results have fewer than the standard 10 items because there are not that many YMCA locations in the specified radius:
@ -166,16 +166,14 @@ You can see the results have fewer than the standard 10 items because there are
### Specify multiple 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 an image of how it works:
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.
## Prioritize results by proximity
Many use cases call for the ability to promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. Mapzen Search allows you to prioritize results within geographic boundaries, including around a point, within a country, or within a region.
### Prioritize around a point
By specifying a `focus.point`, nearby places will be scored higher depending on how close they are to the `focus.point` so that places with higher scores will appear higher in the results list. The effect of this scoring boost diminishes to zero after 100 kilometers away from the `focus.point`. After all the nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization.
@ -187,8 +185,8 @@ To find YMCA again, but this time near a specific coordinate location (represent
Looking at the results, you can see that the few locations closer to this location 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. Because you provided a focus point, Mapzen Search can compute distance from that point for each resulting feature.
@ -218,7 +216,7 @@ Going back to the YMCA search you conducted with a focus around a point in Sydne
| `text` | YMCA |
| `focus.point.lat` | -33.856680 |
| `focus.point.lon` | 151.215281 |
| `boundary.country` | ***AUS*** |
| `boundary.country` | AUS |
The results below look very different from the ones you 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 top of the list, which is facilitated by the focus parameter.
@ -245,9 +243,9 @@ If you are looking for the nearest YMCA locations, and are willing to travel no
| `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*** |
| `boundary.circle.lat` | -33.856680 |
| `boundary.circle.lon` | 151.215281 |
| `boundary.circle.radius` | 50 |
Looking at these results, they are all less than 50 kilometers away from the focus point:
@ -276,8 +274,6 @@ The search examples so far have returned a mix of results from all the data sour
****TO DO: Add a description of each of these.*****
If you use the `sources` parameter, you can choose which of these data sources to include in your search. So if you're only interested in finding a YMCA in data from OpenAddresses, for example, you can build a query specifying that data source.
In Mapzen Search, place types are referred to as `layers`, ranging from fine to coarse. The Mapzen Search 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 the results, sorted by granularity:
****TO DO: Describe fine and coarse geocoding, gazeteer. ***
|layer|description|
|----|----|
|`venue`|points of interest, businesses, things with walls|
@ -323,7 +317,7 @@ In Mapzen Search, place types are referred to as `layers`, ranging from fine to
|`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|
rmglennon
9 years ago