Places API reference

Estimated reading time: 10 minutes

Add the Jawg Places geocoder to a map

Get ready for the tutorial

In this tutorial, you will learn how to make a map with a search box that allows you to enter addresses and place names and locate them on a map. To complete the tutorial, you should have some familiarity with HTML and JavaScript, although all the source code is provided. You can use any text editor and operating system, but must keep an Internet connection while you are working.

You also need a Jawg API key, which you can get by following the steps in the Jawg website.

Create an HTML page

You are ready to start building your web page and map.

Tip: The end of this page has a finished version of the code that you can use to check your work or review if you need to troubleshoot an error.

  • Start your text editor with a blank document and copy and paste the following HTML. (Note: If the text editor you are using requires you to name and save a document at the time when it is first created, call the file index.html.)
<!DOCTYPE html>
<html>
<head>
</head>
<body>
</body>
</html>

These form the basic structure of an HTML document. <!DOCTYPE html> goes at the top of every HTML page and indicates that it is written for HTML5, and the <html> tags tell your browser that the content is HTML. The <head> tag contains the title for the page and other metadata about the page, while the <body> is where you add the code and the rest of the content on your page. There are many web tutorials available to help you experiment with and learn more about HTML documents and the tags in them.

  • In the <head> tag, add a title, such as <title>My Geocoding Map</title>.
  • On the next line, add a metadata tag so you can properly display diacritics and characters from different languages.
<meta charset="utf-8">
  • Name your the document index.html (where the file name is index and the type is .html) and save it.
  • Drag your index.html file onto a web browser tab. It should show your title, My Geocoding Map, but the web page canvas will be blank.

Your HTML should look like this:

<!DOCTYPE html>
<html>
<head>
  <title>My Geocoding Map</title>
  <meta charset="utf-8">
</head>
<body>
</body>
</html>

Add references to CSS and JavaScript files

A cascading style sheet (CSS) is used to style a webpage, including layout and fonts, and JavaScript adds functionality to the page. In your index.html file, you need to list the CSS and JavaScript files needed to build your page.

The Leaflet JavaScript library provides tools for building an interactive map for web and mobile devices. Leaflet is extensible, and developers have built additional tools for Leaflet maps.

The leaflet-geocoder library simplifies the process of using Jawg Places within Leaflet.

  • In index.html, at the bottom of the <head> section, add references to leaflet and the leaflet-geocoder CSS and JavaScript files.
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.0.3/dist/leaflet.css" integrity="sha512-07I2e+7D8p6he1SIM+1twR5TIrhUQn9+I6yjqD53JQjFiMf8EtC93ty0/5vJTZGF8aAocvHYNEDJajGdNx1IsQ==" crossorigin="" />
  <script src="https://unpkg.com/leaflet@1.0.3/dist/leaflet.js" integrity="sha512-A7vV8IFfih/D732iSSKi20u/ooOfj/AGehOKq0f4vLT1Zr2Y+RX7C+w8A1gaSasGtRUZpF/NZgzSAu4/Gc41Lg==" crossorigin=""></script>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.2/leaflet-geocoder-mapzen.css">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.2/leaflet-geocoder-mapzen.js"></script>
  • Save your edits and refresh the browser. The webpage should still appear empty because you have not added any code to interact with these references.

After adding these, your index.html file should look something like this.

<!DOCTYPE html>
<html>
  <head>
  <title>My Geocoding Map</title>
  <meta charset="utf-8">
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.0.3/dist/leaflet.css" integrity="sha512-07I2e+7D8p6he1SIM+1twR5TIrhUQn9+I6yjqD53JQjFiMf8EtC93ty0/5vJTZGF8aAocvHYNEDJajGdNx1IsQ==" crossorigin="" />
    <script src="https://unpkg.com/leaflet@1.0.3/dist/leaflet.js" integrity="sha512-A7vV8IFfih/D732iSSKi20u/ooOfj/AGehOKq0f4vLT1Zr2Y+RX7C+w8A1gaSasGtRUZpF/NZgzSAu4/Gc41Lg==" crossorigin=""></script>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.2/leaflet-geocoder-mapzen.css">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.2/leaflet-geocoder-mapzen.js"></script>
</head>
<body>
</body>
</html>

Add a map to the page

To display a Leaflet map on a page, you need a <div> element, which is a container on the page that groups elements, with an ID value. If you want to know more about initializing a Leaflet map, see the Leaflet getting started documentation.

  • At the bottom of the <head> section, after the references you added in the earlier steps, add a <style> tag and the following attributes to set the size of the map on your webpage. A Leaflet map will not display unless you include a width.
<style>
  #map {
    height: 100%;
    width: 100%;
    position: absolute;
  }
  html,body{margin: 0; padding: 0}
</style>
  • At the top of the <body> section, add the <div>.
<div id='map'></div>
  • Directly after the <div>, add this JavaScript code within a <script> tag to initialize a map.
<script>
  var mymap = L.map('map').setView([48.7965913, 2.3210938], 15);
  L.tileLayer('https://tile.jawg.io/{your-style-id}/{z}/{x}/{y}.png?access-token=your-access-token', {}).addTo(mymap);
