API docs by Redocly

Isochrones API (1.0.3)

License: Magic Lane Terms of Service

Isochrone API calculates the regions that can be reached within a designated time / distance / battery consumption frame from a given location. It returns an area which can be displayed on the map and subsequently used as a geographic filter in location and reverse geocode search API.

Isochrones

Get a geographic area via POST

Get a geographic area which can be reached in a designated time / distance / battery consumption frame.

Authorizations:
ApiKey
Request Body schema: application/json
required

Isochrones parameters

transport
string
Default: "car"
Enum: "car" "lorry" "truck" "pedestrian" "bike"

Route transport mode

type
string
Default: "fastest"
Enum: "fastest" "shortest" "economic" "scenic"

Route type. Accepted values depend on the transport mode; other combinations are rejected as invalid:

  • car / lorry / truck: fastest, shortest, scenic
  • bike: fastest, shortest; economic only with an e-bike profile ( *_pedelec, *_spedelec )
  • pedestrian: fastest, shortest
profile
string
Enum: "road" "cross" "city" "mountain" "road_pedelec" "cross_pedelec" "city_pedelec" "mountain_pedelec" "road_spedelec" "cross_spedelec" "city_spedelec" "mountain_spedelec" "walk" "hike"

transport mode detailed profile (bike/ebike/pedestrian)

departure
required
Array of numbers <float> = 2 items [ items <float > ]

isochrone departure as [longitude, latitude]

ranges
required
Array of integers <= 10 items [ items > 0 ]

range values depending on route type, each greater than 0; at most 10 values:

  • fastest: travel time in seconds
  • shortest: travel distance in meters
  • economic: battery consumption in watt-hours ( e-bikes only )
avoid
Array of strings
Items Enum: "highway" "toll" "ferry" "unpaved" "turnaround" "traffic" "roadblocks" "immutable_roadblocks"

route avoidance options

hillskip
number <float> [ 0 .. 1 ]
Deprecated

Deprecated, use fitness. A value in [0,1], equivalent to fitness = 1 - hillskip; when both are given, hillskip is used

fitness
number <float> [ 0 .. 1 ]
Default: 0.5

Fitness factor [0,1] for tuning the bike / pedestrian routing. Values outside [0,1] are rejected as invalid

geometry
string
Enum: "lineString" "polyline"

Geometry encoding

emergency
boolean

Emergency vehicle mode

locale
string

language code in the same format as for the Routing API, i.e., a lowercase ISO 639-1 code ( e.g., en ) or an ISO 639-2 code ( e.g., eng ), optionally with a region. A code that cannot be parsed is rejected as invalid. The isochrone result contains no translated text

object (vehicle)

vehicle characteristics

profile
string
Enum: "road" "cross" "city" "mountain" "road_pedelec" "cross_pedelec" "city_pedelec" "mountain_pedelec" "road_spedelec" "cross_spedelec" "city_spedelec" "mountain_spedelec" "walk" "hike"

transport mode detailed profile (bike/ebike/pedestrian)

mass
integer >= 0

vehicle mass in kg; for bike transport, the mass of the e-bike. Must not be negative

speed
number <float>

reference speed for the vehicle in m/s. For car, truck and bike it must be greater than 0 when given, otherwise the request is rejected as invalid.

  • car / truck: the vehicle maximum speed
  • bike: the e-bike reference speed, used only with an e-bike profile ( *_pedelec, *_spedelec )
  • pedestrian: not used
height
integer >= 0

vehicle height in cm. Must not be negative

length
integer >= 0

vehicle length in cm. Must not be negative

width
integer >= 0

vehicle width in cm. Must not be negative

axle
integer >= 0

vehicle axle load in kg. Must not be negative

avoid_geofence_areas
Array of strings

Geofence area tokens to avoid

avoid_geofence_anti_areas
Array of strings

Geofence anti-area tokens to avoid

debug
boolean
Default: false

If true, the output will be formatted.

Responses

Response Schema: application/json
object
copyrights
Array of strings
object (errorObject)

returned instead of routes when the request is invalid ( HTTP 400 ) or when no isochrone can be computed ( HTTP 200 )

