Map with multiple geometries | Documentation

Build a URL to create a static map with multiple geometries.

To display multiple geometries on a static mapA static map is a non-interactive map image generated by the ArcGIS Static Maps service that includes a basemap style and optional geometries such as points, polylines, and polygons.Learn more, use the /with-overlay endpoint from the ArcGIS Static Maps serviceThe ArcGIS Static Maps service, also known as Static Maps service, is a location service hosted by Esri that generates non-interactive map images called static maps. The service supports displaying a variety of basemap styles and optional geometries such as points, polylines, and polygons. No client-side mapping API is required.Learn more. Provide an overlay in the request body. The overlay is an array of can include a geometry, symbol, label, and other display properties. Additionally, you can specify the image width and height in pixels, along with the output format (png, jpeg, or webp).

How to display a map with multiple geometries

The typical workflow to display a static map with multiple geometries is:

Map: Define the basemapStyle and map area with center.x and center.y, and zoom or radius in the request body.
Overlay: Define the overlay, which is an array of points, polylines, and/or polygons with their associated symbols and labels in the request body.
Image: Specify the image height and width in pixels, format, and attribution style in the request body.
Request: Send a POST request to the /with-overlay endpoint to generate the static map.

Service URL

Use dark colors for code blocksCopy
https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps

Path parameters

These are required parameters to specify the style to access.

Use dark colors for code blocksCopy
https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/{version}/static-maps/{basemapStyle}/with-overlay

Name	Description	Example
`{version}`	Required: The version of the static maps service.	`v1`
`{basemapStyle}`	Required: The basemap style for the static map.	`arcgis/navigation`, `arcgis/navigation-night`, `arcgis/imagery`, `arcgis/streets-night`, or `arcgis/streets`

Body parameters

Name	Type	Description
`overlay`	`Overlay`	An array of geometries to display on the static map, including point, polyline, and/or polygon. Supports up to 64 geometries.
`symbolDictionary`	`SymbolDictionary`	Dictionary of custom SVG marker symbols keyed by a unique ID. Values must be base64 data URLs referenced via `customSymbolId`.
`image`	`Image`	The image object defines the image `width`, `height`, `format`, `padding` and `attribution` of the static map.
`map`	`Map`	A map view that specifies the center location, visible geographic area of the map, and basemap reference details.

Code examples

Display multiple geometries for incident response

Use the Static Maps service to generate a static map that combines multiple incident geometries. The map uses the ArcGIS Streets basemap style and displays active fires, road closures, and evacuation zones.

Steps

Reference the service.
Set the API key in the Authorization request header using the Bearer authentication scheme.
Define the request body parameters, including the overlay array containing point, polyline, and polygon geometries with their associated symbols and labels.
Send the request to the Static Maps service to generate the static map.

JavaScript
Expand
Use dark colors for code blocksCopy
      fetch(
        `https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/${basemapStyle}/with-overlay`,
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${accessToken}`,
            "Content-Type": "application/json",
            accept: "image/png",
          },
          body: JSON.stringify(requestBody),
        }
      )
        .then((response) => response.blob())
        .then((blob) => {
          const imgUrl = URL.createObjectURL(blob);
          mapImage.src = imgUrl;
        });
Expand

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
curl -X POST "https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/arcgis/streets-night/with-overlay" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "overlay": [
      { "type": "point", "geometry": { "x": -87.5782186, "y": 41.7224694, "spatialReference": { "wkid": 4326 } }, "symbol": { "customSymbolId": "road closure", "scale": 1 } },
      { "type": "point", "geometry": { "x": -87.5887485, "y": 41.730931, "spatialReference": { "wkid": 4326 } }, "symbol": { "customSymbolId": "fire", "scale": 1.5 } },
      { "type": "point", "geometry": { "x": -87.5839622, "y": 41.7274706, "spatialReference": { "wkid": 4326 } }, "symbol": { "customSymbolId": "fire", "scale": 1.5 } },
      { "type": "point", "geometry": { "x": -87.5916801, "y": 41.7222908, "spatialReference": { "wkid": 4326 } }, "symbol": { "customSymbolId": "road closure", "scale": 1 } },
      { "type": "point", "geometry": { "x": -87.585, "y": 41.735, "spatialReference": { "wkid": 4326 } }, "symbol": { "customSymbolId": "road closure", "scale": 1 } },
      {
        "type": "polyline",
        "geometry": { "paths": [[[-87.5917728, 41.7222736], [-87.5781823, 41.7223921]]], "spatialReference": { "wkid": 4326 } },
        "symbol": { "style": "solid", "color": "750505", "width": 5 }
      },

Expand

Run in Postman

Display a point with a custom symbol

Use the Static Maps service to generate a static map with the locations of animal enclosures in San Diego Zoo, California. The map uses the ArcGIS Imagery basemap style and has a custom marker symbol that represents each animal.

Steps

Reference the service.
Set the API key in the Authorization request header using the Bearer authentication scheme.
Define the request body parameters, including the overlay array containing point, polyline, and polygon geometries with their associated symbols and labels.
Send the request to the Static Maps service to generate the static map.

JavaScript
Expand
Use dark colors for code blocksCopy
        const res = await fetch(
          `https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/${basemapStyle}/with-overlay`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${accessToken}`,
              accept: "image/png",
            },
            body: JSON.stringify(body),
          }
        );

        const blob = await res.blob();
        const mapEl = document.getElementById("parkMap");
        mapEl.src = URL.createObjectURL(blob);
        mapEl.style.display = "block";
