Geospatial search, commonly referred to as geocoding, is the process of matching an address to its corresponding geographic coordinates.
There's nothing inherent in the language we use to describe a physical address that allows us to convert that human readable sentence in to a format that a computer can understand, such as latitude & longitude.
Making the leap from text to coordinates is an intricate and challenging process. Lucky for you, Mapzen has done all the hard work and made it accessible though a web service.
Geocoding is the process of matching an address or other text to its corresponding geographic coordinates.
scheme domain version path query authentication token
https://search.mapzen.com/v1/search?text=London
\___/ \_______________/\__/\_____/\_________/
| | / | |
scheme domain version path query
```
In addition, you can search at `https://search.mapzen.com/v1/search/structured` to look for individual components of a location.
Pelias works over HTTPS and HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query.
## Search the world
@ -27,20 +19,19 @@ In the simplest search, you can provide only one parameter, the text you want to
For example, if you want to find a [YMCA](https://en.wikipedia.org/wiki/YMCA) facility, here's what you'd need to append to the base URL of the service, `search.mapzen.com`.
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.
You can install a plug-in for your browser to display JSON in a more formatted manner. You can search the web store for your browser to find and install applicable products.
In the example above, you will find the name of each matched locations in a property named `'label'`. The top 10 labels returned were:
In the example above, you will find the name of each matched locations in a property named `'label'`. The top 10 labels returned at the time of writing were:
* YMCA, Bargoed Community, United Kingdom
* YMCA, Nunspeet, Gelderland
@ -55,13 +46,13 @@ In the example above, you will find the name of each matched locations in a prop
Spelling matters, but not capitalization when performing a query with Pelias. You can type `ymca`, `YMCA`, or even `yMcA`. See for yourself by comparing the results of the earlier search to the following:
Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search.
## Search for a component of a location
With the `text` parameter, your search is composed of all the items in one string. With [structured geocoding](http://search.mapzen.com/v1/search/structured), you can search for individual components of a location.
With the `text` parameter, your search is composed of all the items in one string. With [structured geocoding](structured-geocoding.md), you can search for individual components of a location.
Structured geocoding accepts one or more of the following parameters:
@ -80,19 +71,18 @@ For more information on how to search this way, see [Structured geocoding](struc
## Set the number of results returned
By default, Pelias results 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning only the first result.
By default, Pelias results up to 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning only the first result.
@ -106,11 +96,10 @@ Sometimes your work might require that all the search results be from a particul
Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is GBR and set the parameters like this:
@ -184,11 +172,10 @@ Sometimes you don't have a rectangle to work with, but rather you have a point o
In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` is your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers.
@ -250,11 +236,10 @@ Now that you have seen how to use boundary and focus to narrow and sort your res
Going back to the YMCA search you conducted with a focus around a point in Sydney, the results came 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. You can combine that same focus point in Sydney with the country boundary of Australia like this.
@ -277,11 +262,10 @@ The results below look different from the ones you saw before with only a focus
If you are looking for the nearest YMCA locations, and are willing to travel no farther than 50 kilometers from your current location, you likely would want the results to be sorted by distance from current location to make your selection process easier. You can get this behavior by using `focus.point` in combination with `boundary.circle.*`. You can use the `focus.point.*` values as the `boundary.circle.lat` and `boundary.circle.lon`, and add the required `boundary.circle.radius` value in kilometers.
@ -319,34 +303,32 @@ The search examples so far have returned a mix of results from all the data sour
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.
Because 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
* 20 Ymca Drive, Niagara, ON, Canada
* 341 Ymca Rd, New Hope, AL, USA
* 318 Ymca Rd, New Hope, AL, USA
* 138 Ymca Rd, New Hope, AL, USA
* 304 Ymca Rd, New Hope, AL, USA
* 1919 Ymca Lane, Minnetonka, MN, USA
* 101 Ymca Dr, Kannapolis, NC, USA
* 2121 Ymca Camp Road, Stokes County, NC, USA
* 1110 Ymca Camp Road, Stokes County, NC, USA
* 1581 Ymca Camp Road, Stokes County, NC, USA
If you wanted to combine several data sources together, 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 you specified one.
Julian Simioni
7 years ago