Get Map Image

The Get Map Image tool renders a static map image from an ArcGIS MapServer. It is the right tool to reach for whenever the deliverable is a picture of a map—rather than the underlying features or attributes.

Tool Name

get_map_image

Tool Alias

Get Map Image

Objective

Render a static map image from an ArcGIS MapServer service by wrapping the underlying Export Map REST API, with control over extent, image size, format, layer visibility, attribute filtering, and time extent.

Description

get_map_image wraps the ArcGIS REST API Export Map operation. Use it when the deliverable is a picture of a map—PNG or JPG for screen, PDF for print, SVG for vector editing in tools such as Adobe Illustrator. If you need feature attributes or geometry instead, use query_data.

Common workflows

  • Quick visual previews of one or more layers.
  • Reprojecting output to a different coordinate system via imageSR—for example, Web Mercator → Lambert Conformal Conic.
  • Filtering layers with SQL WHERE clauses before rendering.
  • High-DPI exports to PDF for print.
  • Vector exports to SVG for downstream design work.
  • Rotated map frames.

First-class parameters

The most commonly used Export Map options are first-class fields on the input schema:

  • bbox and bboxSR — the geographic extent to render and its spatial reference.
  • layers and layerMode — which layers to draw and how layers is interpreted (show/hide/include/exclude).
  • format — output format (png, jpg, pdf, svg, and so on).
  • dpi — output resolution.
  • width and height — output canvas size in pixels.
  • imageSR — spatial reference for the output image (use to reproject).
  • transparent — whether the background should be transparent.
  • spatialFilter — geometry-based filtering applied to the rendered features.
  • timeExtent — time slice to render for time-aware layers.

Power-user parameters

Less common Export Map options are not first-class fields. Instead, pass them verbatim through the passthrough object, which is merged directly into the underlying REST request. These include:

rotation, mapScale, dynamicLayers, datumTransformations, clipping, gdbVersion, historicMoment, selectionDefinitions, and the various range, parameter, and time-option payloads (layerRangeValues, mapRangeValues, layerParameterValues, layerTimeOptions).

Constraints

Important: MapServer endpoints only

get_map_image works against ArcGIS MapServer services only. URLs that point at FeatureServer, ImageServer, GPServer, or VectorTileServer endpoints will fail. If you are unsure of the endpoint type, run describe_item on the portal item or inspect the URL suffix.

  • Confirm field names with describe_layer before filtering. Before constructing SQL WHERE clauses to filter layers, run describe_layer against each target layer to confirm field names and data types. The wrong field name is the most common reason an export "succeeds" but draws an empty map.
  • Aspect ratio behavior. width and height define the output canvas. If the bbox aspect ratio does not match, the server expands the requested extent to fit; it does not stretch the geometry. Use the extent returned in the response—not the originally requested bbox—for any subsequent spatial calculations.

When to use

  • The user wants a visual rendering of a map—static picture for a screenshot, document, or print job.
  • The agent needs to produce an image for a downstream tool (a slide deck, a PDF report, a vector design file).

When not to use

  • The user wants feature attributes, records, or geometry. Use query_data instead.
  • The target is not a MapServer endpoint (FeatureServer, ImageServer, GPServer, VectorTileServer). Use the appropriate tool for that service type.

Schema

The full JSON Schema definitions for the input parameters accepted by get_map_image and the output payload it returns are provided as separate files alongside this document.

Input schema

The input schema describes the required serviceUrl, bbox, and bboxSR parameters, every first-class option (layers, layerMode, format, dpi, width, height, imageSR, transparent, spatialFilter, timeExtent), and the passthrough object used to forward power-user parameters to the underlying REST request.

Download or view GetMapImageToolInputSchema.json

Output schema

The output schema describes the JSON response returned by the wrapper—including the temporary href to the exported image, the actual width, height, and extent of the rendered image (which may differ from the requested bbox when aspect ratios don't match), and the scale at which the image was rendered.

Download or view GetMapImageToolOutputSchema.json

Sample prompts to test the tool

Send any of the prompts below to your MCP-compatible AI client to verify that get_map_image is working correctly. The prompts are grouped by which input or feature each one exercises—from spatial reference and image format through layer filtering, time extent, and the passthrough escape hatch for power-user parameters.

Spatial reference (bboxSR / imageSR)

  • Export a map of the contiguous U.S. with states and highways, reproject the output to WKID 102004 (USA Contiguous Lambert Conformal Conic).
  • Give me the U.S. states map with bboxSR in WGS84 (4326) but imageSR in Web Mercator (3857).
  • Export the SampleWorldCities World layer with bboxSR=4326 and imageSR=54030 (Robinson).

Image format

  • Export California counties as a PDF for printing.
  • Give me a JPG of Texas with cities—no transparency needed.
  • Export the U.S. Northeast (NY, NJ, CT, MA, RI, VT, NH) as an SVG so I can edit it in Illustrator.
  • Render the USA map as a PNG8 to keep file size small.

Size and DPI

  • Export a print-ready 300 DPI map of the Pacific Northwest at 2400×3000 pixels.
  • Give me a quick 96 DPI thumbnail of the U.S., 600×400 pixels.
  • Export a wide banner of the continental U.S., 4000×1200, at 200 DPI.

Transparency

  • Export only the U.S. state capitals (CITIES where CAPITAL='Y') as a transparent PNG so I can overlay them on my own basemap.
  • Export the U.S. states map with transparent=false—solid background.
  • Export the SampleWorldCities Continent layer as a transparent GIF.

Layer filtering (layers + where)

  • Map all U.S. cities with population over 1,000,000 (POP2000 > 1000000).
  • Show only South Atlantic states (SUB_REGION = 'S Atl') with their counties.
  • Render Texas with only city-class places, excluding towns and CDPs (CLASS = 'city' AND ST = 'TX').
  • From the School Boundaries service, show only school districts in California.
  • Show the U.S. with only the HIGHWAYS layer visible—hide states, cities, counties.

layerMode (filter vs append)

  • filter mode: from SampleWorldCities, show only the Cities layer filtered to capitals.
  • append mode: keep SampleWorldCities' default visibility but additionally filter Cities to CAPITAL='Y'.

Extent variations

  • Export a tight extent around the Bay Area (xmin=-123, ymin=37, xmax=-121.5, ymax=38.5) showing cities and highways.
  • Export the full continental U.S. extent (-125, 24, -66, 50) at 1600×900.
  • Export a global extent (-180, -90, 180, 90) of the SampleWorldCities World layer.

Spatial filter

  • Export U.S. cities within California's polygon using a spatialFilter with esriSpatialRelWithin.
  • Show schools that intersect a bounding box around Los Angeles County.

Time extent

  • Try a timeExtent from 2000-01-01 to 2010-01-01 on the USA service.

Passthrough (advanced)

  • Export California rotated 45° clockwise (use passthrough.rotation).
  • Force a fixed mapScale of 1:5,000,000 when exporting the Midwest.
  • Clip the U.S. export to a custom polygon around the Four Corners region using passthrough.clipping.
  • Use dynamicLayers in passthrough to re-symbolize the STATES layer with a custom renderer.

Combined and stress tests

  • Export a 4096×4096 PNG32 at 300 DPI of the U.S. with states + highways + cities over 500K population, reprojected to WKID 102004, transparent background.
  • Export the smallest possible map: 1×1 pixel, JPG, 1 DPI, full U.S. extent.