6.1 KiB

Raw Blame History

`SEARCH`

Turning human recognizable place names into computer recognizable geographic coordinates

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 [...].

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

Looking For Places - Getting Started

{search text, global, no options}

The most basic scenario

Let's say you wanted to find Stinky Beach, you would simply query the search API as follows:

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

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

Maybe you'd like to find an address, like this:

[/v1/search?api_key={YOUR-KEY}&text=30 west 26th street](https://search.mapzen.com/v1/search?api_key={YOUR_API_KEY}&text=30 west 26th street)

Or even a landmark, like Yankee Stadium:

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

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:

[/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 document. Read more about the response format.

Result count

You may have noticed that there were 10 places in the results for our Stinky Beach search. That's the default number of results the API will return, unless otherwise specified.

Want a single result?

[/v1/search?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?

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

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

Boundaries are mutually exclusive

Country (country code)
Rectangle (bbox)
Circle (point, radius)

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:

the originating source of the data (sources)
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 options}

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

6.1 KiB Raw Blame History

SEARCH