Teekonnaarvutuse juhend

Praktiline juhend näidetega: teekonna arvutamine, vahepunktid, geomeetria ja väljundvormingud.

Endpoint ja meetod

Teedevõrk katab Eesti, Läti ja Leedu (üks Balti graaf): nt Riia → Vilnius töötab. Ainult GET; POST annab 400.

Parameetrite koondtabel

curl "https://pump.elemroot.com/LogismeRouting/SURRouting?pref=Fastest&start=660545.95,6476102.22&end=553474.28,6583771.55&srs=EPSG:3301&output=json&noRouteGeom=false&key=docs_382d376eaaa6d004b7b93b7d"

Esimene päring

curl "https://pump.elemroot.com/LogismeRouting/SURRouting?pref=Fastest&start=22.513265,58.265563&end=23.233129,58.605584&output=json&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "RouteSummary": {
      "BoundingBox": [
        { "e": 22.512399678574166, "n": 58.26509890506477 },
        { "e": 23.233128562435795, "n": 58.60563260378001 }
      ],
      "TotalTime": "P0Y0M0DT0H48M35.080S",
      "TotalDistance": "62973.600000000006"
    }
  }
]

Teejoone geomeetria

curl "https://pump.elemroot.com/LogismeRouting/SURRouting?pref=Fastest&start=22.513265,58.265563&end=23.233129,58.605584&output=json&noRouteGeom=false&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "RouteSummary": { "TotalTime": "P0Y0M0DT0H48M35.080S", "TotalDistance": "62973.600000000006", "BoundingBox": [ ... ] },
    "RouteGeometry": {
      "LineString": [
        { "n": 58.265563, "e": 22.513265 },
        { "n": 58.265921552298856, "e": 22.512801561977046 },
        { "n": 58.2658073706609, "e": 22.51254892386472 }
      ]
    }
  }
]

LineString on teejoone punktid järjekorras stardist sihtpunktini ({n, e} = põhi, ida).

Vahepunktid (via)

Lisa via-punkte (tühikuga eraldatud E,N punktid):

curl "https://pump.elemroot.com/LogismeRouting/SURRouting?pref=Shortest&start=22.513265,58.265563&via=22.8,58.45&end=23.233129,58.605584&output=json&key=docs_382d376eaaa6d004b7b93b7d"

[
  { "RouteSummary": { "TotalDistance": "28189.0", "TotalTime": "P0Y0M0DT0H22M17.770S", "BoundingBox": [ ... ] } },
  { "RouteSummary": { "TotalDistance": "34742.1", "TotalTime": "P0Y0M0DT0H31M47.620S", "BoundingBox": [ ... ] } }
]

Koordinaatide järjekord

NB: sisendi E,N on vastupidine geokodeerimise/pöördgeo q-le (lat,lon).

XML (OpenLS XLS)

Vaikimisi (output=xml) tagastatakse OpenLS XLS XML:

<?xml version='1.0' encoding='UTF-8'?>
<XLS version="1.1" xmlns="http://www.opengis.net/xls" xmlns:gml="http://www.opengis.net/gml">
  <ResponseHeader/>
  <Response version="" requestID="">
    <DetermineRouteResponse>
      <RouteSummary>
        <TotalTime>P0Y0M0DT0H48M35.080S</TotalTime>
        <TotalDistance value="62973.600000000006"/>
        <BoundingBox>
          <gml:pos>58.26509890506477 22.512399678574166</gml:pos>
          <gml:pos>58.60563260378001 23.233128562435795</gml:pos>
        </BoundingBox>
      </RouteSummary>
      <RouteGeometry>
        <gml:LineString>
          <gml:pos>58.265563 22.513265</gml:pos>
          <gml:pos>58.265921552298856 22.512801561977046</gml:pos>
        </gml:LineString>
      </RouteGeometry>
    </DetermineRouteResponse>
  </Response>
