Printmaps provides JSON-API-compatible service calls for the basic use of this web service. Over this, any client (program client, web application, curl tool, ...) can use the Printmaps services.

Document

Type Description
Version beta
Date 2017/05/23
URL http://printmaps-osm.de:8181/api/beta/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
HideLayers no string list of map layers to hide
UserData no struct user data to depict (repetitive structure)
Style yes string design (style) of user data
SRS yes string spatial reference system for user data
Type yes string type of preprocessor for user data
File yes string file with user data
Layer yes/no string data layer (within user data) to extract
UserItems no struct user elements to depict (repetitive structure)
Style yes string design (style) of user element
WellKnownText yes string wkt definition of user element
UserScalebar no struct user defined scale bar
Style yes string design (style) of scale bar
NatureLength yes float length (meter) of scale bar in nature
XPos yes float x-position (millimeter) of scale bar
YPos yes float y-position (millimeter) of scale bar
UserFiles - 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/beta/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": 10000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 51.9505,
            "Longitude": 7.6049,
            "Style": "osm-carto",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserData": null,
            "UserItems": [
                {
                    "Style": "<PolygonSymbolizer fill='white' fill-opacity='0.75' />",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0))"
                },
                {
                    "Style": "<LineSymbolizer stroke='black' stroke-width='3' stroke-linecap='square' />",
                    "WellKnownText": "LINESTRING(15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-2' size='40' fill='firebrick' allow-overlap='true'>'Aasee, Münster\\nTour and Sculptures\\nScale 1:10000'</TextSymbolizer>",
                    "WellKnownText": "POINT(300.0 560.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-0' size='12' fill='firebrick' orientation='90' halo-radius='1' halo-fill='white' allow-overlap='true'>'© OpenStreetMap contributors'</TextSymbolizer>",
                    "WellKnownText": "POINT(7.5 300.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-2' size='360' fill='firebrick' opacity='0.2' orientation='315' allow-overlap='true'>'S A M P L E'</TextSymbolizer>",
                    "WellKnownText": "POINT(300.0 300.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-1' size='16' fill='firebrick' halo-radius='1' halo-fill='white' allow-overlap='true'>'500 Meter'</TextSymbolizer>",
                    "WellKnownText": "POINT(40.0 36.0)"
                }
            ],
            "UserScalebar": {
                "Style": "<LineSymbolizer stroke='firebrick' stroke-width='8' stroke-linecap='butt' />",
                "NatureLength": 500,
                "XPos": 30,
                "YPos": 30
            }
        }
    }
}
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:8181/api/beta/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: 2565
Content-Type: application/vnd.api+json; charset=utf-8
Date: Thu, 18 May 2017 13:49:07 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "0ac04905-7c27-40cb-a667-e0f9dae61bd3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 10000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 51.9505,
            "Longitude": 7.6049,
            "Style": "osm-carto",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserData": null,
            "UserItems": [
                {
                    "Style": "\u003cPolygonSymbolizer fill='white' fill-opacity='0.75' /\u003e",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0))"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='black' stroke-width='3' stroke-linecap='square' /\u003e",
                    "WellKnownText": "LINESTRING(15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='40' fill='firebrick' allow-overlap='true'\u003e'Aasee, Münster\nTour and Sculptures\nScale 1:10000'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(300.0 560.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-0' size='12' fill='firebrick' orientation='90' halo-radius='1' halo-fill='white' allow-overlap='true'\u003e'© OpenStreetMap contributors'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(7.5 300.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='360' fill='firebrick' opacity='0.2' orientation='315' allow-overlap='true'\u003e'S A M P L E'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(300.0 300.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-1' size='16' fill='firebrick' halo-radius='1' halo-fill='white' allow-overlap='true'\u003e'500 Meter'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(40.0 36.0)"
                }
            ],
            "UserScalebar": {
                "Style": "\u003cLineSymbolizer stroke='firebrick' stroke-width='8' stroke-linecap='butt' /\u003e",
                "NatureLength": 500,
                "XPos": 30,
                "YPos": 30
            }
        }
    }
}

Create an order (step 2)

