Mapzen Search: Finding places

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.

All Mapzen Search requests share the same format:

   https://search.mapzen.com/v1/search?text=London&api_key=mapzen-xxxxxx
   \___/   \_______________/\__/\_____/\__________/\___________________/
     |            |          /     |        |                |
  scheme       domain   version  path     query     authentication token

In addition, you can search at https://search.mapzen.com/v1/search/structured to look for individual components of a location.

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

Searching globally

In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To do this, build a query where the text parameter is set to the item you want to find.

For example, if you want to find a YMCA facility, here’s what you’d need to append to the base URL of the service, search.mapzen.com.

/v1/search?api_key=mapzen-xxxxxx&text=YMCA

Note the parameter values are set as follows:

parameter value
api_key get yours here
text YMCA

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

  • 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

Spelling matters, but not capitalization when performing a query with Mapzen Search. You can type ymca, YMCA, or even yMcA. See for yourself by comparing the results of the earlier search to the following:

/v1/search?api_key=mapzen-xxxxxx&text=yMcA

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, you can search for individual components of a location.

Structured geocoding accepts one or more of the following parameters:

  • address
  • neighbourhood
  • borough
  • locality
  • county
  • region
  • postalcode
  • country

Structured geocoding also supports the other parameters from search, allowing you to filter and prioritize your results.

For more information on how to search this way, see Structured geocoding.

Set the number of results returned

By default, Mapzen Search 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.

parameter value
api_key get yours here
text YMCA
size 1

/v1/search?api_key=mapzen-xxxxxx&text=YMCA&size=1

If you want 25 results, you can build the query where size is 25.

/v1/search?api_key=mapzen-xxxxxx&text=YMCA&size=25

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

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

To find YMCA again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use focus.point.

/v1/search?api_key=mapzen-xxxxxx&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 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.

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

Combine boundary search and prioritization

Now that you have seen how to use boundary and focus to narrow and sort your results, you can examine a few scenarios where they work well together.

Prioritize within a country

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.

/v1/search?api_key=mapzen-xxxxxx&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
boundary.country AUS

The results below look different from the ones you saw before 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 helped by the focus parameter.

  • 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, Larrakeyah, Northern Territory [distance: 3144.296]
  • YMCA, Kepnock, Queensland [distance: 1001.657]
  • YMCA, Kings Meadows, Tasmania [distance: 917.144]
  • YMCA, Katherine East, Northern Territory [distance: 2873.376]
  • YMCA, Sadadeen, Northern Territory [distance: 2026.731]
  • YMCA, Ararat, Victoria [distance: 841.022]

Prioritize within a circular region

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.

/v1/search?api_key=mapzen-xxxxxx&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

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

Looking at these results, they are all less than 50 kilometers away from the focus point:

  • 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]
  • Caringbah YMCA, Caringbah, New South Wales [distance: 22.543]
  • YMCA building, Loftus, New South Wales [distance: 25.756]

Available search parameters

Parameter Type Required Default Example
api_key string yes none get yours here
text string yes none Union Square
focus.point.lat floating point number no none 48.581755
focus.point.lon floating point number no none 7.745843
boundary.rect.min_lon floating point number no none 139.2794
boundary.rect.max_lon floating point number no none 140.1471
boundary.rect.min_lat floating point number no none 35.53308
boundary.rect.max_lat floating point number no none 35.81346
boundary.circle.lat floating point number no none 43.818156
boundary.circle.lon floating point number no none -79.186484
boundary.circle.radius floating point number no 50 35
sources string no all sources: osm,oa,gn,wof openstreetmap,wof
layers string no all layers: address,venue,neighbourhood,locality,borough,localadmin,county,macrocounty,region,macroregion,country,coarse address,venue
boundary.country string no none ‘GBR’
size integer no 10 20