Places API reference

Estimated reading time: 15 minutes

Jawg Places: Finding places

Geocoding is the process of matching an address or other text to its corresponding geographic coordinates.

All Jawg Places requests share the same format:

    https://api.jawg.io/places/v1/search?text=Paris&access-token=your-jawg-access-token
    \___/   \_________/\_____/\__/\_____/\________/\__________/
      |          |        |     \      \      |           |
    scheme     domain service  version path  query   authentication token

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 Paris, here’s what you’d need to append to the base URL of the service, api.jawg.io/places.

/v1/search?access-token=your-jawg-access-token&text=Paris

Note the parameter values are set as follows:

parameter value
access-token get yours here
text Paris

Clicking the link above will open a file containing the best matching results for the text Paris. 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 at the time of writing were:

  • Paris, France
  • Paris, TX, USA
  • Paris, TN, USA
  • Paris, OH, USA
  • Paris, IL, USA
  • Paris, OH, USA
  • Paris, ME, USA
  • Paris, IL, USA
  • Paris, AR, USA

Spelling matters, but not capitalization when performing a query with Jawg Places. You can type paris, PARIS, or even PaRiS. See for yourself by comparing the results of the earlier search to the following:

/v1/search?access-token=your-jawg-access-token&text=PaRiS

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://api.jawg.io/places/v1/search/structured/), 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, Jawg Places 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.

parameter value
access-token get yours here
text Paris
size 1

/v1/search?access-token=your-jawg-access-token&text=Paris&size=1

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

/v1/search?access-token=your-jawg-access-token&text=Paris&size=25

If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. Jawg Places supports three types: country, rectangle, and circle.

Search within a particular country

Searching in a country

Sometimes your work might require that all the search results be from a particular country. To do this, you can set the boundary.country parameter value to the alpha-2 or alpha-3 ISO-3166 country code.

Now, you want to search for Paris again, but this time only in France. To do this, you will need to know that the alpha-3 code for France is FRA and set the parameters like this:

/v1/search?access-token=your-jawg-access-token&text=Paris&boundary.country=FRA

parameter value
access-token get yours here
text Paris
boundary.country FRA

Note that all the results are within France:

  • Paris, France

If you try the same search request with different country codes, the results change to show Paris locations within this region.

/v1/search?access-token=your-jawg-access-token&text=Paris&boundary.country=USA

Results in the United States:

  • Paris, TX, USA
  • Paris, TN, USA
  • Paris, OH, USA
  • Paris, IL, USA
  • Paris, OH, USA
  • Paris, ME, USA
  • Paris, KY, USA
  • Paris, AR, USA
  • Paris, ID, USA
  • Paris, PA, USA

Search within a rectangular region

Searching in a bounding box

To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the minimum and the maximum latitude, longitude).

For example, to find a Paris within the state of Texas, you can set the boundary.rect.* parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5

Tip: You can look up a bounding box for a known region with this web tool.

/v1/search?access-token=your-jawg-access-token&text=Paris&boundary.rect.min_lat=48.51&boundary.rect.min_lon=1.807&boundary.rect.max_lat=49.16&boundary.rect.max_lon=2.988

parameter value
access-token get yours here
text Paris
boundary.rect.min_lat 48.51
boundary.rect.min_lon 1.807
boundary.rect.max_lat 49.16
boundary.rect.max_lon 2.988
  • Paris, France

Search within a circular region

Searching within a circle

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

In this example, you want to find all Paris locations within a 300-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.

/v1/search?access-token=your-jawg-access-token&text=Paris&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=300

parameter value
access-token get yours here
text Paris
boundary.circle.lat 43.818156
boundary.circle.lon -79.186484
boundary.circle.radius 300

You can see the results have fewer than the standard 10 items because there are not that many Paris locations in the specified radius:

  • Paris, MI, USA

Specify multiple boundaries

Searching within multiple regions

If you’re going to try 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.

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. Jawg Places 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 Paris again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use focus.point.

/v1/search?access-token=your-jawg-access-token&text=Paris&focus.point.lat=-33.856680&focus.point.lon=151.215281

