API – Step-by-step

Understanding what is going on

To include a map in a web page you will need 4 things:

• Include OpenLayers
• A <div> map container
• A valid API Key
• JavaScript to create a simple map

1. Include OpenLayers

The first part is to include the custom build mapz OpenLayers JavaScript library:

                

<link rel='stylesheet' href='https://www.mapz.com/api/static/css/ol/7.3.0/ol.css' />
<script src='https://www.mapz.com/api/static/javascript/lib/7.3.0/ol.js'
type='text/javascript'></script>
              

2. <div> map container>

The map in the application is contained in a <div> HTML element.

                    

<div id='map' class='map'></div>
                
                  

The map properties like width, height and border can be controlled through CSS (refer to the "CSS-Index" provided with the code examples). Here's the CSS element used to make the map 600 pixels high and as wide as the browser window.

                

<style>
    .map {
      height: 600px;
      width: 100%;
    }
  </style>
    

3. JavaScript to create a simple map

With this JavaScript code, a map object is created with a map layer "Shades of Gray" zoomed on Kapstadt in South Africa:

              

<script>
  var map = new ol.Map({
    target: document.getElementById('map'),
    logo: false,
    layers: [
      new ol.layer.Tile({
        source: new ol.source.XYZ({
          tilePixelRatio: 2,
          url:'https://tiles.mapz.com/mapproxy/v1/demo-817ca352/tiles/1.0.0/mapz_shades_of_gray_hq/EPSG3857/{z}/{x}/{-y}.jpeg'
        }),
      })
    ],
    view: new ol.View({
      center: ol.proj.transform([18.41723, -33.92717], 'EPSG:4326', 'EPSG:3857'),
      zoom: 14
    })
  });
</script>

4. API Key

Don't forget: Replace demo-817ca352 in the Layer retrieval URL with your own API key. Please send an email to our autoresponder at demo.api.key@mapz.com to immediately receive a fully functional demo key.

Let's break this down:

The following line creates an OpenLayers Map object. Just by itself, this does nothing since there's no layers or interaction attached to it.

 var map = new ol.Map({ ... });

To attach the map object to the <div>, the map object takes a target into arguments. The value is the id of the <div>:

target: document.getElementById('map'),

In the Array "layers: [ ... ] you can specify in the URL which of the available map layers you want the system to retrieve. In our example, the layer "mapz_shades_of_gray_hq" from our map design line "Shades of Gray" is displayed in Retina quality and is specified directly in the URL. However, by setting the tilePixelRatio to 2, the browser will shrink all maps for low-resolution screens. To directly retrieve a lower resolution image, simply use mapz_shades_of_gray instead of mapz_shades_of_gray_hq, set the tilePixelRatio to 1, and use .jpeg instead of .png.

   layers: [
      new ol.layer.Tile({
        source: new ol.source.XYZ({
          tilePixelRatio: 2,
          url:'https://tiles.mapz.com/mapproxy/v1/demo-817ca352/tiles/1.0.0/mapz_shades_of_gray_hq/EPSG3857/{z}/{x}/{-y}.jpeg'
        }),
      })
    ],

You can also combine our maps with layers from external sources e.g. your own layers. You can find a list of the possible data formats here.

The next part of the Map object is the View. The view allow to specify the center, resolution, and rotation of the map. The simplest way to define a view is to define a center point and a zoom level. Note that zoom level 0 is zoomed out. The maximum zoom level is 22.

      view: new ol.View({
        center: ol.proj.transform([18.41723, -33.92717], 'EPSG:4326', 'EPSG:3857'),
        zoom: 14
      })

You will notice that the center specified is in lat/lon coordinates (EPSG:4326). Since the only layer we use is in Spherical Mercator projection (EPSG:3857), we can reproject them on the fly to be able to zoom the map on the right coordinates.

That was already everything that was needed to embed a map. More clues about possible parameters can be found directly within the code of our coding examples.

You can find additional information with OpenLayers. Useful tools for converting from CSV files to JSON or GeoJSON files are provided on the website ConvertCSV.com.