@jorgenphi/staticmaps v1.9.5

StaticMaps

A Node.js library for creating map images with markers, polylines, polygons and text. This library is a JavaScript implementation of Static Map.

Prerequisites

Image manipulation is based on Sharp. Pre-compiled libvips binaries for sharp are provided for use with Node.js versions 12+ on macOS (x64, ARM64), Linux (x64, ARM64) and Windows (x64, x86) platforms. For other OS or using with Heroku, Docker, AWS Lambda please refer to sharp installation instructions.

Releases

Changelog

Installation

> npm i staticmaps

Getting Started

Initialization

import StaticMaps from 'staticmaps';

const options = {
  width: 600,
  height: 400
};
const map = new StaticMaps(options);

Map options

Methods

addMarker (options)

Adds a marker to the map.

Marker options

Usage example

const marker = {
  img: `${__dirname}/marker.png`, // can also be a URL
  offsetX: 24,
  offsetY: 48,
  width: 48,
  height: 48,
  coord : [13.437524,52.4945528]
};
map.addMarker(marker);

addLine (options)

Adds a polyline to the map.

Polyline options

Usage example

  const polyline = {
    coords: [
      [13.399259,52.482659],
      [13.387849,52.477144],
      [13.40538,52.510632]
    ],
    color: '#0000FFBB',
    width: 3
  };

  map.addLine(polyline);

addPolygon (options)

Adds a polygon to the map. Polygon is the same as a polyline but first and last coordinate are equal.

map.addPolygon(options);

Polygon options

Usage example

  const polygon = {
    coords: [
      [13.399259,52.482659],
      [13.387849,52.477144],
      [13.40538,52.510632],
      [13.399259,52.482659]
    ],
    color: '#0000FFBB',
    width: 3
  };

  map.addPolygon(polygon);

addMultiPolygon (options)

Adds a multipolygon to the map.

map.addMultiPolygon(options);

Multipolygon options

Usage example

  const multipolygon = {
    coords: [
      [
        [-89.9619685, 41.7792032],
        [-89.959505, 41.7792084],
        [-89.9594928, 41.7827904],
        [-89.9631906, 41.7827815],
        [-89.9632678, 41.7821559],
        [-89.9634801, 41.7805341],
        [-89.9635341, 41.780109],
        [-89.9635792, 41.7796834],
        [-89.9636183, 41.7792165],
        [-89.9619685, 41.7792032],
      ],
      [
        [-89.9631647, 41.7809413],
        [-89.9632927, 41.7809487],
        [-89.9631565, 41.781985],
        [-89.9622404, 41.7819137],
        [-89.9623616, 41.780997],
        [-89.963029, 41.7810114],
        [-89.9631647, 41.7809413],
      ],
    ],
    color: '#0000FFBB',
    width: 3
  };

  map.addMultiPolygon(multipolygon);

addCircle (options)

Adds a circle to the map.

map.addPolygon(options);

Polygon options

Usage example

  const circle = {
    coord: [13.01, 51.98],
    radius: 500,
    fill: '#000000',
    width: 0,
  };

  map.addCircle(circle);

addText (options)

Adds text to the map.

map.addText(options)

Text options

Usage example

  const text = {
    coord: [13.437524, 52.4945528],
    text: 'My Text',
    size: 50,
    width: 1,
    fill: '#000000',
    color: '#ffffff',
    font: 'Calibri',
    anchor: 'middle'
  };

  map.addText(text);

render (center, zoom)

Renders the map.

map.render();

Render options

clearCache ()

clear the file based Tile cache.
Can be used, if tileCacheAutoPurge is set to false to clear the cache

map.clearCache();

image.save (fileName, outputOptions)

Saves the image to a file in fileName.

map.image.save('my-staticmap-image.png', { compressionLevel: 9 });

Arguments

The outputOptions replaces the deprectated quality option. For Backwards compatibility quality still works but will be overwritten with outputOptions.quality.

Returns

<Promise>

If callback is undefined it return a Promise. DEPRECATED

image.buffer (mime, outputOptions)

Saves the image to a buffer.

map.image.buffer('image/jpeg', { quality: 75 });

Arguments

