pelias
/
documentation
mirror of https://github.com/pelias/documentation.git
1
0
Fork 0
Code Issues Releases Activity
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.
38 Commits
5 Branches
0 Tags
13 MiB
 
Tree: e33c51c12c
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'e33c51c12c'
${ noResults }
documentation/getting-started/002-search.md

15 KiB
Raw Blame History

SEARCH, or Looking for Places

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.

🏫 💈 🏦 🇺🇸 🏡 🏥 ......... 💻

The most basic scenario

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.

Find an address

You would set the following parameters in your query url:

parameter value
api_key get yours here
text 30 West 26th Street, New York, NY

[/v1/search?api_key={YOUR-KEY}&text=30 West 26th Street, New York, NY](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=30 West 26th Street, New York, NY)

...go ahead, and click that link, we'll wait

You probably saw some cool GeoJSON, more on that later, with the following places in the results:

  • 30 West 26th Street, Manhattan, NY
  • 30 West 26th Street, Manhattan, NY
  • 30 West 26th Street, Manhattan, NY
  • 30 West 26th Street, Merced, CA
  • 307 West 26th Street, Manhattan, NY
  • 300 West 26th Street, Manhattan, NY
  • 307 West 26th Street, Manhattan, NY
  • 301 West 26th Street, Manhattan, NY
  • 30 East 26th Street, Manhattan, NY
  • 2 West 26th Street, Manhattan, NY

Find a venue

As mentioned above, query text can be a partial or full name of a place we're looking for. So here's an example of another way of finding that address we just searched for:

parameter value
api_key get yours here
text Samsung Accelerator

[/v1/search?api_key={YOUR-KEY}&text=Samsung Accelerator](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=Samsung Accelerator)

Or maybe a landmark, like Yankee Stadium

parameter value
text yankee stadium
api_key get yours here

[/v1/search?api_key={YOUR-KEY}&text=yankee stadium](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=yankee stadium)

cApiTaliZAtioN

You may have noticed already that cApiTaliZAtioN isn't a big deal for search. You can type yankee stadium or Yankee Stadium or even YANKEE STADIUM if you're really excited about finding it. See for yourself by comparing the results of the previous search to the following:

parameter value
text YANKEE STADIUM
api_key get yours here

[/v1/search?api_key={YOUR-KEY}&text=YANKEE STADIUM](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=YANKEE STADIUM)

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 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:

{
  "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.

{  
  "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.

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.

Want a single result?

Just set the size parameter to the desired number:

parameter value
text stinky beach
size 1
api_key get yours here

[/v1/search?api_key={YOUR-KEY}&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?

parameter value
text stinky beach
size 25
api_key get yours here

[/v1/search?api_key={YOUR-KEY}&text=stinky beach&size=25](https://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=stinky beach&size=25)

Narrowing your Search

All this time you've been searching the entire world...

What if you need results from only a...

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.

...rectangular region

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:

Let's say you wanted to find museums in London

You'd need to set the boundary.rect.* parameter grouping to indicate the extent of the boundary.

parameter value
text museum
boundary.rect.min_lat 51.286839
boundary.rect.min_lon -0.51035
boundary.rect.max_lat 51.692322
boundary.rect.max_lon 0.33403
api_key get yours here

/v1/search?api_key={YOUR-KEY}&text=museum&boundary.rect.min_lat=51.286839&boundary.rect.min_lon=-0.51035&boundary.rect.max_lat=51.692322&boundary.rect.max_lon=0.33403

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?
parameter value
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
api_key get yours here

[/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)

...circular region

Sometimes you don't have a rectangle to work with, but you you've got instead a point on earth, for example your location coordinates, and a maximum distance within which acceptable results can be located.

Find all Starbucks locations within a 3km radius of a spot in Madrid

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.

parameter value
text starbucks
boundary.circle.lat 40.414149
boundary.circle.lon -3.703755
boundary.circle.radius 3
api_key get yours here

/v1/search?api_key={YOUR-KEY}&text=starbucks&boundary.circle.lat=40.414149&boundary.circle.lon=-3.703755&boundary.circle.radius=3

...specific country

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.

Try searching for San Francisco in Columbia
parameter value
text san francisco
boundary.country COL
api_key get yours here

[/v1/search?api_key={YOUR-KEY}&text=san francisco&boundary.country=COL](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=san francisco&boundary.country=COL)

Note that all the results have country set to Columbia.

Now try searching for San Francisco in the USA
parameter value
text san francisco
boundary.country US
api_key get yours here

[/v1/search?api_key={YOUR-KEY}&text=san francisco&boundary.country=US](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=san francisco&boundary.country=US)

You can see all the results are now from within the US, and the top place is San Francisco, CA. Awesome, right?!

Boundary issues

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:

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.

Focus on a point

Search will focus on a given point anywhere on earth, and results within ~100km will be prioritized, 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.

Let's find City Hall near the center of Washington, DC

parameter value
text city hall
focus.point.lat 38.8993488
focus.point.lon -77.0145665
api_key get yours here

[/v1/search?api_key={YOUR-KEY}&text=city hall&focus.point.lat=38.8993488&focus.point.lon=-77.0145665](http://pelias.bigdev.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=city hall&focus.point.lat=38.8993488&focus.point.lon=-77.0145665)

  • focus viewport api example (e.g. union square)
  • focus point api example (NY union square)

TBD

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 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

Our layers are derived from the hierarchy created by the gazetteer Who's on First and can be used to facilitate coarse geocoding.

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

For end-user applications, /autocomplete is intended to be used alongside /search to facilitate real-time feedback for user s