Skip to main content

Try MapillaryJS

MapillaryJS is essentially an npm package that can be installed via Yarn or npm. In this guide we will go through what you need to do to start using MapillaryJS in your web application.

You will learn
  • How to install MapillaryJS
  • How to add MapillaryJS to your website


Client Access Token#

To start using MapillaryJS with data from the Mapillary platform, you need to:

  1. Create a Mapillary account
  2. Sign in to your account
  3. Register an application in the developer dashboard
  4. Get the client access token for your new application

Keep the client access token for your application at hand, you will use it when initializing the MapillaryJS viewer later.

When extending MapillaryJS to provide your own data, no account or access token is needed.


To install MapillaryJS you need to have Yarn or Node.js and npm installed.

Once you have setup the prerequisites, you can try MapillaryJS in your own website.

Add MapillaryJS to a Website#

Using an ES6 Module Bundler#

Install the package.

yarn add mapillary-js

Use a CSS loader or include the CSS file in the <head> of your HTML file.

<link  href=""  rel="stylesheet"/>

Include the following code in your application. You need to replace <your access token> with the client access token for the application you registered before. You also need a valid image ID to initialize the viewer.

If you are developing a TypeScript application you will get code editor intellisense while typing.

import {Viewer, ViewerOptions} from 'mapillary-js';
const container = document.createElement('div'); = '400px'; = '300px';document.body.appendChild(container);
const options: ViewerOptions = {  accessToken: '<your access token>',  container,  imageId: '<your image ID for initializing the viewer>',};const viewer = new Viewer(options);

Using a CDN#

Include the JavaScript and CSS files in the <head> of your HTML file.

<script src=""></script><link  href=""  rel="stylesheet"/>

Add a container to the <body> of your HTML file.

<div id="mly" style="width: 400px; height: 300px;"></div>

The global UMD name for MapillaryJS is mapillary. Include the following script in the <body> of your HTML file.

<script>  var {Viewer} = mapillary;
  var viewer = new Viewer({    accessToken: '<your access token>',    container: 'mly', // the ID of our container defined in the HTML body    imageId: '<your image ID for initializing the viewer>',  });</script>

That's It!#

Congratulations! You have just added MapillaryJS to your project.

You should see something similar to what is shown in the live editor below.


Throughout the documentation the live example editors use the React library and the JSX syntax. This is the first such example that you will see. If you have not used React before, that is no problem, understanding React and JSX is not needed to follow along in the guides.


You can edit the code and get immediate feedback in the Result section.

Live Editor
SyntaxError: Unexpected token (1:8)
1 : return ()


  • Install MapillaryJS with Yarn or npm, or use a CDN
  • Use a CSS loader or include the CSS file in the <head> of your HTML file
  • Import the Viewer class and create a new Viewer instance with your options

Next steps#

Now you are ready to start exploring the guide to main concepts.