Type Description
Call-URL /api/beta/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": "0ac04905-7c27-40cb-a667-e0f9dae61bd3"
    }
}
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:8181/api/beta/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: 2565
Content-Type: application/vnd.api+json; charset=utf-8
Date: Thu, 18 May 2017 13:56:23 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "0ac04905-7c27-40cb-a667-e0f9dae61bd3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 10000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 51.9505,
            "Longitude": 7.6049,
            "Style": "osm-carto",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserData": null,
            "UserItems": [
                {
                    "Style": "\u003cPolygonSymbolizer fill='white' fill-opacity='0.75' /\u003e",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0))"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='black' stroke-width='3' stroke-linecap='square' /\u003e",
                    "WellKnownText": "LINESTRING(15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='40' fill='firebrick' allow-overlap='true'\u003e'Aasee, Münster\nTour and Sculptures\nScale 1:10000'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(300.0 560.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-0' size='12' fill='firebrick' orientation='90' halo-radius='1' halo-fill='white' allow-overlap='true'\u003e'© OpenStreetMap contributors'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(7.5 300.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='360' fill='firebrick' opacity='0.2' orientation='315' allow-overlap='true'\u003e'S A M P L E'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(300.0 300.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-1' size='16' fill='firebrick' halo-radius='1' halo-fill='white' allow-overlap='true'\u003e'500 Meter'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(40.0 36.0)"
                }
            ],
            "UserScalebar": {
                "Style": "\u003cLineSymbolizer stroke='firebrick' stroke-width='8' stroke-linecap='butt' /\u003e",
                "NatureLength": 500,
                "XPos": 30,
                "YPos": 30
            }
        }
    }
}

Request the order status (step 3)

Type Description
Call-URL /api/beta/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:8181/api/beta/maps/mapstate/0ac04905-7c27-40cb-a667-e0f9dae61bd3

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: 1124
Content-Type: application/vnd.api+json; charset=utf-8
Date: Thu, 18 May 2017 14:00:53 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "0ac04905-7c27-40cb-a667-e0f9dae61bd3",
        "Attributes": {
            "MapMetadataWritten": "2017-05-18T15:49:07+02:00",
            "MapOrderSubmitted": "2017-05-18T15:56:23+02:00",
            "MapBuildStarted": "2017-05-18T15:56:26+02:00",
            "MapBuildCompleted": "2017-05-18T15:56:44+02:00",
            "MapBuildSuccessful": "yes",
            "MapBuildMessage": "map build successful",
            "MapBuildBoxMillimeter": {
                "Width": 600,
                "Height": 600
            },
            "MapBuildBoxPixel": {
                "Width": 7087,
                "Height": 7087
            },
            "MapBuildBoxEPSG3857": {
                "XMin": 841706.669895,
                "YMin": 6786313.23769,
                "XMax": 851440.521173,
                "YMax": 6796047.08897
            },
            "MapBuildBoxEPSG4326": {
                "LonMin": 7.56117966312,
                "LatMin": 51.9235452218,
                "LonMax": 7.64862033688,
                "LatMax": 51.9774385861
            }
        }
    }
}

Download the created map (step 4)

Type Description
Call-URL /api/beta/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:8181/api/beta/maps/mapfile/0ac04905-7c27-40cb-a667-e0f9dae61bd3

set +o verbose # echo off from bash script
echo

cat 'response-header.txt'

found=`grep "HTTP/1.1 200 OK" < "response-header.txt"`
if  [ ! "$found" ]; then
    cat "printmap.zip"
    echo
fi

Response (symbolic representation):

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 30200630
Content-Type: application/zip
Last-Modified: Thu, 18 May 2017 13:56:44 GMT
Date: Thu, 18 May 2017 14:02:44 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",
        "attributes": {
            "fileformat": "jpeg",
            "scale": 5000,
            "printWidth": 6600.0,
            "printHeight": 600.0,
            "latitude": 151.9505,
            "longitude": 7.6049,
            "style": "osm-cartago"
        }
    }
}
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:8181/api/beta/maps/metadata

Response:

HTTP/1.1 400 Bad Request
Content-Length: 1533
Content-Type: application/vnd.api+json; charset=utf-8
Date: Thu, 18 May 2017 14:04:53 GMT

