15 KiB

Raw Blame History Unescape Escape

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

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

Search the World

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.

Example time

Let's search for YMCA. Here's what you'd need to append to the base URL of the service, search.mapzen.com.

/v1/search?api_key={YOUR-KEY}&text=YMCA

Note the parameter values are set as follows:

parameter	value
`api_key`	get yours here
`text`	YMCA

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:

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

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

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.

...to a 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.

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:

/v1/search?api_key={YOUR-KEY}&text=YMCA&boundary.country=GBR

parameter	value
`api_key`	get yours here
`text`	YMCA
`boundary.country`	GBR

Note that all the results reside within Great Britain:

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

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

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

/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

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

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

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

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 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 Disney World, Florida

/v1/search?api_key={YOUR-KEY}&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281

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

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]

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

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)

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:

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

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)

15 KiB Raw Blame History Unescape Escape

SEARCH, or Looking for Places

Search the World

Example time

Narrowing your Search...

...to a specific country

Example time

...to a rectangular region

Example time

...to a circular region

Example time

We respect your boundaries

Prioritizing Nearby Places

Focus on a point

Example time

Results

Result count

Want a single result?

How about 25 results?

TBD

Combining Focused Results with Boundaries

Selecting Datasets

Selecting Sources

Selecting Layers

Coarse Geocoding (Neighborhoods, Cities, States, Countries)

Using Autocomplete & Search Together

cApiTaliZAtioN

15 KiB

Raw Blame History Unescape Escape

`SEARCH`, or Looking for Places

Selecting `Sources`