Schedules

Index Action

Computing a schedule takes usually a couple of seconds, but may also take longer depending on the input parameters. Instead of letting the web client wait until the server has completed the computation, the server immediately returns a ResponseId. This MD5 hash can be used in another request to the show-action to check the progress.

If an error occurs that can immediately be found while parsing the input, then the output is a well-known ApiException. However, if the error occurs later, maybe during the computation of the schedule, then the first request to the show-action yields an error statement.

Since in this controller the input paramters are more complex than in other controllers, the input is passed as a single parameter json, that contains the following JSON formatted input. Additionaly one can change the network by setting the paramter network_id.

Parameter Abbreviation Data Type
network_id nid INTEGER

JSON Input

{
  "StartPoint": <GEOLOCATION>,
  "EndPoint": <GEOLOCATION>,
  "StartTime": <DATETIME>,
  "EndTime": <DATETIME>,
  "Categories": [{
    "Id": <INTEGER>,
    "MaxVisits": <INTEGER>,
    "Score": <INTEGER [0..100]>
  }, ...]
}

JSON Output

{
  "ResponseId": <MD5_HASH>,
  "StatusCode": <INTEGER>
}

Example Requests

As with all parameters also the json parameter can be sent as GET parameter. However, due to the limitations of the URL length it is highly recommended to pass the json parameter in the POST section for this request.

http://api.ostar.inf.unibz.it/0/schedules
POST-DATA:
json={
  'StartPoint': '11.35820031,46.49679698',
  'EndPoint': '11.3507545,46.49862121',
  'StartTime': '2012-12-21T10:00:00%2B01:00',
  'EndTime': '2012-12-21T12:00:00%2B01:00',
  'Categories': [{
      'Id': 8,
      'MaxVisits': 2,
      'Score': 60
    },{
      'Id': 9,
      'MaxVisits': 2,
      'Score': 60
    }]
}

RESPONSE:
{
  "ResponseId": "13be9a2198611564658d69e2d9f1c404",
  "StatusCode": 0
}

Show Action

Differently to other show-actions this one does not take a integer number in the URL as parameter, but a MD5 hash. This ResponseId was earlier obtained by calling the index action. See below the example request.

JSON Output

{
  "FinalSchedule": <BOOLEAN>,
  "Schedules": [
    {
      "StartTime": <DATETIME>,
      "EndTime": <DATETIME>,
      "Score": <INTEGER>,
      "Itinerary": [
        {
          "Type": "Edge",
          "Id": <INTEGER>,
          "StartTime": <DATETIME>,
          "EndTime": <DATETIME>,
          "TravelTime": <INTEGER (in seconds)>
        },
        {
          "Type": "Poi",
          "Id": <INTEGER>,
          "StartTime": <DATETIME>,
          "EndTime": <DATETIME>,
          "VisitTime": <INTEGER (in seconds)>
        }
      ]
    }
  ],
  "StatusCode": <INTEGER>
}

If the schedule computation is not yet finished the output looks like this:

{
  "FinalSchedule": false,
  "Schedules": null,
  "StatusCode": <INTEGER>
}

Example Request

Please note, that unlike the other example requests this particular request won’t succeed, since the MD5 hash has some random ingredients and so the abvoe sample request won’t yield the same MD5 hash as stated here.

curl "localhost:8080/0/schedules/13be9a2198611564658d69e2d9f1c404"

{
  "Schedules": [
    {
      "StartTime": "2012-12-21T10:00:00+01:00",
      "EndTime": "2012-12-21T11:48:49+01:00",
      "Score": 335,
      "Itinerary": [
        {
          "TravelTime": 17,
          "Id": 2000263,
          "StartTime":
          "2012-12-21T10:00:00+01:00",
          "EndTime": "2012-12-21T10:00:17+01:00",
          "Type": "Edge"
        },
        ...
        {
          "VisitTime": 1864,
          "Score": 93,
          "Id": 201,
          "StartTime": "2012-12-21T10:02:01+01:00",
          "EndTime": "2012-12-21T10:33:05+01:00",
          "Type": "Poi"
        },
        ...
        {
          "TravelTime": 62,
          "Id": 2002621,
          "StartTime": "2012-12-21T11:47:47+01:00",
          "EndTime": "2012-12-21T11:48:49+01:00",
          "Type": "Edge"
        }
      ]
    }
  ],
  "FinalSchedule": true,
  "StatusCode": 0
}