Printmaps provides JSON-API-compatible service calls for the basic use of this web service. Over this, any client (program, web application, curl tool, ...) can use the Printmaps services. The following explanations describe the use of the API and are intended for application developers.

If, on the other hand, interactive maps are to be generated, we recommend using the Printmaps client. In addition to the elementary commands, the Printmaps client provides a variety of auxiliary functions.

Document

Type Description
Version beta2
Date 2018/12/03
URL http://printmaps-osm.de:8282/api/beta2/maps/

API attributes

Attribute Subattribute Required Data type Description
File format yes string data format of map
Scale yes int scale of map
PrintWidth yes float width of map (millimeter)
PrintHeight yes float hight of map (millimeter)
Latitude yes float latitude of map center point (decimal degrees)
Longitude yes float longitude of map center point (decimal degrees)
Style yes string design (style) of map
Projection yes int map projection (EPSG number)
HideLayers no string list of map layers to hide
UserObjects no struct user data or items (repetitive structure)
Style - string design (style) of user data
SRS - string spatial reference system for user data
Type - string type of preprocessor for user data
File - string file with user data
Layer - string data layer (within user data) to extract
'or'
Style - string design (style) of user element
WellKnownText - string wkt definition of user element
UserFiles no string list of uploaded user files (read-only attribute)

API calls

This service provides the following services:

Map Action Description
Step 1 POST (create resource) define the order data
Step 2 POST (create resource) create an order
Step 3 GET (fetch resource) request the order status
Step 4 GET (fetch resource) download the created map
optional PATCH (update resource) update the order data
optional DELETE (delete resource) delete all data of a map order
optional GET (fetch resource) request the map data
optional GET (fetch capabilities) request the service capabilities
optional GET (fetch capabilities) request the available map data
optional POST (send form data) upload user data

The description of the individual service functions is made by means of curl calls (embedded in bash scripts).

Define the order data (step 1)

Type Description
Call-URL /api/beta2/maps/metadata
Request-Type POST (create resource)
Response, Success 201 Created
Response, Failure 400 Bad Request

Request:

#!/bin/bash
#
# create map meta data (new map) 

postdata=$(cat <<EOF
{
    "Data": {
        "Type": "maps",
        "ID": "",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 5000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 40.751,
            "Longitude": -73.9515,
            "Style": "osm-carto",
            "Projection": "3857",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserObjects": [
                {
                    "Style": "<PolygonSymbolizer fill='white' fill-opacity='1.0' />",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0))"
                },
                {
                    "Style": "<LineSymbolizer stroke='dimgray' stroke-width='1.0' stroke-linecap='square' />",
                    "WellKnownText": "LINESTRING(20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0)"
                },
                {
                    "Style": "<LineSymbolizer stroke='dimgray' stroke-width='1.5' stroke-linecap='square' />",
                    "WellKnownText": "MULTILINESTRING((5.0 0.0, 0.0 0.0, 0.0 5.0), (5.0 600.0, 0.0 600.0, 0.0 595.0), (595.0 600.0, 600.0 600.0, 600.0 595.0), (595.0 0.0, 600.0 0.0, 600.0 5.0))"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-2' size='80' fill='dimgray' opacity='0.6' allow-overlap='true'>'New York'</TextSymbolizer>",
                    "WellKnownText": "POINT(90.0 560.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-0' size='12' fill='dimgray' orientation='90' allow-overlap='true'>'© OpenStreetMap contributors'</TextSymbolizer>",
                    "WellKnownText": "POINT(11 300.0)"
                }
            ]
        }
    }
}
EOF
)

echo "postdata =\n$postdata"

set -o verbose

curl \
--silent \
--include \
--header "Content-Type: application/vnd.api+json; charset=utf-8" \
--header "Accept: application/vnd.api+json; charset=utf-8" \
--data "$postdata" \
http://printmaps-osm.de:8282/api/beta2/maps/metadata

Response:

The response returns a unique map ID. This ID identifies the map unambiguously and has to be attached to all other service calls.

