Mapsense displays geographic data on a custom map interface that allows for dynamic data filtering. Embedded maps enable these datasets to be shown in third-party sites where users are not necessarily registered with Mapsense but wish to interact with private data. Getting embedded maps running on your website is a simple matter of generating authentication tokens for your users, and including a script in your page.

You must generate an session key to embed a map onto your site. These session keys securely delegate permissions to an embedded iframe pointing at Mapsense. Unlike browser cookies, session tokens are intended to be short-lived, and invalidated as frequently as possible.

Session keys also allow you to control access to your embedded dataset; you can specify which columns and rows will be available in the embedded map with a SQL-like query. A common use case is to generate a unique session key for each external user, limiting the embedded dataset to only data relevant to that user.

To embed a map, you'll need to create at least one of these tokens. You can read more about generating a session on our API documentation.

A simple token (with no special permissions) can be generated as follows:

curl -H "Content-Type: application/json" https://explore.mapsense.co/explore/api/session/generate -d '{"permissions":[{"universe":"YOUR_LAYER_NAME"}]}' --user YOUR_USER:YOUR_PASSWORD

First, add a placeholder wherever you want a map to appear.

<div data-mapsense-session="SESSION_TOKEN" data-mapsense-config="CONFIGURATION">
  <!-- Map appears here -->
</div>

Next, include following script somewhere after the placeholder added above.

<script type="text/javascript" src="https://explore.mapsense.co/explore/embed/scout.js"></script>

The configuration can be copied and pasted directly from the URL in the Mapsense console. Specifically, you'll want to copy the part after the hash "#". A simple example might just include the name of the universe {"universe":"my-universe"}. A more complicated example might include things like custom zoom level and filters.

You can add as many placeholders as you like, and they can each have their own session and configuration. A configuration allows you to set default coloring, zoom, center and filters. Read more about setting these here.