Static maps (beta)

Draw your own lines, points and areas on the street map and receive a PNG image.

map.static Beta call

How to call it

Request schema

Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.

POST /v1/map/static

{
    "type": "object",
    "properties": {
        "center": {
            "type": "array",
            "description": "Required when zoom is present.",
            "items": {
                "type": "number"
            }
        },
        "features": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "features": {
                    "type": "array",
                    "maxItems": 20000,
                    "description": "Required when features is present.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "geometry": {
                                "type": "array"
                            },
                            "properties": {
                                "type": [
                                    "array",
                                    "null"
                                ]
                            },
                            "type": {
                                "type": "string",
                                "enum": [
                                    "Feature"
                                ]
                            }
                        },
                        "required": [
                            "geometry",
                            "type"
                        ]
                    }
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "FeatureCollection"
                    ],
                    "description": "Required when features is present."
                }
            },
            "required": [
                "features"
            ]
        },
        "flavor": {
            "type": [
                "string",
                "null"
            ],
            "enum": [
                "light",
                "white",
                "grayscale",
                "dark",
                "black"
            ]
        },
        "height": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2048
        },
        "language": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 16
        },
        "max_zoom": {
            "type": [
                "number",
                "null"
            ],
            "minimum": 0,
            "maximum": 20
        },
        "padding": {
            "type": [
                "number",
                "null"
            ],
            "minimum": 0
        },
        "scale": {
            "type": [
                "integer",
                "null"
            ],
            "enum": [
                "1",
                "2"
            ]
        },
        "width": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2048
        },
        "zoom": {
            "type": [
                "number",
                "null"
            ],
            "minimum": 0,
            "maximum": 22,
            "description": "Required when center is present."
        }
    },
    "additionalProperties": false,
    "required": [
        "features",
        "height",
        "width"
    ]
}

Request example

{
    "width": 400,
    "height": 300,
    "features": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -73.5673,
                        45.5017
                    ]
                },
                "properties": {
                    "marker-color": "#1e88e5"
                }
            },
            {
                "type": "Feature",
                "geometry": {
                    "type": "LineString",
                    "coordinates": [
                        [
                            -73.5673,
                            45.5017
                        ],
                        [
                            -73.554,
                            45.5088
                        ]
                    ]
                },
                "properties": {
                    "stroke": "#1e88e5"
                }
            }
        ]
    }
}

Response

What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.

POST /v1/map/static

Response schema

{
    "description": "The caller's GeoJSON drawn on the street map as a PNG, returned base64-encoded. Nothing is stored. The example's `image_base64` is shortened.",
    "data": {
        "type": "object",
        "properties": {
            "content_type": {
                "type": "string",
                "enum": [
                    "image/png"
                ]
            },
            "width": {
                "type": "integer",
                "description": "Image width in pixels: `width` × `scale`."
            },
            "height": {
                "type": "integer",
                "description": "Image height in pixels: `height` × `scale`."
            },
            "zoom": {
                "type": "number",
                "description": "The zoom the map was drawn at: the one sent, or the one fitted to the features."
            },
            "image_base64": {
                "type": "string",
                "description": "The PNG, base64-encoded."
            }
        },
        "required": [
            "content_type",
            "image_base64"
        ]
    },
    "meta": {
        "type": "object",
        "properties": {
            "bytes": {
                "type": "integer",
                "description": "Size of the PNG."
            }
        }
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "map.static",
    "billing": {
        "unit": "call",
        "quantity": 1,
        "counted": true
    },
    "data": {
        "content_type": "image/png",
        "width": 400,
        "height": 300,
        "zoom": 14.2,
        "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAEsCAYAAAA..."
    },
    "meta": {
        "bytes": 48213
    }
}

What it costs

One call, whatever its size.

Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.

Errors it can return