HTTP/1.1 201 Created
Content-Length: 2009
Content-Type: application/vnd.api+json; charset=utf-8
Date: Mon, 03 Dec 2018 10:05:58 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "33b1bb90-9759-4b82-8e91-b2942744f2f3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 5000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 40.751,
            "Longitude": -73.9515,
            "Style": "osm-carto",
            "Projection": "3857",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserObjects": [
                {
                    "Style": "\u003cPolygonSymbolizer fill='white' fill-opacity='1.0' /\u003e",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0))"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='dimgray' stroke-width='1.0' stroke-linecap='square' /\u003e",
                    "WellKnownText": "LINESTRING(20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0)"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='dimgray' stroke-width='1.5' stroke-linecap='square' /\u003e",
                    "WellKnownText": "MULTILINESTRING((5.0 0.0, 0.0 0.0, 0.0 5.0), (5.0 600.0, 0.0 600.0, 0.0 595.0), (595.0 600.0, 600.0 600.0, 600.0 595.0), (595.0 0.0, 600.0 0.0, 600.0 5.0))"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='80' fill='dimgray' opacity='0.6' allow-overlap='true'\u003e'New York'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(90.0 560.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-0' size='12' fill='dimgray' orientation='90' allow-overlap='true'\u003e'© OpenStreetMap contributors'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(11 300.0)"
                }
            ]
        }
    }
}

Create an order (step 2)

Type Description
Call-URL /api/beta2/maps/mapfile
Request-Type POST (create resource)
Response, Success 202 Accepted
Response, Failure 400 Bad Request

Request:

#!/bin/bash
#
# order map (request map build)

postdata=$(cat <<EOF
{
    "Data": {
        "Type": "maps",
        "ID": "33b1bb90-9759-4b82-8e91-b2942744f2f3"
    }
}
EOF
)

echo "postdata =\n$postdata"

set -o verbose

curl \
--silent \
--include \
--header "Content-Type: application/vnd.api+json; charset=utf-8" \
--header "Accept: application/vnd.api+json; charset=utf-8" \
--data "$postdata" \
http://printmaps-osm.de:8282/api/beta2/maps/mapfile

Response:

With the status code "202 Accepted", the service signals that the job is accepted and placed in the building queue. The current status of the build process can be determined by the client using an appropriate request.

HTTP/1.1 202 Accepted
Content-Length: 2009
Content-Type: application/vnd.api+json; charset=utf-8
Date: Mon, 03 Dec 2018 10:06:35 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "33b1bb90-9759-4b82-8e91-b2942744f2f3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 5000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 40.751,
            "Longitude": -73.9515,
            "Style": "osm-carto",
            "Projection": "3857",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserObjects": [
                {
                    "Style": "\u003cPolygonSymbolizer fill='white' fill-opacity='1.0' /\u003e",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0))"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='dimgray' stroke-width='1.0' stroke-linecap='square' /\u003e",
                    "WellKnownText": "LINESTRING(20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0)"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='dimgray' stroke-width='1.5' stroke-linecap='square' /\u003e",
                    "WellKnownText": "MULTILINESTRING((5.0 0.0, 0.0 0.0, 0.0 5.0), (5.0 600.0, 0.0 600.0, 0.0 595.0), (595.0 600.0, 600.0 600.0, 600.0 595.0), (595.0 0.0, 600.0 0.0, 600.0 5.0))"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='80' fill='dimgray' opacity='0.6' allow-overlap='true'\u003e'New York'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(90.0 560.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-0' size='12' fill='dimgray' orientation='90' allow-overlap='true'\u003e'© OpenStreetMap contributors'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(11 300.0)"
                }
            ]
        }
    }
}

Request the order status (step 3)

Type Description
Call-URL /api/beta2/maps/mapstate/id
Request-Type GET (fetch resource)
Response, Success 200 OK
Response, Failure 400 Bad Request

Request:

#!/bin/bash
#
# fetch map state

set -o verbose

curl \
--silent \
--include \
--header "Accept: application/vnd.api+json; charset=utf-8" \
http://printmaps-osm.de:8282/api/beta2/maps/mapstate/33b1bb90-9759-4b82-8e91-b2942744f2f3

Response:

The service documents the start of the build process in the field "mapBuildStarted". When the process is complete, the mapBuildCompleted field is updated. The fields "mapBuildSuccessful" and "mapBuildMessage" indicate the success / failure of the build process. The field "mapBuildSuccessful" can have the values "no" or "yes". The values in the fields "mapBuildBox *" describe technical properties and can be used for georeferencing the map.

