Renders

Render a map (keyless, cacheable URL)

Changed on

The keyless twin of POST /v1/renders, for <img> tags, Markdown and no-code tools. Same request object, URL-encoded as JSON in spec. Always the keyless tier (PNG, full attribution, ≤ 1600 px wide) and publicly cacheable for 24 hours (Cache-Control: public, max-age=86400), so repeat loads of an embedded map do not count against the limit. Because the cache key is the URL, a changed spec is a new URL. For dashboards that re-render on fresh data that is exactly what you want.

This endpoint never accepts a key. Sending one returns 400. Use POST with your key instead.

An oversized, missing, or malformed spec is always 400 validation_error (never 413).

https://api.ultimaps.com/v1/renders?spec=%7B%22mapId%22%3A%22united-states%22%2C%22regions%22%3A%7B%22US-CA%22%3A%22%231D4ED8%22%7D%7D
get/v1/renders

Request

  • Base URL: https://api.ultimaps.com
  • URL: https://api.ultimaps.com/v1/renders
  • Auth: none required

Query parameters

specstring required

The render request (see RenderRequest) as URL-encoded JSON. At most 6144 bytes of UTF-8 measured after URL-decoding, so non-ASCII text counts more than one byte per character. Larger specs must use POST. Overflow is 400 validation_error, not 413.

Response

The rendered PNG (or the dry-run report when spec sets dryRun: true). The image carries Content-Disposition: inline; filename="<mapId>.png". The dry-run report does not.

dryRuntrue required
mapIdstring required
legendobject nullable

Exactly the legend the render would draw. Its shape follows the resolved type. groups/steps choropleths and categories return an array of {label, color} (steps labels are the class boundaries, groups labels are ranges). A gradient returns {points: [min, mid|null, max], stops: [hex…]}, the continuous scale's domain and preview colors. With choropleth.noData the No data row is the last item (a gradient adds it as noData: {label, color}). Null for regions-only requests.

Example response

{
  "regionMatching": {
    "corrected": [
      {
        "matchedTo": "US-CA"
      }
    ],
    "unmatched": [
      {
        "suggestions": [
          "Texas (US-TX)"
        ]
      }
    ]
  }
}

Changes

  • b913e49453e5Revision changes
    • info

      added the optional property / to the response with the status

  • b2539061d706Revision changes
    • warning

      added the new label_lists_ignored enum value to the // response property for the response status

    • warning

      added the new labels_overlap enum value to the // response property for the response status

    • warning

      added the new legend_heading_dropped enum value to the // response property for the response status

    • warning

      added the new midpoint_ignored enum value to the // response property for the response status

    • warning

      added the new nodata_low_contrast enum value to the // response property for the response status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status