code
integer

numeric error code, for support and diagnostics. Use reason and details for display

reason
string

short error explanation, e.g., "Invalid input", "No routes available between these locations". May be empty for some errors

details
string

what was wrong with the request. Returned only for invalid requests

Array of objects

one isochrone per requested range value, in the order of ranges. Not returned together with error

Array
distance
integer

the requested range value of this isochrone, in the unit of the range ( seconds, meters or watt-hours, see ranges )

time
integer

the requested range value of this isochrone - same value as distance

bbox
Array of numbers <float> [ items <float > ]

isochrone bounding box [ west, south, east, north ] = [ min longitude, min latitude, max longitude, max latitude ]

Points with Coordinates (object) or Points with Polyline (object)

range polygon coordinates list

One of
type
string
Value: "LineString"
coordinates
required
Array of numbers (path_coords) [ items <float >[ items <float > ] ]

polygon in a form of coordinates array [[ lon, lat ], ...]. Isochrone coordinates carry no altitude

Response Schema: application/json
object
copyrights
Array of strings
required
object (errorObject)

returned instead of routes when the request is invalid ( HTTP 400 ) or when no isochrone can be computed ( HTTP 200 )

code
integer

numeric error code, for support and diagnostics. Use reason and details for display

reason
string

short error explanation, e.g., "Invalid input", "No routes available between these locations". May be empty for some errors

details
string

what was wrong with the request. Returned only for invalid requests

Request samples

Content type
application/json
{
  • "transport": "car",
  • "type": "fastest",
  • "departure": [
    • 8.165682,
    • 49.61167
    ],
  • "ranges": [
    • 1200
    ],
  • "avoid": [
    • "unpaved",
    • "highway",
    • "traffic"
    ],
  • "geometry": "polyline",
  • "locale": "en",
  • "vehicle": {
    • "mass": 1500,
    • "speed": 27.78,
    • "height": 170,
    • "length": 450,
    • "width": 180,
    • "axle": 0
    },
  • "emergency": false,
  • "debug": false
}

Response samples