HTTP/1.1 200 OK
Content-Length: 1125
Content-Type: application/vnd.api+json; charset=utf-8
Date: Mon, 03 Dec 2018 10:08:13 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "33b1bb90-9759-4b82-8e91-b2942744f2f3",
        "Attributes": {
            "MapMetadataWritten": "2018-12-03T11:05:58+01:00",
            "MapOrderSubmitted": "2018-12-03T11:06:35+01:00",
            "MapBuildStarted": "2018-12-03T11:06:37+01:00",
            "MapBuildCompleted": "2018-12-03T11:06:46+01:00",
            "MapBuildSuccessful": "yes",
            "MapBuildMessage": "map build successful",
            "MapBuildBoxMillimeter": {
                "Width": 600,
                "Height": 600
            },
            "MapBuildBoxPixel": {
                "Width": 7087,
                "Height": 7087
            },
            "MapBuildBoxProjection": {
                "XMin": -8234223.1773,
                "YMin": 4973703.45209,
                "XMax": -8230263.4695,
                "YMax": 4977663.15989
            },
            "MapBuildBoxWGS84": {
                "LonMin": -73.9692853302,
                "LatMin": 40.7375252942,
                "LonMax": -73.9337146698,
                "LatMax": 40.7644719757
            }
    }
}
}

Download the created map (step 4)

Type Description
Call-URL /api/beta2/maps/mapfile/id
Request-Type GET (fetch resource)
Response, Success 200 OK
Response, Failure 400 Bad Request

Note: A very simple way to download the created map is to enter the map-specific URL in a web browser.

Request:

#!/bin/bash
#
# download map (zip)

set -o verbose  #echo on

curl \
--header "Accept: application/vnd.api+json; charset=utf-8" \
--dump-header "response-header.txt" \
--output "printmap.zip" \
http://printmaps-osm.de:8282/api/beta2/maps/mapfile/33b1bb90-9759-4b82-8e91-b2942744f2f3

set +o verbose # echo off from bash script
echo

cat 'response-header.txt'

Response (symbolic representation):

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 16596102
Content-Type: application/zip
Last-Modified: Mon, 03 Dec 2018 10:06:46 GMT
Date: Mon, 03 Dec 2018 14:36:09 GMT

... the service sends the map to the client ...

Service response in case of failures

A negative service response can have the following characteristics:

With the status code "400 Bad Request" the service signals a technical error and responds with a detailed error list. The "500 Internal Server Error" status code signals an unexpected error on the service side. In this case, a text message describes the type of error.

Request (invalid):

#!/bin/bash
#
# create map meta data (new map) 

postdata=$(cat <<EOF
{
    "Data": {
        "Type": "maps",
        "ID": "",
        "Attributes": {
            "Fileformat": "jpeg",
            "Scale": 5000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 40.751,
            "Longitude": -773.9515,
            "Style": "osm-cartago",
            "Projection": "3857",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserObjects": [
                {
                    "Style": "<PolygonSymbolizer fill='white' fill-opacity='1.0' />",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0))"
                },
                {
                    "Style": "<LineSymbolizer stroke='dimgray' stroke-width='1.0' stroke-linecap='square' />",
                    "WellKnownText": "LINESTRING(20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0)"
                },
                {
                    "Style": "<LineSymbolizer stroke='dimgray' stroke-width='1.5' stroke-linecap='square' />",
                    "WellKnownText": "MULTILINESTRING((5.0 0.0, 0.0 0.0, 0.0 5.0), (5.0 600.0, 0.0 600.0, 0.0 595.0), (595.0 600.0, 600.0 600.0, 600.0 595.0), (595.0 0.0, 600.0 0.0, 600.0 5.0))"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-2' size='80' fill='dimgray' opacity='0.6' allow-overlap='true'>'New York'</TextSymbolizer>",
                    "WellKnownText": "POINT(90.0 560.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-0' size='12' fill='dimgray' orientation='90' allow-overlap='true'>'© OpenStreetMap contributors'</TextSymbolizer>",
                    "WellKnownText": "POINT(11 300.0)"
                }
            ]
        }
    }
}
EOF
)

echo "postdata =\n$postdata"

set -o verbose

curl \
--silent \
--include \
--header "Content-Type: application/vnd.api+json; charset=utf-8" \
--header "Accept: application/vnd.api+json; charset=utf-8" \
--data "$postdata" \
http://printmaps-osm.de:8282/api/beta2/maps/metadata

Response:

HTTP/1.1 400 Bad Request
Content-Length: 1036
Content-Type: application/vnd.api+json; charset=utf-8
Date: Mon, 03 Dec 2018 14:41:55 GMT