parameter value
access-token get yours here
text Paris
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, Jawg Places can compute distance from that point for each resulting feature.

  • Paris, France [distance: 16958.308]
  • Paris, France [distance: 16957.736]
  • Paris, TX, USA [distance: 13956.291]
  • Paris, TN, USA [distance: 14676.426]
  • Paris, IL, USA [distance: 14815.598]
  • Paris, OH, USA [distance: 15192.115]
  • Paris, OH, USA [distance: 15388.042]
  • Paris, ME, USA [distance: 16276.678]
  • Paris, ID, USA [distance: 12994.297]
  • Paris, AR, USA [distance: 14175.14]

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 Paris search you conducted with a focus around a point in Hell’s Kitchen, 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 Hell’s Kitchen with the country boundary of United States like this.

/v1/search?access-token=your-jawg-access-token&text=Paris&focus.point.lat=40.763758&focus.point.lon=-73.991818&boundary.country=USA

parameter value
access-token get yours here
text Paris
focus.point.lat 40.763758
focus.point.lon -73.991818
boundary.country USA

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.

  • Paris, TN, USA [distance: 1340.995]
  • Paris, TX, USA [distance: 2063.654]
  • Paris, ME, USA [distance: 482.243]
  • Paris, OH, USA [distance: 603.473]
  • Paris, OH, USA [distance: 797.081]
  • Paris, IL, USA [distance: 1173.48]
  • Paris, PA, USA [distance: 552.831]
  • Paris, KY, USA [distance: 927.723]
  • Paris, IL, USA [distance: 1172.513]
  • Paris, MO, USA [distance: 1539.17]

Prioritize within a circular region

If you are looking for the nearest Paris locations, and are willing to travel no farther than 500 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?access-token=your-jawg-access-token&text=Paris&focus.point.lat=40.763758&focus.point.lon=-73.991818&boundary.circle.lat=40.763758&boundary.circle.lon=-73.991818&boundary.circle.radius=500

parameter value
access-token get yours here
text Paris
focus.point.lat 40.763758
focus.point.lon -73.991818
boundary.circle.lat 40.763758
boundary.circle.lon -73.991818
boundary.circle.radius 500

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

  • Paris, ME, USA [distance: 482.243]
  • Paris, NY, USA [distance: 267.788]
  • Parrish, USA [distance: 460.717]

Jawg Places brings together data from multiple open sources and combines a variety of place types into a single database, allowing you options for selecting the dataset you want to search.

With Jawg Places, you can filter by:

  • sources: the originating source of the data
  • layers: the kind of place you want to find

Filter by data source

The search examples so far have returned a mix of results from all the data sources available to Jawg Places. Here are the sources being searched:

source name short name
OpenStreetMap openstreetmap osm
OpenAddresses openaddresses oa
Who’s on First whosonfirst wof
GeoNames geonames gn

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 Paris in data from OpenAddresses, for example, you can build a query specifying that data source.

/v1/search?access-token=your-jawg-access-token&text=Paris&sources=oa

parameter value
access-token get yours here
text Paris
sources oa

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.

/v1/search?access-token=your-jawg-access-token&text=Paris&sources=osm,gn

parameter value
access-token get yours here
text Paris
sources osm,gn

Each of these data sources has properties, licenses, and strengths. You can learn more about the data sources for Jawg Places.

Filter by data type

In Jawg Places, place types are referred to as layers, ranging from fine to coarse. The Jawg Places layers are derived from the hierarchy created by the gazetteer Who’s on First and can be used to help coarse geocoding. Here’s a list of the types of places you could find in the results, sorted by granularity:

layer description
venue points of interest, businesses, things with walls
address places with a street address
street streets,roads,highways
neighbourhood social communities, neighbourhoods
borough a local administrative boundary, currently only used for New York City
localadmin local administrative boundaries
locality towns, hamlets, cities
county official governmental area; usually bigger than a locality, almost always smaller than a region
macrocounty a related group of counties. Mostly in Europe.
region states and provinces
macroregion a related group of regions. Mostly in Europe
country places that issue passports, nations, nation-states
coarse alias for simultaneously using all administrative layers (everything except venue and address)

/v1/search?access-token=your-jawg-access-token&text=Paris&layers=venue,address

parameter value
access-token get yours here
text Paris
layers venue,address

Available search parameters

Parameter Type Required Default Example
access-token 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