DE:OpenRailwayMap/API

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="https://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="https://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="https://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:

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="https://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);

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);

var openrailwaymap = new L.TileLayer('http://{s}.tiles.openrailwaymap.org/standard/{z}/{x}/{y}.png',
{
	attribution: "<a href="https://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);

<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)