{
    "Errors": [
        {
            "ID": "",
            "Status": "422 Unprocessable Entity",
            "Code": "3008",
            "Source": {
                "Pointer": "data.attributes.style"
            },
            "Title": "invalid attribute style",
            "Detail": "valid values: osm-carto, osm-carto-mono, osm-carto-ele20, schwarzplan, schwarzplan+, raster10"
        },
        {
            "ID": "",
            "Status": "422 Unprocessable Entity",
            "Code": "3002",
            "Source": {
                "Pointer": "data.attributes.fileformat"
            },
            "Title": "invalid attribute fileformat",
            "Detail": "valid values: png"
        },
        {
            "ID": "",
            "Status": "422 Unprocessable Entity",
            "Code": "3007",
            "Source": {
                "Pointer": "data.attributes.longitude"
            },
            "Title": "invalid attribute longitude",
            "Detail": "valid values: -180.00 ... 180.00"
        }
    ]
}

Update the order data

Type Description
Call-URL /api/beta2/maps/metadata
Request-Type PATCH (update resource)
Response, Success 200 OK
Response, Failure 400 Bad Request

The data stored on the service side can be updated at any time. It is always the complete record with all elements to update.

Request:

#!/bin/bash
#
# update map meta data

postdata=$(cat <<EOF
{
    "Data": {
        "Type": "maps",
        "ID": "33b1bb90-9759-4b82-8e91-b2942744f2f3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 5000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 40.751,
            "Longitude": -73.9515,
            "Style": "osm-carto",
            "Projection": "3857",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserObjects": [
                {
                    "Style": "<PolygonSymbolizer fill='white' fill-opacity='1.0' />",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0))"
                },
                {
                    "Style": "<LineSymbolizer stroke='firebrick' stroke-width='1.0' stroke-linecap='square' />",
                    "WellKnownText": "LINESTRING(20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0)"
                },
                {
                    "Style": "<LineSymbolizer stroke='firebrick' stroke-width='1.5' stroke-linecap='square' />",
                    "WellKnownText": "MULTILINESTRING((5.0 0.0, 0.0 0.0, 0.0 5.0), (5.0 600.0, 0.0 600.0, 0.0 595.0), (595.0 600.0, 600.0 600.0, 600.0 595.0), (595.0 0.0, 600.0 0.0, 600.0 5.0))"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-2' size='80' fill='firebrick' opacity='0.6' allow-overlap='true'>'New York'</TextSymbolizer>",
                    "WellKnownText": "POINT(90.0 560.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-0' size='12' fill='firebrick' orientation='90' allow-overlap='true'>'© OpenStreetMap contributors'</TextSymbolizer>",
                    "WellKnownText": "POINT(11 300.0)"
                }
            ]
        }
    }
}
EOF
)

echo "postdata =\n$postdata"

set -o verbose

curl \
--silent \
--include \
--header "Content-Type: application/vnd.api+json; charset=utf-8" \
--header "Accept: application/vnd.api+json; charset=utf-8" \
--data "$postdata" \
--request PATCH \
http://printmaps-osm.de:8282/api/beta2/maps/metadata

Response:

The service signals the successful update by the status "200 OK".

HTTP/1.1 200 OK
Content-Length: 2017
Content-Type: application/vnd.api+json; charset=utf-8
Date: Mon, 03 Dec 2018 14:49:57 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "33b1bb90-9759-4b82-8e91-b2942744f2f3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 5000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 40.751,
            "Longitude": -73.9515,
            "Style": "osm-carto",
            "Projection": "3857",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserObjects": [
                {
                    "Style": "\u003cPolygonSymbolizer fill='white' fill-opacity='1.0' /\u003e",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0))"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='firebrick' stroke-width='1.0' stroke-linecap='square' /\u003e",
                    "WellKnownText": "LINESTRING(20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0)"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='firebrick' stroke-width='1.5' stroke-linecap='square' /\u003e",
                    "WellKnownText": "MULTILINESTRING((5.0 0.0, 0.0 0.0, 0.0 5.0), (5.0 600.0, 0.0 600.0, 0.0 595.0), (595.0 600.0, 600.0 600.0, 600.0 595.0), (595.0 0.0, 600.0 0.0, 600.0 5.0))"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='80' fill='firebrick' opacity='0.6' allow-overlap='true'\u003e'New York'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(90.0 560.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-0' size='12' fill='firebrick' orientation='90' allow-overlap='true'\u003e'© OpenStreetMap contributors'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(11 300.0)"
                }
            ]
        }
    }
}

