💻 Purpose of the API

The Routeplanner Mapview API renders a route as a static map image. Given an encoded polyline representing a route, it returns a ready-to-display map image in PNG, GIF, or JPEG format.

Use it to:

Display a route visually in an application without requiring a full interactive map
Generate route previews for reports, emails, or print output
Show the result of a routing calculation as a simple image

🤔 How to use?

Base URL

https://api.company.info/routeplanner/mapview/

Authentication

All requests require an API key passed as a request header:

X-API-Key: YOUR_API_KEY

`GET /route`

Returns a static map image showing the route represented by the provided encoded polyline.

Parameters

Parameter	Required	Type	Description
`polyline`	Yes	string	The route to render, encoded as a flexible polyline string

What is an encoded polyline?

A polyline is a series of geographic coordinates that together define a route. Encoding it compresses the coordinate sequence into a compact string that can be passed as a URL parameter.

The Routeplanner Mapview API uses the Flexible Polyline encoding format. A polyline string looks like this:

BGomr7jDi_klJkBmFsEgUgUsjD8BkI8B4I0UknDkD0PwC8LwC0KkDwM-BkI

You typically obtain this polyline from the output of a routing API call, which returns the route geometry in this encoded format.

Example request

curl --request GET \
     --url 'https://api.company.info/routeplanner/mapview/route?polyline=BGomr7jDi_klJkBmFsEgUgUsjD8BkI8B4I0UknDkD0PwC8LwC0KkDwM-BkI' \
     --header 'X-API-Key: YOUR_API_KEY' \
     --output route_map.png

Example response

A successful response returns a binary image file. The format (PNG, GIF, or JPEG) is indicated by the Content-Type header of the response:

Content-Type	Format
`image/png`	PNG image
`image/gif`	GIF image
`image/jpeg`	JPEG image

To use the image in a web application, you can either save it to disk or pipe it directly into an <img> tag via a Blob URL.

⚠️ Possible errors

HTTP Status	When it occurs	What to do
`400 Bad Request`	The `polyline` parameter is missing or contains an invalid encoded polyline string	Verify the polyline is a valid Flexible Polyline encoded string and that the `polyline` parameter is present
`404 Not Found`	The route could not be rendered for the given polyline	Check that the coordinates in the polyline fall within a supported geographic area
`500 Internal Server Error`	Unexpected server-side issue	Retry after a short delay; contact support if it persists

🛠️ Try it yourself!

Test the API directly in our API reference.

🔤 Glossary

Polyline A sequence of geographic coordinate points that together define a path or route on a map.

Flexible Polyline encoding A compact encoding format that compresses a list of latitude/longitude coordinates into a single URL-safe string. It is more efficient than passing raw coordinates and supports additional dimensions such as altitude.

Static map image A pre-rendered, non-interactive image of a map. Unlike interactive map tiles, a static map is a single image file suitable for display in contexts where interactivity is not needed, such as emails, PDFs, or simple previews.

❓ FAQ

Where do I get the polyline from? The encoded polyline is typically returned by a routing API as part of the route geometry. Pass that value directly to this endpoint.

Can I choose the image format? The API returns an image and the format is determined server-side. The Content-Type response header tells you which format was returned (image/png, image/gif, or image/jpeg).

Can I control the map size, zoom level, or style? The current version of the API does not expose parameters for map size, zoom, or styling. The map is automatically framed to fit the provided route.

How do I display the image in a web application? You can fetch the image and display it directly. In a browser context, either save it as a file or create a Blob URL from the response and assign it to an <img> element's src attribute.