Expand

REST API

cURL

HTTP

Use dark colors for code blocksCopy
curl -X POST "https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/arcgis/imagery/with-overlay" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "overlay": [
      {
        "type": "point",
        "geometry": {
          "x": -117.1534621,
          "y": 32.7369592,
          "spatialReference": { "wkid": 4326 }
        },
        "symbol": {
          "customSymbolId": "placeIcon",
          "scale": 2
        }
      }
    ],
    "image": {
      "width": 500,
      "height": 250,
      "format": "png"
    },
    "map": {
      "radius": 300,
      "center": {
        "x": -117.1516,
        "y": 32.73525,
        "spatialReference": {
          "wkid": 4326
        }
      }
    },
    "symbolDictionary": {
      "placeIcon": "<BASE64_SVG>"
    }
  }'
Run in Postman

Display a polyline for GPS tracks

Use the Static Maps service to display a route taken during a recent exercise. The route is symbolized with a solid orange line, a custom start symbol, and a custom end symbol. The image is displayed in a fitness app along with details such as distance, duration, total calories burned, and total steps gained.

Steps

Reference the service.
Define the request body parameters, including the overlay array containing point and polyline geometries with their associated symbols and labels.
Set the API key in the Authorization request header using the Bearer authentication scheme.
Send the request to the Static Maps service to generate the static map.

