Static maps - API Client JS

src/services/staticMaps.ts

MapTiler API Client JS staticMaps functions provides many possibilities for creating static maps images URLs.

StaticMaps functions:

• Centered
• Bounded
• Automatic

MapTiler Cloud provides many possibilities for creating static maps as PNG, JPEG or WebP images. They all offer the possibilities to:

• Choose from one of the MapTiler styles, or your own.
• Add markers with a custom icon (or default icon with custom color).
• Add path or polygon, with a line width, color, and/or fill specified by parameters.

centered

This type of map is centered on a longitude-latitude coordinate and the zoom level must also be provided (from 0: very zoomed out, to 22: very zoomed in).

const imageLink = maptiler.staticMaps.centered(
  // center position (Boston)
  [-71.06080, 42.362114], 

  // zoom level
  12.5, 
  
  // Options
  {
    // Request a hiDPI/Retina image
    hiDPI: true,

    // Output image size
    width: 1000,
    height: 1000,

    // Map style
    style: 'streets-v2',
  });

Parameters

Response

Returns a image URL.

https://api.maptiler.com/maps/basic-v2-light/static/-73.98,40.766999,16/825x350.png?markers=icon%3Ahttps%3A%2F%2Ftinyurl.com%2Fyakrjl3t%7Canchor%3Acenter%7C-73.981137%2C40.767397&key=<YOUR_MAPTILER_API_KEY_HERE>

More examples

Create a map with a custom image marker:

// in an async function, or as a 'thenable':
const result = await maptilerClient.staticMaps.centered(
  [-73.980000,40.766999], 
  16, 
  {
    width: 825, 
    height: 350, 
    style: "basic-v2-light", 
    markers: [-73.981137,40.767397,"red"], 
    markerIcon: "https://tinyurl.com/yakrjl3t", 
    markerAnchor: "center"
  });

Result:

Read more about centered static maps on our official API documentation.

bounded

This type of map requires a bounding box made from two points: the south-west corner and the north-east corner. The zoom level cannot be provided as it is automatically deduced from the size of the bounding box.

const imageLink = maptiler.staticMaps.bounded(
  // The bounding box on Europe
  [
    -24,  // west bound (min x)
    34.5, // south bound (min y)
    32,   // east bound (max x)
    71,   // north bound (max y)
  ],

  // Options
  {
    hiDPI: true,
    width: 2048,
    height: 2048,
    style: 'streets-v2',

    // Extra space that will add around the bounding box, in percentage
    // (0.1 = 10% is actually the dafault)
    padding: 0.1
  });

Since the zoom level cannot be provided, the level of detail is dictated by the size of the output image. Here is an example:

2048 x 2048	1024 x 1024

As you may notice, the bounding box could have different proportions than the output image size. In the following example, we place the same bounding box around Portugal, which has a tall and thin shape. We also add a path to highlight the perimeter of the bounding box. We kept the default padding of 10%. As you can see, the size of the output image has a huge effect on the map display dispite the bounding box being the same.

2048 x 2048	1024 x 2048

Parameters

Response

Returns a image URL.

https://api.maptiler.com/maps/basic-v2-dark/static/12.057495,48.545705,18.880005,51.062113/825x350.png?attribution=bottomleft&path=fill%3Anone%7Cstroke%3A%23FFAA01%7Cwidth%3A2%7C12.138249330010638%2C51.081843238455065%7C12.138249330010638%2C48.53909314617505%7C18.85785478699063%2C48.53909314617505%7C18.85785478699063%2C51.081843238455065%7C12.138249330010638%2C51.081843238455065&key=<YOUR_MAPTILER_API_KEY_HERE>

More examples

Czech republic map in the basic dark style with a bounding box and the attribution in the bottom left corner of the image:

// in an async function, or as a 'thenable':
const result = await maptilerClient.staticMaps.bounded(
  [12.057495,48.545705,18.880005,51.062113], 
  {
    width: 825, 
    height: 350, 
    style: "basic-v2-dark", 
    pathStrokeColor: "#FFAA01", 
    pathWidth: 2, 
    path: [
      [
        12.138249330010638,
        51.081843238455065
      ],
      [
        12.138249330010638,
        48.53909314617505
      ],
      [
        18.85785478699063,
        48.53909314617505
      ],
      [
        18.85785478699063,
        51.081843238455065
      ],
      [
        12.138249330010638,
        51.081843238455065
      ]
    ], 
    attribution: "bottomleft"
});

Result:

Read more about bounded static maps on our official API documentation.

automatic

This type of map fit automatically to whatever you need to place inside: paths or markers.