{
    "Errors": [
        {
            "ID": "",
            "Status": "422 Unprocessable Entity",
            "Code": "3008",
            "Source": {
                "Pointer": "data.attributes.style",
                "Parameter": ""
            },
            "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",
                "Parameter": ""
            },
            "Title": "invalid attribute fileformat",
            "Detail": "valid values: png"
        },
        {
            "ID": "",
            "Status": "422 Unprocessable Entity",
            "Code": "3006",
            "Source": {
                "Pointer": "data.attributes.latitude",
                "Parameter": ""
            },
            "Title": "invalid attribute latitude",
            "Detail": "valid values: 45.82 ... 55.15"
        },
        {
            "ID": "",
            "Status": "422 Unprocessable Entity",
            "Code": "3013",
            "Source": {
                "Pointer": "data.attributes.latitude and/or data.attributes.longitude",
                "Parameter": ""
            },
            "Title": "no map data available",
            "Detail": "no data available for the center position of the map"
        }
    ]
}

Update the order data

Type Description
Call-URL /api/beta/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.

Request:

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

postdata=$(cat <<EOF
{
    "Data": {
        "Type": "maps",
        "ID": "0ac04905-7c27-40cb-a667-e0f9dae61bd3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 10000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 51.9505,
            "Longitude": 7.6049,
            "Style": "osm-carto",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserData": [
                {
                    "Style": "<LineSymbolizer stroke='crimson' stroke-width='10' stroke-opacity='0.75' stroke-linecap='round' />",
                    "SRS": "+init=epsg:4326",
                    "Type": "ogr",
                    "File": "aasee.gpx",
                    "Layer": "tracks"
                }
            ],
            "UserItems": [
                {
                    "Style": "<PolygonSymbolizer fill='white' fill-opacity='0.75' />",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0))"
                },
                {
                    "Style": "<LineSymbolizer stroke='black' stroke-width='3' stroke-linecap='square' />",
                    "WellKnownText": "LINESTRING(15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-2' size='40' fill='firebrick' allow-overlap='true'>'Aasee, Münster\\nTour and Sculptures\\nScale 1:10000'</TextSymbolizer>",
                    "WellKnownText": "POINT(300.0 560.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-0' size='12' fill='firebrick' orientation='90' halo-radius='1' halo-fill='white' allow-overlap='true'>'© OpenStreetMap contributors'</TextSymbolizer>",
                    "WellKnownText": "POINT(7.5 300.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-2' size='360' fill='firebrick' opacity='0.2' orientation='315' allow-overlap='true'>'S A M P L E'</TextSymbolizer>",
                    "WellKnownText": "POINT(300.0 300.0)"
                },
                {
                    "Style": "<TextSymbolizer fontset-name='fontset-1' size='16' fill='firebrick' halo-radius='1' halo-fill='white' allow-overlap='true'>'500 Meter'</TextSymbolizer>",
                    "WellKnownText": "POINT(40.0 36.0)"
                }
            ],
            "UserScalebar": {
                "Style": "<LineSymbolizer stroke='firebrick' stroke-width='8' stroke-linecap='butt' />",
                "NatureLength": 500,
                "XPos": 30,
                "YPos": 30
            }
        }
    }
}
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:8181/api/beta/maps/metadata

Response:

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

HTTP/1.1 200 OK
Content-Length: 2913
Content-Type: application/vnd.api+json; charset=utf-8
Date: Thu, 18 May 2017 14:14:11 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "0ac04905-7c27-40cb-a667-e0f9dae61bd3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 10000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 51.9505,
            "Longitude": 7.6049,
            "Style": "osm-carto",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserData": [
                {
                    "Style": "\u003cLineSymbolizer stroke='crimson' stroke-width='10' stroke-opacity='0.75' stroke-linecap='round' /\u003e",
                    "SRS": "+init=epsg:4326",
                    "Type": "ogr",
                    "File": "aasee.gpx",
                    "Layer": "tracks"
                }
            ],
            "UserItems": [
                {
                    "Style": "\u003cPolygonSymbolizer fill='white' fill-opacity='0.75' /\u003e",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0))"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='black' stroke-width='3' stroke-linecap='square' /\u003e",
                    "WellKnownText": "LINESTRING(15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='40' fill='firebrick' allow-overlap='true'\u003e'Aasee, Münster\nTour and Sculptures\nScale 1:10000'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(300.0 560.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-0' size='12' fill='firebrick' orientation='90' halo-radius='1' halo-fill='white' allow-overlap='true'\u003e'© OpenStreetMap contributors'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(7.5 300.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='360' fill='firebrick' opacity='0.2' orientation='315' allow-overlap='true'\u003e'S A M P L E'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(300.0 300.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-1' size='16' fill='firebrick' halo-radius='1' halo-fill='white' allow-overlap='true'\u003e'500 Meter'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(40.0 36.0)"
                }
            ],
            "UserScalebar": {
                "Style": "\u003cLineSymbolizer stroke='firebrick' stroke-width='8' stroke-linecap='butt' /\u003e",
                "NatureLength": 500,
                "XPos": 30,
                "YPos": 30
            }
        }
    }
}