Content type
application/json
{
  • "info": {
    • "copyrights": [
      • "MagicLane"
      ]
    },
  • "routes": [
    • {
      • "distance": 1200,
      • "time": 1200,
      • "bbox": [
        • 7.96876,
        • 49.47344,
        • 8.4062,
        • 49.74558
        ],
      • "points": {
        • "type": "polyline",
        • "polyline": "}|rnHspop@vG|GzA|PtG?xD}PtGnLrJ??oLsJmLxDmLvG?dV{Yza@mLdVdkAnM|P|A|PpJlL?lLvG?xD_H?mLyDmCxDoCzA}PxDoCtG{YrJmL{AmUsJmL}AmL?yk@bYmU|A}GrJoCtG{Plm@}Ypj@nCxD_HtG|Y?|PrJzPzA|YtG|GxDj^vG~GzAzPnM|P|AlUnM|PtGzYxDvt@{Azk@tGzPrJ~G?|PtG|G?|PxD|Ggs@nCcv@mLyDmLev@oC?lLza@~GpJ|P|Axb@tG??}PlPmCxDmLxa@|G`y@??leCuGhp@zAlUuGj^xDhg@jP|G?j^sJnC?|PfV|GzAmLlP?rJ}GxD|GsJ~G?lLxD|GwGnC?lLrJ?|A}GxD?zAjUtG?|AmLrJlLtG?xDig@nM?zAbtA|^fbA|Aj^jPxt@?fp@vG??ebAwGmL{A}YyDmCzA_HuGk^iSk^yDkU?wfAxDmCzAlLvGlC?nLnM?zAzPvG?zA}GvG|P?zYtG?xD{YnMnC{Ak^tGgkArJkUpJ??}PxDoC?mLyDoC|^mC|AlLpJnC|AzPrJnC?~GpJ?fVzPtG|PlPnCtG|PnMlLxDzY{AlLya@hp@yD{YyDoCoMnC?lLqM|G?nLpM|G}A|PkPzY?~GgVxk@zAhg@vGzYrJnCwGig@vGmU}AkUxD}PtG_HpMig@tGj^tG?{Ak^rJoCvDkUfVk^xD|GsJlU?tfAzA|GrJ?{AekAtGmLxD{YxDoCxD{YxDnC?|PjPzY?lLhSvt@?vfAxDlL?|PvG?}Ak^xDoC?ig@iSgbAhSoC?mLeV?mPyb@}A}PuG_H|A}GtG?tGmLhSlC?{PqJ?wGoL?}GlPk^hS}PxDlUrJ|G?lUtGlLtG?|AlLxD?tGlLxDzYxD?xD|PvD?pMzY?lUsJ|GzAv}@rJmLyDyb@nMmU?{YiS{YeVyt@a\\ig@?_HkPk^?mLoM{YzA}PlP{Ynj@lLlPxk@?jUbY|P?lLtG|P?lUxDnCtGxb@?|YxDlC?lLfVzb@?lLnMnCtGlLpM?tG|PhS?lPmLvD}YvGmLxD?tG{YrJ?zAkUiS?uGlL?zPwG|PqJ~G}A|PuG|GyDoC{A~GiSmUwGnCyDmLqJ?gVyk@sJiy@|A}GnM?xD|G?nLtG?nMoLxD~G?lLlPnC?{b@sJoC|AkUyD_HwG?ya@wt@yD}P|A{YtGoCxD}PzA|PvG?zA{YmP}YxDmC|AmLhSxb@jP~G|AlLdVzY|AzYrJ~GsJzYtGj^tGlLvGmL?}PtGoC?{PuGoCnM}PzAmUrJ{PnMzP?~GbYjUxDhp@uG~G?|PxD?tGzP{Ajg@xD|GtG??ekAyDoCtGmC?}PwDoCtGoCzAig@xDoCuG{YxDoC?}PxDmCyDk^sJmLxDhg@}A|PuG|G?lUuGoCyD~GmPoLoMkU{A{b@yDmCxDoLpJ??{PqJ?qMoL?mLyDmC|A}YoM}GtGoC?}PiSgy@hp@?xD|G{A~GuG?vDzb@pM??oLyDmCxD_HzAk^nM~G{Ahp@tG?xDk^rJ|GzAzb@vG?bYk^tG?zAxb@rJ|P?~GtGlC?nLvG|GhSnC?mLmP_HeVyk@zAmUfV~G?mLwGmLcYoC?w}@oMyt@sJmL?}GeVlLyDoC{Agy@tG}P~[lL|AlLpJ~GvG??mLsJ}PgV}Pya@oCuGkUxDmLxDyt@xDoCtGnL?jUnM|G|^hp@tG?rJ|PlP?zA~Gvd@j^xDlLtG?{AmU{a@{Y{A}PgV?}^k^cY{b@?}GqJ}G?}PwGmL?mUcYw}@|Aw}@lPmUvDnLwDj^pJlCyD~G?|PvG?xDlLtG?zA|PpM??oLsJkUzAip@rJoCzA}PvGnC?|PxD?tGzYrJnLjP?wDip@sJoLzA}Gza@?tGlLuGlL?lLjPmCtGlL?lLvG?zAmLrJ?tGk^yD{YwDoCzA}PnM}Gpj@lCxD~GnMnC?zYtG?vGmLvD?xDlLvG?tGmLzA}PwDmLtGmLrJzPxDzb@tG|GzAfbAvG??gy@tGoCnMlLtG??mLud@kUoM}Y?mLqMk^fV}GtGjU?nLhSjU?}PuGmL?}PuGmLxa@oChS~G?}PoM}Gwd@?iSlLmP?yDlLwDoC}A{YyD_HrJmCxDmUrJnC?_HxDmC~[|GxD~GtG?|A_HtG~GrJ??oLsJ}G?}GuGoL?mLcYlLyDnL{a@_H?~GwDlCwGk^sJ{PwDk^tGoCxDlLnM??mLyD?iS{YuG?qMoLya@ebAcYmL{A}YtGmC?}YmPnC{A}GuG??|GyDnC}AmLqJmLwGkg@kP{b@?mLtG}GxDig@nMoC?mLyD_HkP?}AkUuGoCxD}P?ip@wG?yDfbAwD|GsJ??~GsJ|G{AlUa\\jUsJ?uGlLmPmCuG|GiS?{A~GyD_HzAmLmPgbAuGmLxD}P?kUuGmU}A{YxD}GtG?rJoLhS}GpMmLtG}PsJoCsJ|PyD?uGlLyDmCoMzPuG}GzAsaBuGip@dV}G?mLyDoC|A{YxDoC}AkUvGyt@}A}PuG?}Azb@wD|G{a@|PoMlU{AzYvD|PeVzYyDmL?wt@rJoC?mLsJ_HtG}PkPkUiS??j^jPzY{A|PsJ?mm@{b@yDnCuGmL?mLoM_HvDmLjS??mLcYoCiSzb@sJnCwd@kg@uG?yDyb@xD}PyDk^zA{YuG{b@tGoC?mLoMmUhS}G?mLsJ_HeVnCiS{b@wG?wD|Ywd@_H?yb@mPyt@uG}G?{b@tG}G|AmUtG}G?oLtG{Pza@kg@dVmCfVmUnj@nCfs@hg@xD}GyDmLuG?a\\}YcYmL{^?sJ~GcYoC?lLya@zb@mPxb@uGnCyDj^yDnC}A|PoMlLyDj^}^xb@_\\~GyD_HrJkUxD?zA{YuG?cYxk@yDoLnM{P?kg@oM?{Azb@qMnC{A}PsJ?uGk^?}PmP{Y{A{b@xDoCzAkUsJnC{A}PsJoCrJ`fBsJ|PsJoC{A~GuG??lLbYoCjPkUvG|PzAzYsJlLuG?uGlLwG?yD|PoM?cYzY?|PtGnC|AzYrJ|GqMnCwDzYwG~G?lLxDnCyDlC?nLxDlC{A~GsJ?}A|GoMoC{A~GiS{YoMlC?{YsJ{b@bYmL?mLgVnC{A_HwG?{AlLgV}G{A|Pmm@oCyDlLuGmCmm@zPmm@?yD}GcY?mPlL{A}PwG?yDlLcY~G?lLdv@?zA}GvG?tGzPoM~G?lLvd@nCpJjUvG}GzAmLhS?rJ_HxD~GzAtfAyD|GqgA|PuGmC?oLsJ??~GuGlLoM?wG}GvG}P?mLiS}YkSnC?lLpMnC}A|GyD??lLvG?zA~GeV|P?jUpJnCuGnC?zYuGlU?zYsJnC?lLhS|G?zb@mPlC?nLlPlCyDnLuG?zAjUrJnC?hp@yD|G?lUuGzPgV?yD~G?lL`\\oCxD~G}AdbAiS?xD|Y{AlLmP?oMmL}AlCoM{P{AlCyDk^sJ?{A~GyDoCzAk^yDoC|A}PwGsoAyD_H|A}PuG}GyDnCnM~nBzAvfAyD|GqJ?cY|PoMoC}AnLuG?}A|GeVlLa\\oC|A|Yvd@_HjP}PlPmCnMmLxa@oLxD~GxDrxAuGjUyDzk@rJoCnMw}@?mUyDmC?ekAhSlCxDnLrJ?~[zPvGnL?lLnMoCpJjUpMz}G}Ahp@iS?sJlLwDk^wG?uG|PmPoCsg@gy@yDnCoMmUuGnC?|PtG?tGlLrJ?zA|PlP|GnMzYy~@lLsJ|PyD??lLtG?vGmLbY}Gxa@?rJ_HzA~GrJlC?nLdVxb@{Aj^yDnC?lLxDnC{AjUvDnCoMdtA|Axk@sJ|GyDlLgVlLwDnLgVzPcYyb@mPoCwD}G}AmUoM}P}AnCuGmLsJlC{A}GsJoCoM}PuG?vDzb@jS?vD~GlP?|A|GtG?xD~G?h^bY~GtG|G?~GsJ|GyD|PuGoCgs@j^yD|PyDoCeVnLuGoL?}GwG??xk@"
        }
      }
    ]
}