The outputOptions replaces the deprectated quality option. For Backwards compatibility quality still works but will be overwritten with outputOptions.quality.

Returns

<Promise>

If callback is undefined it return a Promise. DEPRECATED

Usage Examples

Simple map w/ zoom and center

const zoom = 13;
const center = [13.437524,52.4945528];

await map.render(center, zoom);
await map.image.save('center.png');

Output

Simple map with bounding box

If specifying a bounding box instead of a center, the optimal zoom will be calculated.

const bbox = [
  11.414795,51.835778,  // lng,lat of first point
  11.645164,51.733833   // lng,lat of second point, ...
];

await map.render(bbox);
await map.image.save('bbox.png');

Output

Map with single marker

const marker = {
  img: `${__dirname}/marker.png`, // can also be a URL,
  offsetX: 24,
  offsetY: 48,
  width: 48,
  height: 48,
  coord: [13.437524, 52.4945528],
 };
map.addMarker(marker);
await map.render();
await map.image.save('single-marker.png');

You're free to specify a center as well, otherwise the marker will be centered.

Output

Map with multiple marker

const marker = {
  img: `${__dirname}/marker.png`, // can also be a URL
  offsetX: 24,
  offsetY: 48,
  width: 48,
  height: 48
};

marker.coord = [13.437524,52.4945528];
map.addMarker(marker);
marker.coord = [13.430524,52.4995528];
map.addMarker(marker);
marker.coord = [13.410524,52.5195528];
map.addMarker(marker);

await map.render();
await map.image.save('multiple-marker.png');

Output

Map with polyline

var line = {
  coords: [
    [13.399259,52.482659],
    [13.387849,52.477144],
    [13.40538,52.510632]
  ],
  color: '#0000FFBB',
  width: 3
};

map.addLine(line);
await map.render();
await map.image.save('test/out/polyline.png');

Output

Map with circle

 const circle = {
  coord: [13.01, 51.98],
  radius: 500,
  fill: '#000000',
  width: 0,
};

map.addCircle(circle);
await map.render();
await map.image.save('test/out/099-circle.png');

Output

Blue Marble by NASA with text

const options = {
    width: 1200,
    height: 800,
    tileUrl: 'https://map1.vis.earthdata.nasa.gov/wmts-webmerc/BlueMarble_NextGeneration/default/GoogleMapsCompatible_Level8/{z}/{y}/{x}.jpg',
    zoomRange: {
      max: 8, // NASA server does not support level 9 or higher
    }
  };

  const map = new StaticMaps(options);
  const text = {
    coord: [13.437524, 52.4945528],
    text: 'My Text',
    size: 50,
    width: '1px',
    fill: '#000000',
    color: '#ffffff',
    font: 'Calibri'
  };

  map.addText(text);

  await map.render([13.437524, 52.4945528]);
  await map.image.save('test/out/bluemarbletext.png');

Output

Tile server with subdomains

{s} - subdomain (subdomain), is necessary in order not to fall into the limit for requests to the same domain. Some servers can block your IP if you get tiles from one of subdomains of tile server.

const options = {
    width: 1024,
    height: 1024,
    tileUrl: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
    tileSubdomains: ['a', 'b', 'c'],
};

const map = new StaticMaps(options);

await map.render([13.437524, 52.4945528], 13);
await map.image.save('test/out/subdomains.png');

Mulitple tile layers

{s} - subdomain (subdomain), is necessary in order not to fall into the limit for requests to the same domain. Some servers can block your IP if you get tiles from one of subdomains of tile server.

const options = {
    width: 1024,
    height: 1024,
    tileLayers: [
        {
          tileUrl: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
          tileSubdomains: ['a', 'b', 'c'],
        },
        {
          tileUrl: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
          tileSubdomains: ['a', 'b', 'c'],
        }
    ],
};

const map = new StaticMaps(options);

await map.render([13.437524, 52.4945528], 13);
await map.image.save('test/out/subdomains.png');

Contributers

• Jordi Casadevall Franco
• Joe Beuckman
• Ergashev Adizbek
• Olivier Kamers
• Wesley Flynn
• Thomas Konings
• Gihan S
• Sergey Averyanov
• boxcc
• Maksim Skutin
• Jorgen Phillips