Delete all data of a map order

Type Description
Call-URL /api/beta2/maps/id
Request-Type DELETE (delete resource)
Response, Success 204 No Content
Response, Failure 400 Bad Request

The service saves the data of a map (order data, order status, map, user files) under the map ID. The client can request the deletion of all data.

Request:

#!/bin/bash
#
# delete map (all artifacts)

set -o verbose

curl \
--silent \
--include \
--header "Accept: application/vnd.api+json; charset=utf-8" \
--request DELETE \
http://printmaps-osm.de:8282/api/beta2/maps/33b1bb90-9759-4b82-8e91-b2942744f2f3

Response:

The service signals the successful deletion of the data by the status code "204 No Content".

HTTP/1.1 204 No Content
Date: Mon, 03 Dec 2018 14:54:24 GMT

Request the map data

Type Description
Call-URL /api/beta2/maps/metadata/id
Request-Type GET (fetch resource)
Response, Success 200 OK
Response, Failure 400 Bad Request

Request:

#!/bin/bash
#
# fetch map meta data

set -o verbose

curl \
--silent \
--include \
--header "Accept: application/vnd.api+json; charset=utf-8" \
http://printmaps-osm.de:8282/api/beta2/maps/metadata/ee0eb16b-abcb-4e38-aa44-3d276ea53584

Response:

HTTP/1.1 200 OK
HTTP/1.1 200 OK
Content-Length: 2009
Content-Type: application/vnd.api+json; charset=utf-8
Date: Mon, 03 Dec 2018 14:57:40 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "ee0eb16b-abcb-4e38-aa44-3d276ea53584",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 5000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 40.751,
            "Longitude": -73.9515,
            "Style": "osm-carto",
            "Projection": "3857",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserObjects": [
                {
                    "Style": "\u003cPolygonSymbolizer fill='white' fill-opacity='1.0' /\u003e",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0))"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='dimgray' stroke-width='1.0' stroke-linecap='square' /\u003e",
                    "WellKnownText": "LINESTRING(20.0 20.0, 20.0 580.0, 580.0 580.0, 580.0 20.0, 20.0 20.0)"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='dimgray' stroke-width='1.5' stroke-linecap='square' /\u003e",
                    "WellKnownText": "MULTILINESTRING((5.0 0.0, 0.0 0.0, 0.0 5.0), (5.0 600.0, 0.0 600.0, 0.0 595.0), (595.0 600.0, 600.0 600.0, 600.0 595.0), (595.0 0.0, 600.0 0.0, 600.0 5.0))"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='80' fill='dimgray' opacity='0.6' allow-overlap='true'\u003e'New York'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(90.0 560.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-0' size='12' fill='dimgray' orientation='90' allow-overlap='true'\u003e'© OpenStreetMap contributors'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(11 300.0)"
                }
            ]
        }
    }
}

Request the service capabilities

Type Description
Call-URL /api/beta2/maps/capabilities/service
Request-Type GET (fetch capabilities)
Response, Success 200 OK

The properties of the service can be queried in order to control the data entry (control elements) and a data check on the client side. Individual properties can change, so the following output is only an example. The client should re-discover the properties at the beginning of each session.

Request:

#!/bin/bash
#
# fetch service capabilities

set -o verbose

curl \
--silent \
--include \
--header "Accept: application/vnd.api+json; charset=utf-8" \
http://printmaps-osm.de:8282/api/beta2/maps/capabilities/service

Response:

HTTP/1.1 200 OK
Content-Length: 7134
Content-Type: application/json; charset=utf-8
Date: Mon, 03 Dec 2018 14:59:56 GMT