</XLS>

Geomeetria üldistamine

Teejoone geomeetriat saab üldistada (lihtsustada):

curl "https://pump.elemroot.com/LogismeRouting/SURRouting?pref=Fastest&start=22.513265,58.265563&end=23.233129,58.605584&output=json&noRouteGeom=false&maxDev=10&maxPoints=100&key=docs_382d376eaaa6d004b7b93b7d"

ESRI-liides (ArcGIS)

Endpoint /ESRIRouting on ArcGIS Network Analyst stiilis liides. Peatuspunktid antakse parameetriga stops (ArcGIS FeatureSet JSON või lihtsüntaks x1,y1;x2,y2), vastus on ArcGIS Directions JSON. f=json on kohustuslik.

curl -G "https://pump.elemroot.com/LogismeRouting/ESRIRouting" \
  --data-urlencode 'stops={"features":[{"geometry":{"x":635541.4,"y":6583331.7,"spatialReference":{"wkid":3301}},"attributes":{}},{"geometry":{"x":638218.2,"y":6589326.7,"spatialReference":{"wkid":3301}},"attributes":{}}]}' \
  --data-urlencode "outSR=3301" \
  --data-urlencode "impedanceAttributeName=Distance" \
  --data-urlencode "directionsLanguage=et_EE" \
  --data-urlencode "directionsLengthUnits=esriNAUKilometers" \
  --data-urlencode "outputGeometryPrecisionUnits=esriMeters" \
  --data-urlencode "outputGeometryPrecision=0.7" \
  --data-urlencode "ignoreInvalidLocations=true" \
  --data-urlencode "returnDirections=true" \
  --data-urlencode "returnRoutes=false" \
  --data-urlencode "findBestSequence=false" \
  --data-urlencode "startTime=1307001600000" \
  --data-urlencode "key=docs_382d376eaaa6d004b7b93b7d" \
  --data-urlencode "f=json"

{
  "directions": [
    {
      "summary": {
        "envelope": { "xmin": 635541.4, "ymin": 6583322.45, "xmax": 638218.2, "ymax": 6589326.7,
                      "spatialReference": { "wkid": 3301 } },
        "totalDriveTime": 14.0415,
        "totalTime": 14.0415,
        "totalLength": 11.4213
      },
      "features": [
        { "compressedGeometry": "+3+1q5u0+iqn3b+u-s",
          "attributes": { "ETA": 1307001600000, "length": 0.0136, "maneuverType": "esriDMTDepart",
                          "time": 0.0817, "text": "1. sihtpunkt" } },
        { "compressedGeometry": "+3+1q5uu+iqn2f-p7-r1+o-d…",
          "attributes": { "ETA": 1307001604900, "length": 11.3988, "maneuverType": "esriDMTTurnRight",
                          "time": 13.9063, "text": "Sõida 11,4 km." } }
      ]
    }
  ],
  "messages": []
}

Parameetrid (* = kohustuslik; tabel genereeritakse OpenAPI-YAML-ist):