</script>

L.xxxxx is a convention used with the Leaflet API. The center: [47.61033,-122.31801] parameter sets the center point of the map, in decimal degrees, at the location of a building at Seattle University.

The next line sets the zoom level, which is like a map scale or resolution, where a smaller value shows a larger area in less detail, and a larger zoom level value depicts smaller area in great detail.

  • Save your edits and refresh the browser.

Your index.html should look something like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.0.3/dist/leaflet.css" integrity="sha512-07I2e+7D8p6he1SIM+1twR5TIrhUQn9+I6yjqD53JQjFiMf8EtC93ty0/5vJTZGF8aAocvHYNEDJajGdNx1IsQ==" crossorigin="" />
    <script src="https://unpkg.com/leaflet@1.0.3/dist/leaflet.js" integrity="sha512-A7vV8IFfih/D732iSSKi20u/ooOfj/AGehOKq0f4vLT1Zr2Y+RX7C+w8A1gaSasGtRUZpF/NZgzSAu4/Gc41Lg==" crossorigin=""></script>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.2/leaflet-geocoder-mapzen.css">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.2/leaflet-geocoder-mapzen.js"></script>

    <style>
      #map {
        height: 100%;
        width: 100%;
        position: absolute;
      }
    html,body{margin: 0; padding: 0}
  </style>

  </head>
  <body>
    <div id='map'></div>
    <script>
      var mymap = L.map('mapid').setView([48.7965913, 2.3210938], 15);
      L.tileLayer('https://tile.jawg.io/{your-style-id}/{z}/{x}/{y}.png?access-token=your-access-token', {}).addTo(mymap);
    </script>
  </body>
</html>

At this point, you have a map! You should see a map, zoom controls, and attribution in the bottom corner.

So far, you have referenced the necessary files, initialized Leaflet with a map container on the page, and added data to the map. Now, you are ready to add the Search box.

  • Inside the same <script> tag, and after the code you just added for the map, initialize a search box and add it to the map with the following code.
L.control.geocoder('your-access-token', {url: 'https://places.jawg.io/v1', autocomplete: false}).addTo(mymap);
  • Save your edits and refresh the browser. You should see search button in the left corner. If you want to expand the button to a box, you can change this behavior in the geocoder options.

Your <body> section should look like this:

[...]
<script>
  var mymap = L.map('mapid').setView([48.7965913, 2.3210938], 15);
  L.tileLayer('https://tile.jawg.io/{your-style-id}/{z}/{x}/{y}.png?access-token=your-access-token', {}).addTo(mymap);
  L.control.geocoder('your-access-token', {url: 'https://places.jawg.io/v1', autocomplete: false}).addTo(mymap);
</script>
[...]

Search for places on the map

Now, you will test your search box by finding a few locations. As you type, the text automatically completes to suggest matching results.

  • On the map, type Seattle University in the Search box.
  • In the results list, find the entry for Seattle University and click it to zoom and add a point to the map at that location. (The point is only on your map, and does not update OpenStreetMap.)
  • Search for other addresses or places to experiment with the search function and get an idea of the results it returns. For example, you might try looking for a point of interest in Seattle, your work address, or a city outside the United States.

Tutorial summary

In this tutorial, you learned the basics of adding the Jawg Places geocoding engine to a map using leaflet-geocoder.

If you want to learn more about Jawg Places, review the Mapzen’s documentation.

Because the geocoder is still under development and considered experimental, if you are getting unexpected search results, please add an issue to the Pelias GitHub repository. The developers can investigate and decide if the problem is caused by software or data, and work to fix it either way.

Completed HTML for this tutorial

You can refer to this HTML if you want to review your work or troubleshoot an error.

<!DOCTYPE html>
<html>

<head>
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.0.3/dist/leaflet.css" integrity="sha512-07I2e+7D8p6he1SIM+1twR5TIrhUQn9+I6yjqD53JQjFiMf8EtC93ty0/5vJTZGF8aAocvHYNEDJajGdNx1IsQ==" crossorigin="" />
  <script src="https://unpkg.com/leaflet@1.0.3/dist/leaflet.js" integrity="sha512-A7vV8IFfih/D732iSSKi20u/ooOfj/AGehOKq0f4vLT1Zr2Y+RX7C+w8A1gaSasGtRUZpF/NZgzSAu4/Gc41Lg==" crossorigin=""></script>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.2/leaflet-geocoder-mapzen.css">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.2/leaflet-geocoder-mapzen.js"></script>
</head>

<body>
  <div id='mapid' style='width: 400px; height: 300px;'></div>
  <script>
    var mymap = L.map('mapid').setView([48.7965913, 2.3210938], 15);
    L.tileLayer('https://tile.jawg.io/{your-style-id}/{z}/{x}/{y}.png?access-token=your-access-token', {}).addTo(mymap);
    L.control.geocoder('your-access-token', {url: 'https://places.jawg.io/v1', autocomplete: false}).addTo(mymap);
  </script>
</body>

</html>