{
    "ConfigMapdata": {
        "Description": "world",
        "MinLatitude": -90,
        "MaxLatitude": 90,
        "MinLongitude": -180,
        "MaxLongitude": 180
    },
    "ConfigMapformats": [
        {
            "Type": "png",
            "MinPrintWidth": 5,
            "MaxPrintWidth": 3000,
            "MinPrintHeigth": 5,
            "MaxPrintHeigth": 2500
        }
    ],
    "ConfigMapscale": {
        "MinScale": 100,
        "MaxScale": 250000
    },
    "ConfigStyles": [
        {
            "Name": "osm-carto",
            "ShortDescription": "OpenStreetMap Carto Style",
            "LongDescription": "The 'OpenStreetMap Carto' map design is the standard style rendered at the OSM webpage.",
            "Release": "4.15.0",
            "Date": "2018/09/21",
            "Link": "https://github.com/gravitystorm/openstreetmap-carto",
            "Copyright": "© OpenStreetMap contributors",
            "Layers": "world,coast-poly,necountries,landcover-low-zoom,landcover,landcover-line,water-lines-casing,water-lines-low-zoom,icesheet-poly,water-areas,landcover-area-symbols,icesheet-outlines,springs,water-lines,water-barriers-line,water-barriers-poly,marinas-area,piers-poly,piers-line,water-barriers-point,bridge,buildings,buildings-major,tunnels,landuse-overlay,tourism-boundary,line-barriers,cliffs,area-barriers,ferry-routes,turning-circle-casing,highway-area-casing,roads-casing,highway-area-fill,roads-fill,turning-circle-fill,aerialways,roads-low-zoom,waterway-bridges,bridges,guideways,entrances,aeroways,admin-low-zoom,admin-mid-zoom,admin-high-zoom,power-minorline,power-line,nature-reserve-boundaries,trees,country-names,capital-names,state-names,placenames-medium,placenames-small,stations,stations-poly,amenity-points-poly,amenity-line,amenity-points,power-towers,power-poles,roads-text-ref-low-zoom,junctions,bridge-text,roads-text-ref,roads-area-text-name,roads-text-name,paths-text-name,railways-text-name,text-poly-low-zoom,text-poly,text-line,text-point,building-text,interpolation,addresses,water-lines-text,ferry-routes-text,admin-text,nature-reserve-text,amenity-low-priority,amenity-low-priority-poly"
        },
        {
            "Name": "osm-carto-mono",
            "ShortDescription": "OpenStreetMap Carto Monochrome Style",
            "LongDescription": "The 'OpenStreetMap Carto Monochrome' map design only renders (calculated) monochrome shades. The style is intended to be used as background.",
            "Release": "4.15.0",
            "Date": "2018/09/21",
            "Link": "https://github.com/gravitystorm/openstreetmap-carto",
            "Copyright": "© OpenStreetMap contributors",
            "Layers": "world,coast-poly,necountries,landcover-low-zoom,landcover,landcover-line,water-lines-casing,water-lines-low-zoom,icesheet-poly,water-areas,landcover-area-symbols,icesheet-outlines,springs,water-lines,water-barriers-line,water-barriers-poly,marinas-area,piers-poly,piers-line,water-barriers-point,bridge,buildings,buildings-major,tunnels,landuse-overlay,tourism-boundary,line-barriers,cliffs,area-barriers,ferry-routes,turning-circle-casing,highway-area-casing,roads-casing,highway-area-fill,roads-fill,turning-circle-fill,aerialways,roads-low-zoom,waterway-bridges,bridges,guideways,entrances,aeroways,admin-low-zoom,admin-mid-zoom,admin-high-zoom,power-minorline,power-line,nature-reserve-boundaries,trees,country-names,capital-names,state-names,placenames-medium,placenames-small,stations,stations-poly,amenity-points-poly,amenity-line,amenity-points,power-towers,power-poles,roads-text-ref-low-zoom,junctions,bridge-text,roads-text-ref,roads-area-text-name,roads-text-name,paths-text-name,railways-text-name,text-poly-low-zoom,text-poly,text-line,text-point,building-text,interpolation,addresses,water-lines-text,ferry-routes-text,admin-text,nature-reserve-text,amenity-low-priority,amenity-low-priority-poly"
        },
        {
            "Name": "osm-carto-ele20",
            "ShortDescription": "OpenStreetMap Carto Elevation Style (20 m)",
            "LongDescription": "The 'OpenStreetMap Carto Elevation' map design adds elevation (contour) lines with an equidistance of 20 meters to the default osm-carto style.",
            "Release": "4.15.0",
            "Date": "2018/09/21",
            "Link": "https://github.com/gravitystorm/openstreetmap-carto",
            "Copyright": "© OpenStreetMap contributors, © opensnowmap.org (based on ASTER GDEM, SRTM, EU-DEM)",
            "Layers": "world,coast-poly,necountries,landcover-low-zoom,landcover,landcover-line,water-lines-casing,water-lines-low-zoom,icesheet-poly,water-areas,landcover-area-symbols,icesheet-outlines,springs,water-lines,water-barriers-line,water-barriers-poly,marinas-area,piers-poly,piers-line,water-barriers-point,bridge,buildings,buildings-major,tunnels,landuse-overlay,contours,tourism-boundary,line-barriers,cliffs,area-barriers,ferry-routes,turning-circle-casing,highway-area-casing,roads-casing,highway-area-fill,roads-fill,turning-circle-fill,aerialways,roads-low-zoom,waterway-bridges,bridges,guideways,entrances,aeroways,admin-low-zoom,admin-mid-zoom,admin-high-zoom,power-minorline,power-line,nature-reserve-boundaries,trees,country-names,capital-names,state-names,placenames-medium,placenames-small,stations,stations-poly,amenity-points-poly,amenity-line,amenity-points,power-towers,power-poles,roads-text-ref-low-zoom,junctions,bridge-text,roads-text-ref,roads-area-text-name,roads-text-name,paths-text-name,railways-text-name,text-poly-low-zoom,text-poly,text-line,text-point,building-text,interpolation,addresses,water-lines-text,ferry-routes-text,admin-text,nature-reserve-text,amenity-low-priority,amenity-low-priority-poly"
        },
        {
            "Name": "schwarzplan",
            "ShortDescription": "Figure Ground Plan (buildings)",
            "LongDescription": "The 'Figure Ground Plan' map design renders only buildings.",
            "Release": "1.1.0",
            "Date": "2017/06/06",
            "Link": "http://geo.dianacht.de/",
            "Copyright": "© OpenStreetMap contributors",
            "Layers": "buildings"
        },
        {
            "Name": "schwarzplan+",
            "ShortDescription": "Figure Ground Plan Plus (buildings, water areas, highways)",
            "LongDescription": "The 'Figure Ground Plan Plus' map design renders only buildings, water areas and highways (as wire).",
            "Release": "1.6.0",
            "Date": "2018/10/01",
            "Link": "http://freizeitkarte-osm.de/",
            "Copyright": "© OpenStreetMap contributors",
            "Layers": "coast-poly,waterarea,buildings,highways"
        },
        {
            "Name": "raster10",
            "ShortDescription": "Map canvas divided into a 10x10 raster",
            "LongDescription": "Technical map (no database interaction) to verify the placement and styling of user map elements.",
            "Release": "1.0.0",
            "Date": "2017/05/14",
            "Link": "http://freizeitkarte-osm.de/",
            "Copyright": "Public Domain",
            "Layers": "raster10"
        }
    ]
}