JavaScript
Expand
Use dark colors for code blocksCopy
        const res = await fetch(
          `https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/${basemapStyle}/with-overlay`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${accessToken}`,
              accept: "image/png",
            },
            body: JSON.stringify(requestBody),
          }
        );

        console.log(res);
        const blob = await res.blob();
        routeMap.src = URL.createObjectURL(blob);
        routeMap.style.display = "block";
      }
Expand

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
curl -X POST "https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/arcgis/navigation/with-overlay" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: image/png" \
  -d '{
    "overlay": [
      {
        "type": "polyline",
        "geometry": {
          "paths": [[
            [-111.84901320943004, 40.725307451459514],
            [-111.85038839867565, 40.72512620217646],
            [-111.85102218154537, 40.72537088859197],
            [-111.85260065963597, 40.72470026441834],
            [-111.85292353015451, 40.72397525771017],
            [-111.8519549185989, 40.722606786026645],
            [-111.84930020544651, 40.72128360122053],
            [-111.84776956002533, 40.721437672037354],
            [-111.84788914169884, 40.72150111285826],
            [-111.84534205205264, 40.72076700823226],
            [-111.8449952651994, 40.7211929711617],
            [-111.84549750822823, 40.72147392394242],
            [-111.84699227914739, 40.721609868410575],
            [-111.84662157595942, 40.72372150349648],
            [-111.84559317356705, 40.72528026409853],
            [-111.84767246019886, 40.72533240136366]
          ]],
          "spatialReference": {
            "wkid": 4326
          }
        },
        "symbol": {
          "width": 4,
          "style": "solid",
          "color": "f18c67"
        }
      },
      {
        "type": "point",
        "geometry": {
          "x": -111.84901320943004,
          "y": 40.725307451459514,
          "spatialReference": {
            "wkid": 4326
          }
        },
        "symbol": {
          "customSymbolId": "run",
          "scale": 2
        }
      },
      {
        "type": "point",
        "geometry": {
          "x": -111.84767246019886,
          "y": 40.72533240136366,
          "spatialReference": {
            "wkid": 4326
          }
        },
        "symbol": {
          "customSymbolId": "flag",
          "scale": 1
        }
      }
    ],
    "symbolDictionary": {
      "run": "<BASE64_SVG>",
      "flag": "<BASE64_SVG>"
    },
    "image": {
      "width": 400,
      "height": 200,
      "format": "png",
      "padding": [20]
    },
    "map": {
      "zoom": 14
    }
  }'

Run in Postman

Display a polyline for a routing result

You can use the Static Maps service together with the Geocoding and Routing services to display a route from two points. First, create search inputs with autosuggest to help users select start and destination addresses. Then, geocode the selected addresses to obtain their coordinates and pass them to the Routing service to generate a route. Finally, use the resulting route geometry with the Static Maps service to create a static map that displays the route between the two locations.

Steps

Reference the Static Maps service, Geocoding service, and Routing service endpoints.
Set the API key in the Authorization request header using the Bearer authentication scheme. Your API key needs Geocoding, Routing, and Static Maps services privileges.
Use user input to call /suggest and display address suggestions.
Get the coordinates of the selected location with /findAddressCandidates.
Pass the coordinates of the start and destination locations to /solve to generate a route.
Pass the resulting route geometry to the Static Maps service to create a static map that displays the route between the two locations.

JavaScript
Expand
Use dark colors for code blocksCopy
      async function updateMapRoute(routePaths) {
        const width = Math.max(64, Math.min(mapDiv.clientWidth, 1024));
        const height = Math.max(64, Math.min(mapDiv.clientHeight, 1024));

        const startPoint = routePaths[0];
        const endPoint = routePaths[routePaths.length - 1];

        const body = {
          overlay: [
            {
              type: "polyline",
              geometry: {
                paths: [routePaths],
                spatialReference: {
                  wkid: 4326,
                },
              },
              symbol: {
                style: "solid",
                color: "4285F4",
                width: 4,
              },
            },
            {
              type: "point",
              geometry: {
                x: startPoint[0],
                y: startPoint[1],
                spatialReference: {
                  wkid: 4326,
                },
              },
              symbol: {
                customSymbolId: "start",
                scale: 2.5,
                offsetY: -8,
              },
            },
            {
              type: "point",
              geometry: {
                x: endPoint[0],
                y: endPoint[1],
                spatialReference: {
                  wkid: 4326,
                },
              },
              symbol: {
                customSymbolId: "end",
                scale: 2.5,
                offsetY: -8,
              },
            },
          ],
          image: {
            width,
            height,
            format: "png",
            padding: [20],
          },
          symbolDictionary: {
            start: svgToBase64(
              "<" +
                'svg xmlns="http://www.w3.org/2000/svg" viewBox="0 2 21 29"><path d="M10.5 1.998a5.4 5.4 0 0 0-5.4 5.4c0 2.982 3.9 6.6 5.4 11.6 1.521-4.98 5.4-8.618 5.4-11.6a5.4 5.4 0 0 0-5.4-5.4zm0 7.8a2.3 2.3 0 1 1 0-4.599 2.3 2.3 0 0 1 0 4.599z" fill="#34A853"/><circle cx="10.5" cy="7.4" r="2.3" fill="#ffffff"/></svg>'
            ),
            end: svgToBase64(
              '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 2 21 29"><path d="M10.5 1.998a5.4 5.4 0 0 0-5.4 5.4c0 2.982 3.9 6.6 5.4 11.6 1.521-4.98 5.4-8.618 5.4-11.6a5.4 5.4 0 0 0-5.4-5.4zm0 7.8a2.3 2.3 0 1 1 0-4.599 2.3 2.3 0 0 1 0 4.599z" fill="#EA4335"/><circle cx="10.5" cy="7.4" r="2.3" fill="#ffffff"/></svg>'
            ),
          },
        };

        const res = await fetch(
          `https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/${basemapStyle}/with-overlay`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${accessToken}`,
              accept: "image/png",
            },
            body: JSON.stringify(body),
          }
        );

        const blob = await res.blob();
        const imgUrl = URL.createObjectURL(blob);

        mapDiv.innerHTML = `<img src="${imgUrl}" alt="Route map" />`;
      }
Expand

REST API

cURL

HTTP