Delete all data of a map order

Type Description
Call-URL /api/beta/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:8181/api/beta/maps/f09bbb26-7d6d-406f-92b9-11aa152c551b

Response:

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

HTTP/1.1 204 No Content
Date: Tue, 18 Apr 2017 13:52:34 GMT

Request the map data

Type Description
Call-URL /api/beta/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:8181/api/beta/maps/metadata/0ac04905-7c27-40cb-a667-e0f9dae61bd3

Response:

HTTP/1.1 200 OK
Content-Length: 2913
Content-Type: application/vnd.api+json; charset=utf-8
Date: Thu, 18 May 2017 14:18:34 GMT

{
    "Data": {
        "Type": "maps",
        "ID": "0ac04905-7c27-40cb-a667-e0f9dae61bd3",
        "Attributes": {
            "Fileformat": "png",
            "Scale": 10000,
            "PrintWidth": 600,
            "PrintHeight": 600,
            "Latitude": 51.9505,
            "Longitude": 7.6049,
            "Style": "osm-carto",
            "HideLayers": "admin-low-zoom,admin-mid-zoom,admin-high-zoom,admin-text",
            "UserData": [
                {
                    "Style": "\u003cLineSymbolizer stroke='crimson' stroke-width='10' stroke-opacity='0.75' stroke-linecap='round' /\u003e",
                    "SRS": "+init=epsg:4326",
                    "Type": "ogr",
                    "File": "aasee.gpx",
                    "Layer": "tracks"
                }
            ],
            "UserItems": [
                {
                    "Style": "\u003cPolygonSymbolizer fill='white' fill-opacity='0.75' /\u003e",
                    "WellKnownText": "POLYGON((0.0 0.0, 0.0 600.0, 600.0 600.0, 600.0 0.0, 0.0 0.0), (15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0))"
                },
                {
                    "Style": "\u003cLineSymbolizer stroke='black' stroke-width='3' stroke-linecap='square' /\u003e",
                    "WellKnownText": "LINESTRING(15.0 15.0, 15.0 585.0, 585.0 585.0, 585.0 15.0, 15.0 15.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='40' fill='firebrick' allow-overlap='true'\u003e'Aasee, Münster\nTour and Sculptures\nScale 1:10000'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(300.0 560.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-0' size='12' fill='firebrick' orientation='90' halo-radius='1' halo-fill='white' allow-overlap='true'\u003e'© OpenStreetMap contributors'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(7.5 300.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-2' size='360' fill='firebrick' opacity='0.2' orientation='315' allow-overlap='true'\u003e'S A M P L E'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(300.0 300.0)"
                },
                {
                    "Style": "\u003cTextSymbolizer fontset-name='fontset-1' size='16' fill='firebrick' halo-radius='1' halo-fill='white' allow-overlap='true'\u003e'500 Meter'\u003c/TextSymbolizer\u003e",
                    "WellKnownText": "POINT(40.0 36.0)"
                }
            ],
            "UserScalebar": {
                "Style": "\u003cLineSymbolizer stroke='firebrick' stroke-width='8' stroke-linecap='butt' /\u003e",
                "NatureLength": 500,
                "XPos": 30,
                "YPos": 30
            }
        }
    }
}

Request the service capabilities

Type Description
Call-URL /api/beta/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:8181/api/beta/maps/capabilities/service

Response:

HTTP/1.1 200 OK
Content-Length: 7012
Content-Type: application/json; charset=utf-8
Date: Sun, 21 May 2017 13:24:08 GMT