As we have seen with centered and bounding box maps, providing all the parameters is nice but can be cumbersome for the simplest use cases.

In the following example, we are going to load a cycling track recorded by one of our team members in Montreal, Canada. The track, originally a GPX file, was pushed to MapTiler Data and is now made avalable as GeoJSON:

// Fetching the GeoJSON
const bikeTrack = await maptilerClient.data.get('the-id-of-a-bike-track-in-montreal');

// Extracting the track points with the shape [[lng, lat], [lng, lat], ...]
const trackPoints = bikeTrack.features[0].geometry.coordinates[0]
  .map(p => p.slice(0, 2));

const imageLink = maptiler.staticMaps.automatic({
  // hiDPI/Retina precision
  hiDPI: true,

  // A farily large output image
  width: 2048,
  height: 1024 ,

  // A grey style on which the track will pop!
  style: 'streets-v2-light',

  // Draw a path with the trackpoints
  path: trackPoints,

  // Adding a marker for the starting point, with a custom color (array of shape [lng, lat, color])
  marker: [trackPoints[0][0], trackPoints[0][1], '#0a0'],

  // Showing the track in red
  pathStrokeColor: 'red',
});

And voila! You have a map automatically adjusted to the track.

Parameters

Response

Returns a image URL.

https://api.maptiler.com/maps/basic-v2/static/auto/825x350.png?markers=14.4%2C50.1%2Cred%7C8.6%2C47.4%2Crgba%28118%2C31%2C232%2C1%29%7C2.4%2C48.9%2C%23ffaa00&key=<YOUR_MAPTILER_API_KEY_HERE>

More examples

Map with multiple markers:

// in an async function, or as a 'thenable':
const result = await maptilerClient.staticMaps.automatic({
  width: 825, 
  height: 350, 
  style: "basic-v2", 
  markers: [
    [14.4,50.1,"red"],
    [8.6,47.4,"rgba(118,31,232,1)"],
    [2.4,48.9,"#ffaa00"]
  ]
});

Result:

Read more about Auto-fitted static maps on our official API documentation.

/src/mapstyle.ts

In all the staticMaps functions, the options.style property can be a string or one of the built-in style shorthand. Here is the full list:

• MapStyle.STREETS reference style for navigation and city exploration
  • MapStyle.STREETS.DARK (variant)
  • MapStyle.STREETS.LIGHT (variant)
  • MapStyle.STREETS.PASTEL (variant)
  • MapStyle.STREETS.NIGHT (variant)
• MapStyle.OUTDOOR reference style for adventure
  • MapStyle.OUTDOOR.DARK (variant)
• MapStyle.WINTER reference style for winter adventure
  • MapStyle.WINTER.DARK (variant)
• MapStyle.SATELLITE reference style satellite and airborne imagery (no variants)
• MapStyle.HYBRID reference style satellite and airborne imagery with labels (no variants)
• MapStyle.BASIC reference style for minimalist design and general purpose
  • MapStyle.BASIC.DARK (variant)
  • MapStyle.BASIC.LIGHT (variant)
• MapStyle.BRIGHT reference style for high contrast navigation
  • MapStyle.BRIGHT.DARK (variant)
  • MapStyle.BRIGHT.LIGHT (variant)
  • MapStyle.BRIGHT.PASTEL (variant)
• MapStyle.TOPO reference style for topographic study
  • MapStyle.TOPO.SHINY (variant)
  • MapStyle.TOPO.PASTEL (variant)
  • MapStyle.TOPO.TOPOGRAPHIQUE (variant)
• MapStyle.VOYAGER reference style for stylish yet minimalist maps
  • MapStyle.VOYAGER.DARK (variant)
  • MapStyle.VOYAGER.LIGHT (variant)
  • MapStyle.VOYAGER.VINTAGE (variant)
• MapStyle.TONER reference style for very high contrast stylish maps
  • MapStyle.TONER.BACKGROUND (variant)
  • MapStyle.TONER.LITE (variant)
  • MapStyle.TONER.LINES (variant)
• MapStyle.OPENSTREETMAP (reference style, this one does not have any variants)
• MapStyle.DATAVIZ the perfect style for data visualization, with very little noise
  • MapStyle.DATAVIZ.DARK (variant)
  • MapStyle.DATAVIZ.LIGHT (variant)
• MapStyle.BACKDROP neutral greyscale style with hillshading suitable for colorful terrain-aware visualization
  • MapStyle.BACKDROP.DARK (variant)
  • MapStyle.BACKDROP.LIGHT (variant)