Running examples locally

This tutorial is only applicable for versions from 4.20.0 onward.

Overview of the tutorial

This tutorial shows how to run offline functional examples. We will do the following steps:

Download examples
Prepare your environment
Replace keys placeholders in HTML files
Run simple http-server to display these examples

API keys

To get an API key:

Register/Sign in to TomTom Developer Portal.
Request an evaluation API key to access the service you want to use the SDK with.

Note - It is possible to have a single key(app) for all TomTom services, but you can also choose to have individual keys for the different services.

Step 1. Download offline functional examples

Before you start you need to download the latest version of offline functional examples, which can be found here https://developer.tomtom.com/maps-sdk/maps-sdk-downloads and unpack the archive.

In the containing folder you will find mutiple files and folders:

HTML files contain the examples code
assets folder contain css files and fonts used by the map
css, img and js contain assets needed by the examples (custom CSS, images and JavaScript libraries, which are used in the examples)
sdk is the folder where our SDK lives. Contains glyphs, sprites, styles and images used internally on the map. Also contains the minified version of SDK

Step 2. Install node.js

Download and install the latest LTS version of node.js suitable for your operating system, you can download from here https://nodejs.org/en/download/.

Step 3. Install npm dependencies

After you finish installing node.js, it is time to install dependencies which are used by the examples. Go into the directory where you have extracted the examples. Open the terminal or command line tool and type the following command:

npm install

This will install the necessary dependencies.

Step 4. Prepare config.json for key replacement script

In order for the offline examples to work you need to replace keys in the examples, for that we have a config file - config.json - where you can enter your keys.

Open the config.json file, which is in the main folder with examples. There are several placeholders for your keys, which you need to replace.

{
    "keys": {
        "maps": "<your maps key>",
        "routing": "<your routing key>",
        "search": "<your search key>",
        "traffic": "<your traffic key>",
        "trafficFlow": "<your trafficFlow key>"
    },
    "paths": {
        "basePath": "/sdk"
    }
}

You may notice that there is an additional property named basePath. If you go back to Step 1, there is a description of sdk folder. basePath points to this folder, so if you have moved it you will need to change this property to the correct path, if not, you can leave it as it is.

Step 5. Replace keys placeholders using the provided script

We provide a script which will automatically replace placeholders for keys and base path in all the examples (otherwise you would have to edit each file manually). In order to run this script, open terminal or command line tool in the main directory and type following command:

npm run replaceKeys

If there is no error message on the console, it means that all keys have been replaced successfully.

Step 6. Run HTTP server

In order to run our examples, open the terminal or command line tool and type the following command:

npm run start

This will start a http-server. Most likely it will open at http://localhost:8080, if it doesn’t, there is an output log on the console of http-server:

Running examples locally

You are here