{
    "ConfigMapdata": {
        "Description": "germany, austria, switzerland",
        "MinLatitude": 45.81617,
        "MaxLatitude": 55.14777,
        "MinLongitude": 5.864417,
        "MaxLongitude": 17.16273
    },
    "ConfigMapformats": [
        {
            "Type": "png",
            "MinPrintWidth": 5,
            "MaxPrintWidth": 2500,
            "MinPrintHeigth": 5,
            "MaxPrintHeigth": 2500
        }
    ],
    "ConfigMapscale": {
        "MinScale": 100,
        "MaxScale": 200000
    },
    "ConfigStyles": [
        {
            "Name": "osm-carto",
            "ShortDescription": "OpenStreetMap Carto Style",
            "LongDescription": "The 'OpenStreetMap Carto' map design is the standard style rendered at the OSM webpage.",
            "Release": "3.3.0",
            "Date": "2017/05/10",
            "Link": "https://github.com/gravitystorm/openstreetmap-carto",
            "Copyright": "© OpenStreetMap contributors",
            "Layers": "world,coast-poly,builtup,necountries,landcover-low-zoom,landcover,landcover-line,water-lines-casing,water-lines-low-zoom,icesheet-poly,water-areas,landcover-area-symbols,icesheet-outlines,water-lines,water-barriers-line,water-barriers-poly,marinas-area,piers-poly,piers-line,water-barriers-point,bridge,buildings,buildings-major,tunnels,landuse-overlay,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,admin-low-zoom,admin-mid-zoom,admin-high-zoom,power-minorline,power-line,nature-reserve-boundaries,tourism-boundary,trees,country-names,capital-names,state-names,placenames-medium,placenames-small,stations,stations-poly,amenity-points-poly,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,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": "3.3.0",
            "Date": "2017/05/10",
            "Link": "https://github.com/gravitystorm/openstreetmap-carto",
            "Copyright": "© OpenStreetMap contributors",
            "Layers": "world,coast-poly,builtup,necountries,landcover-low-zoom,landcover,landcover-line,water-lines-casing,water-lines-low-zoom,icesheet-poly,water-areas,landcover-area-symbols,icesheet-outlines,water-lines,water-barriers-line,water-barriers-poly,marinas-area,piers-poly,piers-line,water-barriers-point,bridge,buildings,buildings-major,tunnels,landuse-overlay,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,admin-low-zoom,admin-mid-zoom,admin-high-zoom,power-minorline,power-line,nature-reserve-boundaries,tourism-boundary,trees,country-names,capital-names,state-names,placenames-medium,placenames-small,stations,stations-poly,amenity-points-poly,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,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": "3.3.0",
            "Date": "2017/05/10",
            "Link": "https://github.com/gravitystorm/openstreetmap-carto",
            "Copyright": "© OpenStreetMap contributors, © U.S. Geological Survey, © J. de Ferranti",
            "Layers": "world,coast-poly,builtup,necountries,landcover-low-zoom,landcover,landcover-line,water-lines-casing,water-lines-low-zoom,icesheet-poly,water-areas,landcover-area-symbols,icesheet-outlines,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,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,admin-low-zoom,admin-mid-zoom,admin-high-zoom,power-minorline,power-line,nature-reserve-boundaries,tourism-boundary,trees,country-names,capital-names,state-names,placenames-medium,placenames-small,stations,stations-poly,amenity-points-poly,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,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.0.0",
            "Date": "2015/06/20",
            "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.0.0",
            "Date": "2017/04/22",
            "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/beta/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). 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:8181/api/beta/maps/capabilities/mapdata

Response (shortened representation):

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 09 May 2017 06:42:36 GMT
Transfer-Encoding: chunked

{
    "Points": [
        {
            "X": 13.84947,
            "Y": 48.77257
        },
        {
            "X": 13.86828,
            "Y": 48.77181
        },
 ...
        {
            "X": 13.81835,
            "Y": 48.78202
        },
        {
            "X": 13.84947,
            "Y": 48.77257
        }
    ]
}

Upload user data

To draw your own data (tracks, waypoints, ...) and / or elements (title, legend, ...) 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=@aasee.gpx" \
http://printmaps-osm.de:8181/api/beta/maps/upload/0ac04905-7c27-40cb-a667-e0f9dae61bd3

Response (shortened representation):

HTTP/1.1 201 Created
Date: Thu, 18 May 2017 14:24:56 GMT
Content-Length: 51
Content-Type: text/plain; charset=utf-8

file <aasee.gpx, 95009 bytes> successfully uploaded