DE:OpenRailwayMap/API

From OpenStreetMap Wiki
Jump to: navigation, search

Nutzungsbedingungen

Die OpenRailwayMap ist ein nicht-kommerzielles Projekt, das durch Spenden finanziert und durch den ehrenamtlichen Einsatz der Mitglieder umgesetzt wird. Unsere Infrastruktur bietet nur eine begrenzte Kapazität, daher gelten bei der Nutzung der API und der Tiles die folgenden Bedingungen:

  • Kleinere Anwendungen mit unregelmäßigen oder relativ wenigen Abfragen dürfen die Tiles und die API frei und kostenlos nutzen.
  • Kommerzielle Anwendungen werden grundsätzlich nicht anders behandelt, jedoch ist eine finanzielle Unterstützung ausdrücklich erwünscht.
  • Anwendungen müssen mit ihren Anfragen einen eindeutigen User-Agent bestehend aus Namen und einer URL senden, um die Betreiber im Problemfall kontaktieren zu können. Beim Einbinden von Tiles in einer Webseite ist das Mitsenden eines User-Agents technisch nicht möglich und daher auch nicht erforderlich. In diesen Fällen reicht der Referer als eindeutige Identifizierung aus, den der Browser beim Laden der Grafiken automatisch mitsendet.
  • Werden regelmäßig und in größerem Stil API-Abfragen gesendet oder Tiles angefragt, dann werden die entsprechenden Nutzer blockiert und - falls identifizierbar - kontaktiert.
  • Blockierten Nutzer geben wir entweder Tipps, wie sich die benötigte Funktionalität auf einem eigenen Server einrichten lässt, oder würden eine Weiternutzung unserer Dienste gegen eine finanzielle Unterstützung erlauben.
  • Die Beantwortung von API-Anfragen sollte in der Regel nicht länger als 3 Sekunden dauern. Trotzdem sollten Anwendungen so geschrieben werden, dass Anfragen nach etwa 5 Sekunden abgebrochen werden. Schlagen mehrere Anfragen kurz hintereinander fehl, dann sollte eine Anwendung davon ausgehen, dass die API momemtan nicht erreichbar ist und die Abfragerate senken.
  • Die API begrenzt die Häufigkeit von Anfragen angemessenes Maß. Die Grenzen sind so gewählt, dass die API nicht überlastet wird und nicht massenhaft Datensätze abgefragt werden (harvesting). Sollte eine Anwendung diese Grenze erreichen und dies zu Problemen führen, dann kontaktiere uns und beschreibe das Problem, sodass wir eventuell Abhilfe schaffen können.
  • Wenn die API oder die Tiles durch Anwendungen genutzt wird, sollten nur dann Daten abgefragt werden, wenn sie durch den Benutzer aktiv angefordert wurden. Falls automatische Abfragen vieler einzelner Datensätze (bulk requests) benötigt werden, sollten künstliche Verzögerungen in das Programm eingebaut werden, damit es sich ähnlich wie ein menschlischer Nutzer verhält. Generell sollten in einer Anwendung an möglichst vielen Stellen gecacht werden, um die Last zu verringern.
  • Die Verfügbarkeit ist allgemein sehr hoch, kann aber nicht garantiert werden. Bedenke, dass dies ein kostenloses Angebot eines nichtkommerziellen Gemeinschaftsprojektes ist. Falls du einen garantiert zuverlässigen Service benötigst, solltest du eine eigene Instanz dieser API bzw. dieses Tileservers aufsetzen.

Die Daten der OpenStreetMap-Datenbank, aus der die Daten der OpenRailwayMap stammen, stehen unter der Lizenz Open Data Commons Open Database License (ODbL). Die Tiles der OpenRailwayMap stehen unter der Creative-Commons-Lizenz Namensnennung - Weitergabe unter gleichen Bedingungen 2.0 (CC-BY-SA 2.0).

Beim Einbinden der OpenRailwayMap-Karte oder einer anderen Nutzung der Tiles ist also folgender Hinweis notwendig:

Daten <a href="http://www.openstreetmap.org/copyright">© OpenStreetMap-Mitwirkende</a>, Grafik: <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA 2.0</a> <a href="http://www.openrailwaymap.org/">OpenRailwayMap</a>

Wird als Hintergrund zusätzlich eine herkömmliche OpenStreetMap-Karte verwendet, was unter anderem beim Einbinden der OpenRailwayMap-Webseite stattfindet, ist folgender Hinweis notwendig:

Daten <a href="http://www.openstreetmap.org/copyright">© OpenStreetMap-Mitwirkende</a>, Grafik: <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA 2.0</a> <a href="http://www.openrailwaymap.org/">OpenRailwayMap</a> und OpenStreetMap

Werden dagegen Daten von der API abgefragt, ist folgender Hinweis in die Anwendung einzubauen:

Daten <a href="http://www.openstreetmap.org/copyright">© OpenStreetMap-Mitwirkende</a>, Anbieter: <a href="http://www.openrailwaymap.org/">OpenRailwayMap</a>

Ein Hinweis ist ungültig, wenn der Text die gleiche Farbe wie der Hintergrund hat, die Schrift unleserlich klein ist, der Hinweistext teilweise oder vollständig verdeckt ist oder die Links fehlen.

Tiles

The map tiles follow the standard Web Mercator tile format - also known as Spherical Mercator, OpenStreetMap or Google tiles. They are usually supported natively by any map library that you are using, but read on if you want to know more details.

Die Tiles haben eine Größe 512 x 512 Pixeln und liegen im PNG-Format vor. Effektiv beträgt die Auflösung 256 x 256 Pixel, die doppelte Auflösung ergibt sich aus der "Retina"-Qualität. Als Projektion wird Spherical Mercator verwendet, das unter den EPSG-Codes EPSG:3857, EPSG:900913 und EPSG:3785 bekannt ist. Sie sind unter folgender URL abrufbar:

http://${s}.tiles.openrailwaymap.org/${style}/${z}/${x}/${y}.png

In modernen Browsern ist die Zahl der gleichzeitigen Bildanfragen an eine Domain standardmäßig begrenzt. Um diese Begrenzung zu umgehen und das Laden der Tiles zu beschleunigen, können Anfragen an verschiedene Subdomains gestellt werden, die auf den gleichen Server verweisen. Durch das Ersetzen des Platzhalters ${s} durch a, b oder c werden künstlich unterschiedliche Subdomains erzeugt. Dieses Domainpräfix kann aber auch weggelassen werden, falls er nicht benötigt wird.

Der Platzhalter ${style} wird durch den gewünschten Kartenstil ersetzt. Momentan existieren folgende Stile:

Wert Erläuterung
standard Standard-Eisenbahnlayer mit der Darstellung der Basisinfrastruktur wie etwa Gleise, Betriebsstellen, Streckennummern, Weichen, etc
signals Darstellung von Signalen und Zugsicherungssystemen
maxspeed Darstellung von Streckenhöchstgeschwindigkeiten und Geschwindigkeitssignalen

Einbindung in OpenLayers 2

var openrailwaymap = new OpenLayers.Layer.XYZ("OpenRailwayMap", ["http://a.tiles.openrailwaymap.org/standard/${z}/${x}/${y}.png","http://b.tiles.openrailwaymap.org/standard/${z}/${x}/${y}.png","http://c.tiles.openrailwaymap.org/standard/${z}/${x}/${y}.png"],
{
	sphericalMercator: true,
	opacity: 1,
	visibility: false,
	transparent: true,
	noOpaq: true,
	isBaseLayer: false,
	attribution: '<a href="http://www.openstreetmap.org/copyright">© OpenStreetMap-Mitwirkende</a>, Grafik: <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA 2.0</a> <a href="http://www.openrailwaymap.org/">OpenRailwayMap</a> und OpenStreetMap'
});
map.addLayer(openrailwaymap);

Einbindung in OpenLayers 3

var openrailwaymap = new ol.layer.Tile({
    title: 'OpenRailwayMap',
    visible: true,
    source : new ol.source.XYZ({
                attributions : [
                    ol.source.OSM.ATTRIBUTION,
                    new ol.Attribution({
                        html : 'Grafik: <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA 2.0</a> <a href="http://www.openrailwaymap.org/">OpenRailwayMap</a> und OpenStreetMap'
                    })
                ],
                url : 'http://{a-c}.tiles.openrailwaymap.org/standard/{z}/{x}/{y}.png',
                crossOrigin: null, //make it work inside canvas
                tilePixelRatio: 2, //server returns 512px img for 256 tiles
                maxZoom: 19, // XYZ's default is 18
                opaque: true
            })
        })
map.addLayer(openrailwaymap);

Einbindung in Leaflet

var openrailwaymap = new L.TileLayer('http://{s}.tiles.openrailwaymap.org/standard/{z}/{x}/{y}.png',
{
	attribution: "<a href="http://www.openstreetmap.org/copyright">© OpenStreetMap-Mitwirkende</a>, Grafik: <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA 2.0</a> <a href="http://www.openrailwaymap.org/">OpenRailwayMap</a> und OpenStreetMap",
	minZoom: 2,
	maxZoom: 19,
	tileSize: 256
}).addTo(map);

Einbindung in OsmAnd

Layer mit Höchstgeschwindigkeiten (online geladen) auf einer Offline-Karte in OsmAnd 2.0
Overlay-Auswahl in Osmand mit OpenRailwayMap- und anderen Online-Layern

