Skip to content

Static Maps API

Welcome to the documentation for the SmartMaps Static Maps REST API. This service allows you to create static maps for use on your website or in mailings. With the interface described here, you can generate static maps in various formats and configurations.

Endpoints

The service offers the following endpoints:

Center-based

https://tiles.smartmaps.cloud/styles/v1/smartmaps/{style}/static/{lon},{lat},{zoom}[/{width}x{height}].{format}

Defines the map section by a coordinate pair (longitude, latitude), a zoom level, and optionally the image dimensions and resolution.

Area-based

https://tiles.smartmaps.cloud/styles/v1/smartmaps/{style}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}

Defines the map section by a surrounding rectangle, specified by the coordinates of the lower left and upper right corners.

Autofit Path

https://tiles.smartmaps.cloud/styles/v1/smartmaps/{style}/static/auto/{width}x{height}[@2x].{format}

Automatically fits the map section to a given path (see query parameters).

Where: - {style} is one of the available map styles (essential, light, dark, grey, accessible, satellite) - {format} is the desired image format (e.g. webp, png, jpg) - @2x is optional and requests a high-resolution image

Authentication

To use the interface, you need an API key provided by SmartMaps. For authentication, the API key is passed as a URL parameter and must always be URL-encoded.

Parameter Description
apiKey API key - received after registration.

Example

Static Map Example Map of Karlsruhe with marker at YellowMap 
<!doctype html>
<html>
    <head>
        <title>Static Map Example</title>
    </head>
    <body>
        <img 
            src="https://tiles.smartmaps.cloud/styles/v1/smartmaps/light/static/8.43,49.02,12/800x300.webp?apiKey=[INSERT API-KEY]" 
            alt="Map of Karlsruhe" />
    </body>
</html>

Map Styles

SmartMaps offers several pre-defined map styles that you can use in your static map requests. Each style provides a different visual appearance for the map. The available styles are:

  • Essential: A balanced, general-purpose map style suitable for most applications.
  • Light: A bright, clean style with light colors, ideal for overlaying additional information.
  • Dark: A sleek, dark-themed map style, perfect for nighttime or low-light contexts.
  • Grey: A monochromatic style using shades of grey, useful for subtle background maps.
  • Accessible: A high-contrast style designed for improved readability and accessibility.
  • Satellite: A high-resolution satellite imagery offering a realistic view of the landscape.

Scale Factors

The Static Maps API supports high-resolution images through the use of scale factors. You can request images with increased resolution by appending a scale factor to the image dimensions. The available scale factors are:

  • @1x (default): Standard resolution
  • @2x: Double resolution
  • @3x: Triple resolution

To use a scale factor, append it to the width and height parameters in your request. For example:

https://tiles.smartmaps.cloud/styles/v1/smartmaps/light/static/8.43,49.02,12/800x600@2x.webp?apiKey=INSERT_API_KEY

This will return an image that is 1600x1200 pixels in size, but with the level of detail of an 800x600 image. This is particularly useful for high-resolution displays or when you need to generate high-quality images for print materials.

Note that higher scale factors will result in larger file sizes and may take longer to generate and download. Also, keep in mind that there might be maximum size limits for the generated images, typically around 4096x4096 pixels. If you need larger images, you may need to contact SmartMaps support for custom arrangements.

When using scale factors, remember to adjust your HTML img tag dimensions accordingly to display the image at the intended size:

<img 
  src="https://tiles.smartmaps.cloud/styles/v1/smartmaps/light/static/8.43,49.02,12/800x600@2x.webp?apiKey=INSERT_API_KEY"
  width="800" 
  height="600" 
  alt="High-resolution map of Karlsruhe" 
/>

This will display a high-resolution image at the original intended size, resulting in sharper details on high-resolution displays.

Features

The following features are available:

  • Map Sizes and Zoom Levels: Customize different map sizes and zoom levels based on any radius.
  • Point Data and Icons: Draw point data and select from different icons.
  • Custom Lines: Draw self-defined lines on the map.