Helpers 
Helpers are a set of functions to facilitate the creation of sources and layers. All the helpers are made available under the helpers object.
Example
maptilersdk.helpers.addPolyline(map, {
// Dataset UUID or URL (relative or absolute)
data: "some-trace.geojson",
});
import { helpers } from "@maptiler/sdk";
helpers.addPolyline(map, {
// Dataset UUID or URL (relative or absolute)
data: "some-trace.geojson",
});
Vector layer helpers
Adding vector layers usually requires creating a source first and then configuring many paint and layout style options. Helper functions simplify this process by combining source and layer creation into a single step.
Vector layer helpers:
Shared logic
Helpers come with a lot of built-in defaults and some fail-proof logic that makes creating vector layers much easier! As a result, a dataset can be displayed in one call, creating both the datasource and the layer(s) in one go!
Depending on the type of feature to add (point, polyline, polygon or heatmap), a different helper function needs to be used, but datasource could contain mixed types of feature and the helper will only display a specific type. Example: we have a geoJSON file that contains both polygons and point and we use it as the data property on the helpers.addPoint(map, {options}), this will only add the points.
In addition to easy styling, helper’s datasource can be:
- a URL to a geoJSON file or its string content
- a URL to a GPX or KML file (only for the polyline helper) or its string content
- a UUID of a MapTiler dataset
Multiple layers
The key design principle of these vector layers helpers is it’s easy to make what you want. Helpers can create multiple layers to represent the symbolization of a layer, if necessary.
Example
To create a road with an outline with the polyline layer helper, you just say if you want an outline and specify its size (or even a zoom dependant size) and everything is handled for you. As a result, the helpers.addPolyline method will return an object with multiple IDs: ID of the top/main layer, ID of the outline layer (could be null) and the ID of the data source. This makes further layer and source manipulation possible.
Without the helpers to create a road with an outline, one must draw two layers: a wider base layer and a narrower top layer, fueled by the same polyline data. This requires ordering the layers properly and computing not the width of the outline, but rather the width of the polyline underneath so that it outgrows the top road layer of the desired number of pixels.
CommonShapeLayerOptions
The vector layer helper also share some I/O logic: each of them can take many options but a subset of them is common across all the helpers:
Type Alias CommonShapeLayerOptions
Polyline layer helper
The polyline helper makes it easy to create vector layers that contain polylines. Whenever it’s possible and it makes sense, we use the same terminology across the different helpers.
API reference
The method helpers.addPolyline is not only compatible with the traditionnal GeoJSON source but also with GPX and KML files and the data option can be a MapTiler dataset UUID and will be resolved automatically.
Minimal usage, with the default line width and a random color (withing a selected list):
import { helpers } from "@maptiler/sdk";
helpers.addPolyline(map, {
// dataset UUID, a URL (relative or absolute)
data: "some-trace.geojson",
});
Examples
Check out the full list of examples.
We can add many options, such a a specific color, a custom width or a dash pattern, this time sourcing the data from MapTiler, using the UUID of a dataset:
import { helpers } from "@maptiler/sdk";
helpers.addPolyline(map, {
data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
lineColor: "#FF6666",
lineWidth: 4,
lineDashArray: "____ _ ",
lineCap: "butt",
});
As you can see, we’ve come up with a fun and easy way to create dash arrays, just use underscores and white spaces and this pattern will repeat!
Adding an outline is also pretty straightforward:
import { helpers } from "@maptiler/sdk";
helpers.addPolyline(map, {
data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
lineColor: "#880000",
outline: true,
});
Endless possibilities, what about a glowing wire?
import { helpers } from "@maptiler/sdk";
helpers.addPolyline(map, {
data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
lineColor: "#fff",
lineWidth: 1,
outline: true,
outlineColor: "#ca57ff",
outlineWidth: 2,
outlineWidth: 10,
outlineBlur: 10,
outlineOpacity: 0.5,
});
View more Polyline layer helper examples.
Polygon layer helper
The polygon helper makes it easy to create vector layers that contain polygons, whether they are multipolygons, holedpolygons or just simple polygons. Whenever it’s possible and it makes sense, we use the same terminology across the different helpers.
API reference
Minimal usage, with a half-transparent and a random color (withing a selected list) polygon of Switzerland, from a local file:
import { helpers } from "@maptiler/sdk";
helpers.addPolygon(map, {
data: "switzerland.geojson",
fillOpacity: 0.5,
});
Examples
Check out the full list of examples.
We can add many options, such a a specific color, a custom width or a pattern, this time sourcing the data from MapTiler, using the UUID of a dataset:
import { helpers } from "@maptiler/sdk";
helpers.addPolygon(map, {
data: "aa203ccf-25ee-4447-bef3-55f90916897a",
pattern: "cheese512.webp",
outline: true,
outlineWidth: 3,
outlineColor: "white",
outlineDashArray: "_ ",
fillOpacity: 0.7,
});
View more Polygon layer helper examples.
Point layer helper
A point visualisation may appear like the simplest of all, but we noticed this is where people get the most creative: cluster, data-drive variable radius, but also scaled with zoom, with or without labels, data-driven colors, etc. Our helper supports all of these and will fill-in with built-in default for what’s missing. Whenever it’s possible and it makes sense, we use the same terminology across the different helpers.
API reference
Here is the simplest example, with a dataset loaded from a local file (if no color is specified, a random color is used and the default radius is ramped over the zoom level):
import { helpers } from "@maptiler/sdk";
helpers.addPoint(map, {
data: "public-schools.geojson",
});
Examples
Check out the full list of examples.
Here is the same dataset, but with point clustering enabled:
import { helpers } from "@maptiler/sdk";
helpers.addPoint(map, {
data: "public-schools.geojson",
cluster: true,
});
On the other hand, if clusters are enabled, the default color is fueled by the color ramp TURBO scaled from 10 to 10000 non-linearly resampled with the method "ease-out-square". The size also varies from minPointradius (default: 10) to maxPointRadius (default: 50):
With the point helper, it’s also possible to adapt the color and the radius based on a property. In the following example, we display a point for each public school, with the scaling factor being the number of students:
import { helpers } from "@maptiler/sdk";
helpers.addPoint(map, {
data: "public-schools.geojson",
property: "students",
pointColor: ColorRampCollection.PORTLAND.scale(200, 2000).resample("ease-out-sqrt"),
pointOpacity: 0.8,
minPointRadius: 6,
maxPointRadius: 30,
showLabel: true,
zoomCompensation: false,
})
Here, the PORTLAND color ramp is going to be used so that schools with 200 students or less will have the colors at the very begining of the color ramp and schools with 2000 or more will have the color defined at the very end. Schools in between will be attributed a colors in a non-linear fashion, following the "ease-out-sqrt" method (read Color ramps section for more info).
View more Point layer helper examples.
Heatmap layer helper
The heatmap layer is a great alternative for visualizing a collection of sparse data, but they can be challenging to use, especially when one has to come up with their own color ramp from scratch. The helper makes this much easier! Whenever it’s possible and it makes sense, we use the same terminology across the different helpers.
API reference
Here is a minimalist example, using the default built-in TURBO color ramp:
import { helpers } from "@maptiler/sdk";
helpers.addHeatmap(map, {
data: "public-schools.geojson",
});
Examples
Check out the full list of examples.
Some visualisations are created with a fixed geographic extent or zoom level in mind, whether it’s a survey at the scale of a single neigbohood, or statitics at country scale. In this case, we want to tailor the color, radius, weight and intensity of the heatmap blobs exactely for this precise settings. In the following example, we disable the zoom compensation to make sure radii and intensity is never zoom-dependant:
import { helpers } from "@maptiler/sdk";
helpers.addHeatmap(map, {
data: "public-schools.geojson",
property: "students",
// radius: how wide are the blobs
radius: [
{propertyValue: 100, value: 15},
{propertyValue: 800, value: 50},
],
// weight: how intense are the blob, as fueled by a property
weight: [
{propertyValue: 100, value: 0.1},
{propertyValue: 800, value: 1},
],
// A custom color ramp, must be used with its default interval of [0, 1]
colorRamp: ColorRampCollection.MAGMA,
zoomCompensation: false,
opacity: 0.6,
// a global factor applied to all the blobs, regardless of the property or zoom
intensity: 1.2,
});
Turning off zoom compensation allows for more accurate adjustments to the visualization at a specific zoom level, but it may not adapt as smoothly when zooming in or out.
View more Heatmap layer helper examples.
Take screenshot helper
The screenshot helper provides a quick and easy solution for capturing the current map view as a PNG image file, making it the most convenient way to save map snapshots.
Warning
Screenshots will not contain DOM elements such as Marker and Popup, since those are not part of the rendering context.
API reference
Here is a minimalist example to get a blob (PNG encoded):
import { Map, helpers } from "@maptiler/sdk";
// ... initialize a Map instance, wait for the "load" or "ready" event ...
// Inside an async function, or with using .then()
const blob = await helpers.takeScreenshot(map);
Examples
Check out the full list of examples.
There are two different ways to create screenshot, corresponding to two very different usecases. Note that screenshots will not contain DOM elements such as Marker and Popup, since those are not part of the rendering context.
Get a blob of a screenshot, PNG encoded
import { Map, helpers } from "@maptiler/sdk";
// ... initialize a Map instance, wait for the "load" or "ready" event ...
// Inside an async function, or with using .then()
const blob = await helpers.takeScreenshot(map);
The returned blob of a PNG image file can be very handy if the goal is to programmatically further manipulate the screenshot, such as sending it to some feedback endpoint with a POST request.
Download a PNG file
import { Map, helpers } from "@maptiler/sdk";
// ... initialize a Map instance, wait for the "load" or "ready" event ...
// No need to be inside an async function, the download will be triggered when the file is ready
maptilersdk.helpers.takeScreenshot(map, {
download: true,
filename: "map_screenshot.png"
});
Getting a file directly is a nice option that can be useful to share some debugging context with colleagues, compare multiple styles, or share your creation on social media.
Note
Keep in mind that MapTiler data are copyrighted and their usage is restricted. This include MapTiler built-in styles and tilesets, among others. In case of doubt, do not hesitate to read our terms or to ask our support team.
Other helpers
Convert GPX and KML to GeoJSON
In the Polyline layer helper section above, we have seen that one can feed the helper directly with a path to a GPX or KML file, that is then converted under the hood client-side into a GeoJSON FeatureCollection object. This conversion feature is also exposed and can be used as such:
import { gpx } from "@maptiler/sdk";
// ... assuming inside an async function
// Fetching the GPX file as a string:
const gpxFilePath = "some_gps_trace.gpx";
const gpxResponse = await fetch(gpxFilePath);
const gpxStr = await gpxResponse.text();
// Converting the GPX payload into a GeoJSON FeatureCollection:
const features = maptilersdk.gpx(gpxStr);
//or
const features = gpx(gpxStr);
And for KML files:
import { kml } from "@maptiler/sdk";
// ... assuming inside an async function
// Fetching the KML file as a string:
const kmlFilePath = "some_gps_trace.kml";
const kmlResponse = await fetch(kmlFilePath);
const kmlStr = await kmlResponse.text();
// Converting the KML payload into a GeoJSON FeatureCollection:
const features = maptilersdk.kml(kmlStr);
//or
const features = kml(kmlStr);