Web Service Endpoint

Create a Maps Web Snapshot

Generate a map image with characteristics you provide in the query parameters and sign using your private key.

URL

GET https://snapshot.apple-mapkit.com/api/v1/snapshot

Query Parameters

teamId
string
(Required)

Your Apple Developer Team ID. For more information, see Creating a Maps Identifier and a Private Key.

keyId
string
(Required)

Your MapKit JS Key ID. For more information, see Creating a Maps Identifier and a Private Key.

signature
string
(Required)

A Base64 URL-encoded signature that signs the request path and query parameters. The signature must be the last parameter in the request URL; otherwise, the request will return status code 401 Unauthorized. See Generating a URL and Signature to Create a Maps Web Snapshot.

center
string
(Required)

The center of the map. You can specify center as coordinates or as an address. Provide coordinates as a string with latitude and longitude separated by a comma, such as:

center="37.78,-122.42"

If center is specified as coordinates, the latitude must be in the range (-90, 90) and longitude must be in the range (-180, 180).

An address that can be geocoded is also a valid value for the center parameter, such as:

center="1 Apple Park Way in Cupertino, California"

z
float

The zoom level of the map. When both z and spn are provided, spn takes precedence over z.

spn
string

A comma-separated coordinate span that indicates the amount of the map to display around the maps center. The latitude must be in the range of (0, 90) , and the longitude must be in the range (0, 180). The latitude and longitude delta parameters must be positive numbers; negative numbers are treated as 0.

When both z and spn are provided, spn takes precedence over z.

size
string

The size of the image in pixels. Specify the size as width and height integers separated by the character x. For example, 640x480 creates an image that is 640 pixels wide and 480 pixels tall.

The width and height must be within the range of [50, 640].

scale
int32

The pixel density of the image. scale=2 returns an image intended for Retina displays. Setting scale to values greater than 1 increases the number of pixels in the generated image.

t
string

The map type.

colorScheme
string

The color scheme of the map. The dark color scheme only applies to the standard and mutedStandard map types.

poi
boolean

A Boolean value indicating whether points of interest are shown on the map. To hide points of interest, set poi=0.

lang
string

The language to be used for labels on the map, Supported values are in locale IDs, such as en-GB or es-MX.

annotations

Annotations to be displayed on the map, specified as an array of JSON Annotation objects. Annotations are layered on top of the map in the order specified in the request.

overlays

An array of overlays to be displayed on the map, specified as an array of JSON Overlay objects.

referer
string

The referer string value to match against the request’s "Referer" header value. Requests that don't match the referer parameter will fail with HTTP status code 401 Unauthorized. Setting a referer restriction via the referer parameter is recommended.

expires
int64

The time in seconds from epoch at which this request will expire. Expired requests fail with HTTP status code 401 Unauthorized. Setting an expiration via the expires parameter is recommended.

Response Codes

200 OK
binary
OK

The request was successful and a map image was returned as image/png.

400 Bad Request
Bad Request

The request is invalid and cannot be accepted.

401 Unauthorized
Unauthorized

This request contains invalid authorization credentials.

413 Request Entity Too Large
Request Entity Too Large

The request URL is too long. The URL for this request exceeds the maximum number of characters allowed.

429

The request cannot be accepted because you have exceeded the rate limit for your API key. You will need to wait and try the request again.

500 Internal Server Error
Internal Server Error

The request failed. This may be due to a temporary outage. Check the Apple Developer System Status Page for up to date information on the Web Map Snapshot API.

Discussion

Use the Snapshot URL query parameters to define characteristics of the map image such as dimensions, language, color scheme, and more. To avoid accesses that count toward your service limit, embed the rendered image instead of linking to it.

Every Snapshot URL request must be signed and include the signature as the final parameter. See Generating a URL and Signature to Create a Maps Web Snapshot for details and example code.

See Also

Essentials

Generating a URL and Signature to Create a Maps Web Snapshot

Create a Snapshot URL and generate a signature to validate the request.

object Annotation

An object for a Snapshot URL that describes annotation characteristics.

Beta
object Overlay

A JSON object for a Snapshot URL that describes polyline overlay characteristics, including points for the overlay and styles such as width, color, and dash pattern.

Beta

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software