Printmaps stellt für die programmatische Nutzung des Webservices, JSON-API-kompatible Serviceaufrufe zur Verfügung. Hierüber kann ein beliebiger Client (Programm, Webanwendung, curl-Tool, ...) die Printmaps-Services aufrufen. Die nachfolgenden Erläuterungen beschreiben die Nutzung des API und richtet sich an Anwendungsentwickler.

Sollen hingegen interaktiv Karten erzeugt werden, so empfiehlt sich hierfür die Nutzung des Printmaps-Clients. Neben den elementaren Kommandos stellt der Printmaps-Client eine Vielzahl von Hilfsfunktionen zur Verfügung.

Dokument

Art Beschreibung
Version beta2
Datum 2018/12/03
URL http://printmaps-osm.de:8282/api/beta2/maps/

API-Attribute

Attribut Subattribut Erforderlich Datentyp Beschreibung
Fileformat ja string Datenformat der Karte
Scale ja int Maßstab der Karte
PrintWidth ja float Breite der Karte (Millimeter)
PrintHeight ja float Höhe der Karte (Millimeter)
Latitude ja float Breitengrad des Kartenmittelpunktes (Dezimalgrad)
Longitude ja float Längengrad des Kartenmittelpunktes (Dezimalgrad)
Style ja string Design / Stil der Karte
Projection ja int Projektion / Abbildung der Karte (EPSG-Nummer)
HideLayers nein string Liste mit Kartenebenen die nicht angezeigt werden sollen
UserObjects nein struct Benutzerdaten / -elemente (Wiederholungsstruktur)
Style - string Darstellungsstil der Benutzerdaten
SRS - string Spatial Reference System in dem die Benutzerdaten vorliegen
Type - string Typ des Verarbeitungsprozessors für die Benutzerdaten
File - string Datei mit den Benutzerdaten
Layer - string zu extrahierender Datenlayer innerhalb der Benutzerdaten
'oder'
Style - string Darstellungsstil des Benutzerelementes
WellKnownText - string WKT-Definition des Benutzerelememtes
UserFiles nein string Liste der hochgeladenen Benutzerdateien (read-only attribute)

API-Aufrufe

Dieser Service bietet folgende Dienste:

Karte Aktion Beschreibung
Schritt 1 POST (create resource) Definieren der Auftragsdaten
Schritt 2 POST (create resource) Anlegen eines Auftrages
Schritt 3 GET (fetch resource) Abfragen des Auftragsstatus
Schritt 4 GET (fetch resource) Download der erzeugten Karte
optional PATCH (update resource) Aktualisieren von Kartendaten
optional DELETE (delete resource) Löschen aller Daten zu einer Karte
optional GET (fetch resource) Abfragen der Kartendaten
optional GET (fetch capabilities) Abfragen der Service-Eigenschaften
optional GET (fetch capabilities) Abfragen des Kartendatenbereiches
optional POST (send form data) Upload eigener Dateien

Die Beschreibung der einzelnen Servicefunktionen erfolgt anhand von curl-Aufrufen (eingebettet in bash-Skripte).

Definieren der Auftragsdaten (Schritt 1)

Art Beschreibung
Aufruf-URL /api/beta2/maps/metadata
Request-Typ POST (create resource)
Response, Erfolg 201 Created
Response, Fehler 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:

Die Response liefert eine Karten-ID zurück. Diese Kennung identifiert die Karte eindeutig und ist an alle weiteren Service-Aufrufe zu übergeben.

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)"
                }
            ]
        }
    }
}

Anlegen eines Auftrages (Schritt 2)

Art Beschreibung
Aufruf-URL /api/beta2/maps/mapfile
Request-Typ POST (create resource)
Response, Erfolg 202 Accepted
Response, Fehler 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:

Mit dem Statuscode "202 Accepted" signalisiert der Service, dass der Auftrag entgegen genommen und in die Build-Warteschlange eingestellt wurde. Den aktuellen Status des Build-Vorgangs kann der Client über eine entsprechende Abfrage ermitteln.

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)"
                }
            ]
        }
    }
}

Abfragen des Auftragsstatus (Schritt 3)

Art Beschreibung
Aufruf-URL /api/beta2/maps/mapstate/id
Request-Typ GET (fetch resource)
Response, Erfolg 200 OK
Response, Fehler 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:

Der Service dokumentiert den Start des Build-Vorganges im Feld "mapBuildStarted". Sobald der Vorgang abgeschlossen ist, wird das Feld "mapBuildCompleted" aktualisiert. Die Felder "mapBuildSuccessful" und "mapBuildMessage" signalisieren den Erfolg / Misserfolg des Build-Vorganges. Das Feld "mapBuildSuccessful" kann die Werte "no" oder "yes" annehmen. Die Werte in den Feldern "mapBuildBox*" beschreiben technische Eigenschaften und können zur Georeferenzierung der Karte verwendet werden.

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 der erzeugten Karte (Schritt 4)

Art Beschreibung
Aufruf-URL /api/beta2/maps/mapfile/id
Request-Typ GET (fetch resource)
Response, Erfolg 200 OK
Response, Fehler 400 Bad Request

Hinweis: Ein sehr einfacher Weg die erzeugte Karte zu downloaden, ist die Eingabe der kartenspezifischen URL in einem Webbrowser.

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 (symbolisch dargestellt):

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

... der Service sendet die Karte an den Client ...

Service-Response im Falle von Fehlern

Eine negative Serviceantwort kann folgende Ausprägungen haben:

Mit dem Statuscode "400 Bad Request" signalisiert der Service einen fachlichen Fehler und antwortet mit einer detaillierten Fehlerliste. Der Statuscode "500 Internal Server Error" signalisiert einen unerwarteten Fehler auf Seite des Service. In diesem Fall beschreibt eine textuelle Meldung die Art des Fehlers.

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"
        }
    ]
}

Aktualisieren von Kartendaten

Art Beschreibung
Aufruf-URL /api/beta2/maps/metadata
Request-Typ PATCH (update resource)
Response, Erfolg 200 OK
Response, Fehler 400 Bad Request

Die serviceseitig gespeicherten Kartendaten können jederzeit aktualisiert werden. Es ist immer der vollständige Datensatz mit allen Elemente zu aktualisieren.

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:

Der Service signalisiert die erfolgreiche Aktualisierung durch den 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)"
                }
            ]
        }
    }
}

Löschen aller Daten zu einer Karte

Art Beschreibung
Aufruf-URL /api/beta2/maps/id
Request-Typ DELETE (delete resource)
Response, Erfolg 204 No Content
Response, Fehler 400 Bad Request

Der Service speichert die Daten zu einer Karte (Auftragsdaten, Auftragsstatus, Karte, Benutzerdateien) unter der Karten-ID. Der Client kann die Löschung der Daten anfordern.

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:

Der Service signalisiert die erfolgreiche Löschung der Daten durch den Statuscode "204 No Content".

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

Abfragen der Kartendaten

Art Beschreibung
Aufruf-URL /api/beta2/maps/metadata/id
Request-Typ GET (fetch resource)
Response, Erfolg 200 OK
Response, Fehler 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
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)"
                }
            ]
        }
    }
}

Abfragen der Service-Eigenschaften

Art Beschreibung
Aufruf-URL /api/beta2/maps/capabilities/service
Request-Typ GET (fetch capabilities)
Response, Erfolg 200 OK

Um auf Seiten des Clients die Dateneingabe zu steuern (Bedienelemente) und eine Datenvorprüfung durchzuführen, können die Eigenschaften des Services abgefragt werden. Einzelne Eigenschaften können sich ändern, somit ist die nachfolgende Ausgabe lediglich als Beispiel zu verstehen. Der Client sollte mit Beginn jeder Sitzung die Eigenschaften neu ermitteln.

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"
        }
    ]
}

Abfragen des Kartendatenbereiches

Art Beschreibung
Aufruf-URL /api/beta2/maps/capabilities/mapdata
Request-Typ GET (fetch capabilities)
Response, Erfolg 200 OK

Dieser Webservice hält nur Kartendaten für eine begrenzte Region bereit. Die Region wird durch ein geschlossenes Polygon beschrieben. Die Bounding-Box des Polygons wird durch die Koordinatenwerte "minLatitude, maxLatitude, minLongitude, maxLongitude" beschrieben (siehe oben). Wird ein leerer Bereich zurückgegeben, so unterliegt der Service keinen Einschränkungen. Der Mittelpunkt der zu erstellenden Karte muss sich innerhalb des Polygons befinden. Ist dies nicht der Fall, wird der Erstellungsauftrag zurückgewiesen. Durch die Abfrage des Polygons kann ein Client:

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:

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 eigener Dateien

Um eigene Daten (Tracks, Waypoints, ...) und Kartenelemente (Grafiken, Icons, ...) auf der Karte anzuzeigen, sind die Dateien zunächst auf den Service hochzuladen.

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:

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