Die Kacheln der OpenRailwayMap können mit wenigen Schritten auch in die beliebte Android- und iOS-App OsmAnd eingebunden werden.

Die folgenden Schritte beziehen sich auf die Android-App. iOS-Nutzer beachten bitte die Hinweise von Krist van Besien in der OsmAnd-Google-Group.

Um die folgenden Schritte vollziehen zu können, muss das Plugin "Online-Karten" aktiviert sein. Die Liste der Plugins ist über das Viereck-Symbol, im Hauptmenü links unten, abrufbar (ggf. nach unten scrollen und in der Plugin-Box "Alles zeigen" anwählen).

  1. In der Kartenansicht das runde Ebenen-Symbol (links oben) anwählen.
  2. Im nun erscheinenden Menü "Karte konfigurieren" "Overlay-Karte..." oder "Underlay-Karte..." anwählen.
  3. Nun "Weitere installieren..." wählen, nach unten scrollen und aus der Liste die gewünschten OpenRailwayMap-Layer (OpenRailwayMap, OpenRailwayMap maxspeed, OpenRailwayMap signalling) auswählen.

Damit stehen die Karten im Overlay- bzw. Underlay-Menü zur Verfügung.

Tipp: Standardmäßig können die Overlay-Karten blass wirken. Die Kartentransparenz kann auf zwei Wegen angepasst werdenː

  • Über einen unscheinbaren blauen Schieberegler im unteren mittleren Bereich der Kartenansicht.
  • Über die Einstellungen des Online-Karten-Pluginsː Viereck-Symbol links unten → "Online-Karten" aus der Plugin-Liste auswählen → "Einstellungen" → "Overlay-Transparenz" bzw. "Kartentransparenz".

Tipp: Die OpenRailwayMap-Karten können auch als Grundkarte verwendet werden (Ebenen-Symbol => "Kartenquelle"). Unter einem (OpenRailwayMap-)Overlay kann ein weiterer OpenRailwayMap-Layer als Underlay platziert werden. Grundsätzlich können so alle drei OpenRailwayMap-Karten gleichzeitig verwendet werden.

OsmAnd speichert heruntergeladene Kartenelemente auf dem Gerät. Einmal heruntergeladen, stehen diese auch offline zur Verfügung. Um sie zu aktualsieren, müssen sie im entsprechenden Unterverzeichnis von tiles im Osmand-Ordner gelöscht und neu heruntergeladen werden.

Eine reine Offline-Nutzung der OpenRailwayMap in OsmAnd ist derzeit noch nicht möglich. Dem Projekt stehen momentan nicht die Ressourcen zur Verfügung, um fertige Offlinedaten zum Download anzubieten. Es besteht zwar die Möglichkeit, auf dem eigenen Rechner selbst die Offlinekarten zu generieren, doch dafür fehlt noch ein entsprechender Kartenstil für OsmAnd. Informationen zum aktuellen Stand finden sich im Github-Repository der OpenRailwayMap.


Einbindung in QGIS

Die Tiles der OpenRailwayMap können auch in QGIS eingebunden werden. Dazu ist das Tile Map Scale Levels Plugin und die folgende XML-Konfiguration erforderlich. Der Platzhalter ${style} wird durch den gewünschten Kartenstil ersetzt. In der Tabelle oben sind die möglichen Werte aufgeführt.

<GDAL_WMS>
	<Service name="TMS">
		<ServerUrl>http://tiles.openrailwaymap.org/${style}/${z}/${x}/${y}.png</ServerUrl>
	</Service>
	<DataWindow>
		<UpperLeftX>-20037508.34</UpperLeftX>
		<UpperLeftY>20037508.34</UpperLeftY>
		<LowerRightX>20037508.34</LowerRightX>
		<LowerRightY>-20037508.34</LowerRightY>
		<TileLevel>19</TileLevel>
		<TileCountX>1</TileCountX>
		<TileCountY>1</TileCountY>
		<YOrigin>top</YOrigin>
	</DataWindow>
	<Projection>EPSG:3857</Projection>
	<BlockSizeX>512</BlockSizeX>
	<BlockSizeY>512</BlockSizeY>
	<BandsCount>4</BandsCount>
	<Cache>
		<Path>/tmp/cache_osm_rail</Path>
	</Cache>
</GDAL_WMS>

API

Die OpenRailwayMap verfügt über eine API, die das gezielte Abfragen von Eisenbahndaten in der OpenStreetMap-Datenbank vereinfacht. Es handelt sich um eine RESTful HTTP API. Alle Anfragen erfolgen über die HTTP GET Methode, die Resultate sind im JSON Format.

Die API unterstützt Cross-Origin Resource Sharing (CORS), indem bei jedem API Resultat Access-Control-Allow-Origin: * in den Header gesetzt wird.

URL-Parameter und iframes

(folgt)