Use dark colors for code blocksCopy
curl -X POST "https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/arcgis/navigation-night/with-overlay" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: image/png" \
  -d '{
    "overlay": [
      {
        "type": "polyline",
        "geometry": {
          "paths": [[
            [-122.34053899999998, 47.60855500000008],
            [-122.33999999999997, 47.60796400000004],
            [-122.33966489999995, 47.60759540000004],
            [-122.34020739999994, 47.60736330000003],
            [-122.34016089999994, 47.607312000000036],
            [-122.3393127, 47.60637520000006]
          ]],
          "spatialReference": { "wkid": 4326 }
        },
        "symbol": {
          "style": "solid",
          "width": 4,
          "color": "007ac2"
        }
      },
      {
        "type": "point",
        "geometry": {
          "x": -122.34053899999998,
          "y": 47.60855500000008,
          "spatialReference": { "wkid": 4326 }
        },
        "symbol": {
          "customSymbolId": "start",
          "scale": 2.5
        }
      },
      {
        "type": "point",
        "geometry": {
          "x": -122.3393127,
          "y": 47.60637520000006,
          "spatialReference": { "wkid": 4326 }
        },
        "symbol": {
          "customSymbolId": "end",
          "scale": 2.5
        }
      }
    ],
    "image": {
      "width": 1024,
      "height": 861,
      "format": "png"
    },
    "symbolDictionary": {
      "start": "<BASE64_SVG>",
      "end": "<BASE64_SVG>"
    }
  }'
Run in Postman

Display a polygon for a drive-time area

Use the Static Maps service together with the Geocoding and Routing services to display a 10-minute drive time area from a geocoding result. First, create a search box with autosuggest to help users select an address. Then, geocode the selected address to obtain its coordinates, and pass those coordinates to the Routing service to generate a 10-minute drive time area. Finally, use the Static Maps service to generate a static map that displays the drive time area as a polygon.

Steps

Reference the Static Maps service, Geocoding service, and Routing service endpoints.
Set the API key in the Authorization request header using the Bearer authentication scheme. Your API key needs Geocoding, Routing, and Static Maps services privileges.
Use user input to call /suggest and display address suggestions.
Get the coordinates of the selected location with /findAddressCandidates.
Pass the coordinates to /solveServiceArea to generate a 10-minute drive time area.
Pass the resulting drive-time polygon to the Static Maps service to generate a static map that displays the drive-time area.

JavaScript
Expand
Use dark colors for code blocksCopy
        const requestBody = {
          overlay: [
            {
              type: "polygon",
              geometry: {
                rings: [polygon],
                spatialReference: {
                  wkid: 4326,
                },
              },
              symbol: {
                style: "solid",
                color: "8B6DFF40",
                outline: {
                  style: "solid",
                  color: "5A2DCCFF",
                  width: 1,
                },
              },
            },
            {
              type: "point",
              geometry: {
                x: location.x,
                y: location.y,
                spatialReference: {
                  wkid: 4326,
                },
              },
            },
          ],
          image: {
            width,
            height,
            format: "png",
          },
        };

        const response = await fetch(
          `https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/${basemapStyle}/with-overlay`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${accessToken}`,
              accept: "image/png",
            },
            body: JSON.stringify(requestBody),
          }
        );
Expand

REST API

cURL

HTTP

Use dark colors for code blocksCopy
curl -X POST \
  "https://static-maps-api.arcgis.com/arcgis/rest/services/static-maps-service/v1/static-maps/arcgis/navigation/with-overlay" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "overlay": [
      {
        "type": "polygon",
        "geometry": {
          "rings": [
            <polygon>
          ],
          "spatialReference": {
            "wkid": 4326
          }
        },
        "symbol": {
          "style": "solid",
          "color": "30009f70",
          "outline": {
            "style": "solid",
            "color": "30009fbd",
            "width": 2
          }
        }
      },
      {
        "type": "point",
        "geometry": {
          "x": -117.1956,
          "y": 34.0567,
          "spatialReference": {
            "wkid": 4326
          }
        }
      }
    ],
    "image": {
      "width": 800,
      "height": 600,
      "format": "png"
    }
  }'
Run in Postman

How to display a map with multiple geometries

Service URL

Path parameters

Body parameters

Code examples

Display multiple geometries for incident response

Steps

REST API

Display a point with a custom symbol

Steps

REST API

Display a polyline for GPS tracks

Steps

REST API

Display a polyline for a routing result

Steps

REST API

Display a polygon for a drive-time area

Steps

REST API

Tutorials