Geovisualization Developer's Guide

Quickstart

Introduction

This quickstart will show you how to create a visualization by using a local CSV file as a data source and the Geovisualization JavaScript API to plot data-driven markers on a map.

Figure 1. Cultural Institutions Visualization

The example plots cultural locations on a map, with the data fetched from a local CSV file by a raw data provider. The locations are represented with symbols, called "markers", whose icon depend on the category of the location and plotted on a map with an object layer defined by The JavaScript API. Finally, we add a tooltip to each marker that displays extra information about the location.

The example is based on a dataset containing rows of cultural institutions provided by the City of Berlin under a Creative Commons by attribution license. We converted the data from Excel to CSV format before using it.

Get a HERE Account

To access Geovisualization, go to https://account.here.com/sign-up and sign up for a HERE account

Get a HERE Plan

When you have an account, register for a 90-day Free Trial plan on the HERE website: https://developer.here.com/plans.

Generate App ID and App Code

On the project page for the newly created plan, click the blue Generate App ID and App Code button under the JavaScript/REST heading to generate the App ID and App Code you will need for Geovisualization.

Connect a Data Source

First download the CSV data source and save it into a folder alongside the HTML and JavaScript files you will create in the next steps.

Visualizing your Data

Next you define the HTML and JavaScript code for the visualization. WHAT DOES IT DO?
Note: For a full guide to visualizing your data, see Creating Visualizations.

Define the HTML Code

Create an index.html file and add the following HTML to set up the JavaScript, CSS and page structure you will need. You will need to add modules for the base here map services and features. Also create a map.js file in the same directory to contain the custom JavaScript code you will add later.

<!DOCTYPE html>
<html lang="en">
<head>
  <title>The Geovisualization Example</title>
  <meta name="viewport" content="initial-scale=1.0, width=device-width" />
  <link rel="stylesheet" type="text/css" href="https://js.cit.api.here.com/v3/3.0/mapsjs-ui.css" />
  <link rel="stylesheet" type="text/css" href="./dist/index.css">
</head>
<body>
  <div class="dl-map"></div>   
    <script type="text/javascript" src="https://js.cit.api.here.com/v3/3.0/mapsjs-core.js"></script>
  <script type="text/javascript" src="https://js.cit.api.here.com/v3/3.0/mapsjs-service.js"></script>
  <script type="text/javascript" src="https://js.cit.api.here.com/v3/3.0/mapsjs-ui.js"></script>
  <script type="text/javascript" src="https://js.cit.api.here.com/v3/3.0/mapsjs-mapevents.js"></script>
  <script type="text/javascript" src="https://js.cit.api.here.com/v3/3.0/mapsjs-clustering.js"></script>
  <script type="text/javascript" src="https://js.cit.datalens.api.here.com/2.6.1/mapsjs-datalens.js"></script>  
  <script type="text/javascript" src="https://d3js.org/d3.v4.min.js"></script>
  <script type="text/javascript" src="./src/ui.js" charset="UTF-8"></script>
  <script type="text/javascript" src="./src/index.js"></script>
</body>
</html>    
      

Define the JavaScript Code

This example will not show all the JavaScript code, only the parts most relevant to using Geovisualization. You can find the full JavaScript code here and if you are new to HERE, we recommend you read the Maps API for JavaScriptdocumentation.

Note: For the full JavaScript API reference, see JavaScript API.

First create an instance of a provider class (H.datalens.RawDataProvider) to define a data file. A provider is an object which works as a database of information for the map. In its constructor, pass the (dataUrl) parameter an URL for a data file, this can be a remote or local URL. The file can be in CSV format and can contain data such as geometries or coordinates. In this example, the file contains locations with coordinates.

let provider = new H.datalens.RawDataProvider({
  dataUrl: './cultural_facilities.csv',
  ...
});

Next, the dataToFeatures method defines how to map the input data to an array of GeoJSON features. In this example it parses the CSV file and assigns appropriate data from each row to the feature :

...
dataToFeatures: (data) => {
  let parsed = helpers.parseCSV(data);
  let features = [];
  let row = null;
  let feature = null;

  for (let i = 1, l = parsed.length; i < l; i++) {
    row = parsed[i];
    feature = {
      'type': 'Feature',
      'geometry': {
        'type': 'Point',
        'coordinates': [Number(row[3]), Number(row[2])]
      },
      'properties': {
        'facility': row[0],
        'address': row[1],
        'SUBahn': row[8],
        'type':  row[11]
      }
    }
    features.push(feature);
  }
  return features;
},
...      
The featuresToRows method defines how a feature is then mapped to each individual row (marker). In this example it matches the geocordinates to the geometry property of the feature, and the supplemental category details to the properties property.
...
featuresToRows: (features) => {
  let rows = [], feature;
  for (let i = 0, l = features.length; i < l; i++) {
    feature = features[i];
    rows.push([{
        lat: feature.geometry.coordinates[1],
        lng: feature.geometry.coordinates[0]
      },
      feature.properties.facility,
      feature.properties.address,
      feature.properties.SUBahn,
      feature.properties.type
    ]);
  }
  return rows;
}
Geovisualization has different layers available depending what you want to draw onto a map. As this example uses markers, it uses an 'object layer' (instantiated with H.datalens.ObjectLayer) that represents your data as points or spatial map objects. The rowToMapObject method defines where each point is drawn on the map, in this example by setting the coordinates to the appropriate array value. The rowToStyle method defines the look of the marker, in this example creating an icon (which are defined in the ui.js file also found here):
rowToMapObject: function (data) {
  let coordinates = data[0];
  return new H.map.Marker(coordinates);
},

rowToStyle: function (data, zoom) {
  if (!venueIcons[data[4]]) { return }
  let icon = H.datalens.ObjectLayer.createIcon(venueIcons[data[4]], {size: 60});
  return { icon };
}

Finally, to render the colored markers, add the layer to the map:

map.addLayer(layer);