Osa ArcGIS-parameetreid eiratakse (accumulateAttributeNames, useHierarchy, outputLines, preserveFirstStop, preserveLastStop, directionsStyleName, useTimeWindows, returnBarriers-pere väärtusega false); neid võib päringus hoida ühilduvuse huvides. Seevastu barriers, polylineBarriers, restrictUTurns, restrictionAttributeNames, attributeParameterValues, directionsTimeAttributeName annavad 400 („isn't supported").

Peatuste järjekorra optimeerimine (findBestSequence=true)

Mitme peatusega marsruudil võib teenus peatuste järjekorra ise optimeerida (rändkaupmehe ülesanne, TSP): algus- ja lõpp-peatus jäävad paigale, vahepealsed järjestatakse ümber nii, et kogu ring oleks lühim/kiireim (vastavalt impedanceAttributeName-ile). Vastus (juhised, pikkus, aeg) käib optimeeritud järjestuse kohta; uue järjekorra saad kätte returnStops=true-ga: stops[].ObjectID on sisendjärjekord, Sequence uus järjekord, Cumul_Time kumulatiivne sõiduaeg sekundites.

curl -G "https://pump.elemroot.com/LogismeRouting/ESRIRouting" \
  --data-urlencode 'stops={"features":[{"geometry":{"x":659000,"y":6473000,"spatialReference":{"wkid":3301}},"attributes":{}},{"geometry":{"x":664500,"y":6470500,"spatialReference":{"wkid":3301}},"attributes":{}},{"geometry":{"x":661500,"y":6472500,"spatialReference":{"wkid":3301}},"attributes":{}},{"geometry":{"x":658000,"y":6469500,"spatialReference":{"wkid":3301}},"attributes":{}}]}' \
  --data-urlencode "outSR=3301" --data-urlencode "impedanceAttributeName=Distance" \
  --data-urlencode "directionsLanguage=et_EE" --data-urlencode "directionsLengthUnits=esriNAUKilometers" \
  --data-urlencode "outputGeometryPrecisionUnits=esriMeters" --data-urlencode "ignoreInvalidLocations=true" \
  --data-urlencode "returnRoutes=false" --data-urlencode "findBestSequence=true" --data-urlencode "returnStops=true" \
  --data-urlencode "key=docs_382d376eaaa6d004b7b93b7d" --data-urlencode "f=json"

{
  "directions": [ { "routeId": 1, "routeName": "Location 1 - Location 4",
                    "summary": { "totalLength": 21.1842, "totalTime": 33.7405, … }, "features": [ … ] } ],
  "stops": {
    "features": [
      { "attributes": { "ObjectID": 1, "Sequence": 1, "Cumul_Time": 0,       "Status": 0 }, "geometry": { "x": 659000, "y": 6473000 } },
      { "attributes": { "ObjectID": 2, "Sequence": 3, "Cumul_Time": 1067.39, "Status": 0 }, "geometry": { "x": 664500, "y": 6470500 } },
      { "attributes": { "ObjectID": 3, "Sequence": 2, "Cumul_Time": 495.46,  "Status": 0 }, "geometry": { "x": 661500, "y": 6472500 } },
      { "attributes": { "ObjectID": 4, "Sequence": 4, "Cumul_Time": 2024.43, "Status": 0 }, "geometry": { "x": 658000, "y": 6469500 } }
    ],
    "spatialReference": { "wkid": 3301 }
  }
}

Peatuste järjekord muutus 1→2→3→4 pealt 1→3→2→4 peale ja ring lühenes 1,4 km võrra. Ilma returnStops-ita on optimeeritud järjekord vastuses kaudselt (juhiste tekst „N. sihtpunkt").

Muud liidesed

Lisaks lühi-URL REST- ja ESRI-liidesele pakub teenus:

Millal mida kasutada

Sagedasemad ülesanded ja neile vastav liides/parameetrikombinatsioon. Kõik read on elusalt kontrollitud.

Veakäsitlus

/SURRouting vea keha (400/500) on Tomcati HTML-vealeht, sõnum on pealkirjas (<h1>HTTP Status 400 - Missing parameter "pref"</h1>). /ESRIRouting vead on JSON {"error":{"message":"…","status":400}}; ka „marsruuti ei leitud" ja teedevõrgu ristkülikust väljas punkt (Coordinates of destination … are out of range) on ESRI-l 400, mitte 500.

Näited galeriis

• Teekonnaarvutus kahe punkti vahel
• Teekonnaarvutuse valikud ja vahepunktid
• Mitme peatusega teekonnaarvutus
• Lähima esinduse leidmine
• Teekonna optimeerimine
• Ringsõit läbi kõigi punktide
• Kaugusmaatriks
• Lähimad sihtkohad liigutatavast punktist