Routing-API-Referenz

Die SmartMaps Routing API bietet Funktionen zur Berechnung von Routen, Distanzmatrizen, optimierten Touren und Isochronen. Sie ermöglicht es Ihnen, die besten Wege zwischen Orten zu finden, Reisezeiten und Entfernungen zu berechnen, mehrstufige Touren zu optimieren und erreichbare Gebiete anhand von Zeit oder Entfernung zu bestimmen.

Endpunkte

Route

Berechnet eine Route zwischen zwei oder mehr Koordinaten mit optionalen Zwischenpunkten.

URL: https://www.yellowmap.de/api_rst/v2/geojson/route

Methode: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "ROUTE",
    "isoLocale": "de-DE",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.362124135917012, 49.01062717784205]
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.437334508302376, 49.004997061308316]
      },
      "properties": {}
    },
    {
      "type": "Feature", 
      "geometry": {
        "type": "Point",
        "coordinates": [8.381356011960742, 48.99103162515999]
      },
      "properties": {}
    }
  ]
}

Parameter:

Parameter	Typ	Beschreibung
`type`	string	Gibt den GeoJSON-Typ an.
`routingparams.type`	string	Muss auf `"ROUTE"` gesetzt werden.
`routingparams.isoLocale`	string	Legt die Sprache der Routenanweisungen fest.
`routingparams.coordFormatOut`	string	Koordinatenformat der Ausgabekoordinate. Unterstützte Werte: `"SUPERKONFORM"`, `"MERCATOR"`, `"GEODECIMAL"`, `"GEODECIMAL_POINT"`.
`routingparams.speedProfile`	string	Geschwindigkeitsprofil für die Routenberechnung. Unterstützte Werte: `"FAST"`, `"SLOW"`, `"BICYCLE"`, `"PEDESTRIAN"`.
`routingparams.routingTimeMode`	string	Legt fest, wie die Zeit berechnet wird. Unterstützte Werte: `"ARRIVAL"`, `"DEPARTURE"`.
`authentication.channel`	string	Eine beliebige Zeichenkette zur Protokollierung und Identifizierung der Anfrage.
`crs.type`	string	Gibt den Typ des Koordinatenreferenzsystems an.
`crs.properties.name`	string	Gibt den Namen des Koordinatenreferenzsystems an.
`features`	array	Array von GeoJSON-Features, die die Routenpunkte repräsentieren. Der erste Punkt ist der Startpunkt, gefolgt von Zwischenpunkten, der letzte Punkt ist das Ziel.

Antwort:

Die Antwort ist eine GeoJSON-FeatureCollection, die die berechnete Route und die Wegbeschreibung enthält.

Matrix

Berechnet die Entfernung und Reisezeit zwischen mehreren Koordinaten und einer Koordinate.

URL: https://www.yellowmap.de/api_rst/v2/geojson/route

Methode: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "MATRIX",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.331952086718967, 49.01603149080641]
      },
      "properties": {
        "type": "StartPoint"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [8.391008912120817, 49.02121007355168],
          [8.38688866848814, 48.996438064932285],
          [8.364227328508337, 49.00139345263399]
        ]
      },
      "properties": {}
    }
  ]
}

Parameter:

Ähnlich wie beim Route-Endpunkt, mit folgenden Unterschieden:

Parameter	Typ	Beschreibung
`routingparams.type`	string	Muss auf `"MATRIX"` gesetzt werden.
`features[0]`	object	Gibt den Startpunkt an.
`features[1]`	object	Gibt die Endpunkte als `MultiPoint`-Geometrie an.

Antwort:

Die Antwort ist eine GeoJSON-FeatureCollection, die die Entfernung und Reisezeit zwischen dem Startpunkt und jedem Endpunkt enthält.

Eine vollständige Anfrage/Antwort finden Sie im Beispiel Distanzmatrix.

Trip

Berechnet die optimale Anfahrtsroute zwischen einem Startziel und mehreren Zielen.

URL: https://www.yellowmap.de/api_rst/v2/geojson/route

Methode: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "TRIP",
    "routingRoundTrip": false,
    "isoLocale": "de-DE",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [8.378608601097369, 49.00882560981356],
          [8.45553610527237, 49.00139345263399]
        ]
      },
      "properties": {}
    }
  ]
}

Parameter:

Ähnlich wie beim Route-Endpunkt, mit folgenden Unterschieden:

Parameter	Typ	Beschreibung
`routingparams.type`	string	Muss auf `"TRIP"` gesetzt werden.
`routingparams.routingRoundTrip`	boolean	Bei `true` ist der Startpunkt gleichzeitig das endgültige Ziel.
`features`	array	Übergabe von mehr als einem Punkt als `MultiPoint`-Geometrie. Der erste Punkt ist der Startpunkt, alle weiteren Punkte sind Zwischenpunkte.

Antwort:

Die Antwort ist eine GeoJSON-FeatureCollection, die die optimierte Route zwischen dem Startpunkt und den Zwischenpunkten enthält.

Isochrone

Berechnet das Gebiet, das durch eine gegebene Reisezeit oder Reiseentfernung abgedeckt wird.

URL: https://www.yellowmap.de/api_rst/v2/geojson/route

Methode: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "ISOCHRONE",
    "timeInMinutes": 40,
    "distanceInMeters": null,
    "isochroneGrid": "100",
    "speedProfile": "FAST",
    "coordFormatOut": "GEODECIMAL_POINT",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": "TEST123"
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.34566116333008, 48.9786396543091]
      },
      "properties": {}
    }
  ]
}

Parameter:

Ähnlich wie beim Route-Endpunkt, mit folgenden Unterschieden:

Parameter	Typ	Beschreibung
`routingparams.type`	string	Muss auf `"ISOCHRONE"` gesetzt werden.
`routingparams.timeInMinutes`	number	Zeit in Minuten für die Isochronen-Berechnung. Kann Werte von >0 bis 60 annehmen. Entweder `timeInMinutes` oder `distanceInMeters` kann übergeben werden.
`routingparams.distanceInMeters`	number	Entfernung in Metern für die Isochronen-Berechnung. Entweder `timeInMinutes` oder `distanceInMeters` kann übergeben werden.
`routingparams.isochroneGrid`	string	Legt die Feinheit des berechneten Polygons fest. Je höher der Wert, desto feiner das Polygon. Kann Werte von 35 bis 150 annehmen.
`features`	array	Ein einzelner Punkt, der als Startpunkt für die Isochronen-Berechnung dient.

Antwort:

Die Antwort ist eine GeoJSON-FeatureCollection, die das Isochronen-Polygon und den Ursprungspunkt enthält.

Eine vollständige Anfrage/Antwort finden Sie im Beispiel Isochrone.

Map Matching

Gleicht eine Reihe von GPS-Punkten mit dem Straßennetz ab und gibt die abgeglichene Route als GeoJSON zurück.

URL: https://www.yellowmap.de/api_rst/v2/geojson/route

Methode: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "MATCH",
    "isoLocale": "de-DE",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL",
    "channel": ""
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC::CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [8.439352102315755,49.02147677180509],
          [8.438526428732251,49.02110387755915]
        ]
      }
    }
  ]
}

Parameter:

Ähnlich wie beim Route-Endpunkt, mit folgenden Unterschieden:

Parameter	Typ	Beschreibung
`routingparams.type`	string	Muss auf `"MATCH"` gesetzt werden.
`features`	array	Muss ein einzelnes `MultiPoint`-Feature sein, das alle abzugleichenden GPS-Punkte enthält.
`features[n].geometry.type`	string	Muss `"MultiPoint"` sein.
`features[n].geometry.coordinates`	array	Koordinaten der abzugleichenden GPS-Punkte.

Antwort:

Die Antwort ist eine GeoJSON-FeatureCollection, die die abgeglichene Route enthält:

properties.distance (number): Gesamtentfernung der abgeglichenen Route in Metern.
properties.duration (number): Dauer in Sekunden.
features[n].geometry (LineString): Koordinaten der abgeglichenen Route.
features[n].properties.matchDestinations (array): Details zu jedem Eingabepunkt:
isMatched: Ob der Punkt dem Straßennetz zugeordnet werden konnte.
distance: Entfernung vom ursprünglichen Punkt zum abgeglichenen Punkt in Metern.
inPoint: Ursprünglicher GPS-Punkt.
matchedPoint: Auf das Straßennetz eingerasteter Punkt.

Eine vollständige Anfrage/Antwort finden Sie im Beispiel Map Matching.

Authentifizierung

Um die SmartMaps Routing API zu nutzen, benötigen Sie einen API-Key zur Authentifizierung. Der API-Key wird als URL-Parameter mit dem Namen apiKey übergeben.

https://www.yellowmap.de/api_rst/v2/geojson/route?apiKey=[INSERT API-KEY]

Fehlerbehandlung

Die API kann folgende HTTP-Statuscodes zurückgeben:

400 Bad Request: Die Anfrage wurde fehlerhaft gestellt, z. B. aufgrund eines Syntaxfehlers im JSON.
412 Precondition Failed: Der API-Key wurde nicht angegeben.

Beispiel

Hier ist ein Beispiel für eine Anfrage zur Berechnung einer Route:

curl --location --request POST 'https://www.yellowmap.de/api_rst/v2/geojson/route?apiKey=[INSERT API-KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "ROUTE",
    "isoLocale": "de-DE",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.362124135917012, 49.01062717784205]
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.437334508302376, 49.004997061308316]
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.381356011960742, 48.99103162515999]
      },
      "properties": {}
    }
  ]
}'