Request the available map data

Type Description
Call-URL /api/beta2/maps/capabilities/mapdata
Request-Type GET (fetch capabilities)
Response, Success 200 OK

This web service provides only map data for a limited region. The region is described by a closed polygon. The bounding box of the polygon is described by the coordinate values "minLatitude, maxLatitude, minLongitude, maxLongitude" (see above). If an empty area is returned, the service is not restricted. The center point of the map to be created must be within the polygon. If this is not the case, the creation order is rejected. By querying the polygon, a client can:

Request:

#!/bin/bash
#
# fetch map data capabilities

set -o verbose

curl \
--silent \
--include \
--header "Accept: application/vnd.api+json; charset=utf-8" \
http://printmaps-osm.de:8282/api/beta2/maps/capabilities/mapdata

Response (shortened representation):

HTTP/1.1 200 OK
HTTP/1.1 200 OK
Content-Length: 22
Content-Type: application/json; charset=utf-8
Date: Mon, 03 Dec 2018 15:03:56 GMT

{
    "Points": null
}

Upload user data

To draw your own data (tracks, waypoints, ...) and map elements (images, icons, ...) on the map, the corresponding files must be uploaded to the service.

Request:

#!/bin/bash
#
# upload user data file (e.g. gpx file with tracks)

set -o verbose

curl \
--silent \
--include \
--header "Accept: application/vnd.api+json; charset=utf-8" \
--request POST \
--form "file=@eastriver.gpx" \
http://printmaps-osm.de:8282/api/beta2/maps/upload/ee0eb16b-abcb-4e38-aa44-3d276ea53584

Response (shortened representation):

HTTP/1.1 201 Created
HTTP/1.1 201 Created
Date: Mon, 03 Dec 2018 15:12:38 GMT
Content-Length: 54
Content-Type: text/plain; charset=utf-8

file <eastriver.gpx, 8729 bytes> successfully uploaded