Getting the Task Result

The task's result can be accessed at /v1/tasks/{task_id}/result. If the task has not yet been completed, this returns a status of 404 Not Found.

URL Parameters

  • {task_id} - Retrieve the result of the task with this task_id.

Query Parameters

  • wait=1 - Optional. Wait for the result to become available.
  • cancel_on_disconnect=1 - Optional. If the client disconnects while waiting on a response from the server, cancel the task. Only applies if wait=1 is specified. This parameter can be used to cancel a task when the client disconnects or crashes, preventing the task from being orphaned and contributing to usage limits on the server.
  • aggregate=1 - Optional. Return a problem_aggregates object summarizing the task result, instead of the full response. Only applies to tasks that would return a problem_response under normal operation, such as evaluate.

Waiting

By including the wait=1 query parameter, the task's call returns after either:

  • The task is completed - returning the result.
  • 15 seconds have elapsed - 302 redirecting to the same location.

If wait=1 is included in any of the task-starting methods, the above applies; however, the first redirect will be to the /v1/tasks/{task_id}/result?wait=1 location.

GET https://routecloud.telogis.com/v1/tasks/v4AQjZm1eUW0gFnECtxqAw/result?wait=1 HTTP/1.1
X-Telogis-Session-Id: e938d41c-d519-4f07-b0a9-26d4745d6e74
Accept: application/json

After a 15 second timeout, the following redirect is returned:

HTTP/1.1 302 Found
Location: tasks/v4AQjZm1eUW0gFnECtxqAw&wait=1
Content-Type: application/json

{
  "task_id": "v4AQjZm1eUW0gFnECtxqAw",
  "started_time": "2017-11-23T12:42:23.839Z",
  "wait_url": "tasks/v4AQjZm1eUW0gFnECtxqAw/result?wait=1",
  "status_url": "tasks/v4AQjZm1eUW0gFnECtxqAw"
}

This repeats until the task has completed. Some HTTP clients limit the number of redirects they will follow, so you may need to repeat calls to this location if the redirect limit is reached. Other clients may have a global timeout configured that may interrupt the redirect operations if the task takes a long time. If this is the case it is better to disable automatic redirects in the client and manually call the redirect url until the result is available.

Once the task has completed, the result is returned.

HTTP/1.1 200 OK
Content-Type: application/json

{ "routes": [ "..." ], "unrouted_jobs": [ "..." ] }

Canceling on Disconnect

The cancel_on_disconnect=1 query parameter causes the task to be canceled when the client disconnects. This helps API users stay within their usage limits. This is particularly useful if calling the RouteCloud API from a browser. If the browser is closed, there is no need to continue running the task.

Status Codes

  • 200 - Success.
  • 302 - If wait=1 was provided and the task result is not yet available, a redirect is sent instead of a normal result every 15 seconds to refresh the HTTP timeout. See Retrieving API Results.
  • 401 - Authentication required.
  • 404 - If wait=1 was not specified, the result is not yet available, or no task exists with the specified task_id.
  • 409 - The task was canceled or failed and will never give a result.

Code Examples

C#

/* wait_for_result.csx
 * To run:
 *   1. Install dotnet script: https://github.com/filipw/dotnet-script#installing
 *   2. dotnet script wait_for_result.csx
 */
#r "nuget: Newtonsoft.Json, 12.0.2"
using System.Net.Http;
using System.Net.Http.Headers;
using System.Web;
using Newtonsoft.Json.Linq;

// Instantiate a http client with automatic redirects disabled as we'll be handling
// the redirect response directly
var httpClient = new HttpClient(new HttpClientHandler{
	AllowAutoRedirect = false
});

// Setup authentication for the RouteCloud API
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
	scheme: "Basic",
	parameter: Convert.ToBase64String(Encoding.ASCII.GetBytes("youraccount%3Amain:password")));

var baseUri = new Uri("https://routecloud.telogis.com/v1/");

// Post a build to RouteCloud
var postContent = new StringContent(await File.ReadAllTextAsync("quick_start_build.json"), Encoding.UTF8, "application/json");
var postResult = await httpClient.PostAsync(new Uri(baseUri, "build"), postContent);
var buildResult = JToken.Parse(await postResult.Content.ReadAsStringAsync());
Console.WriteLine($"Response from build endpoint: {buildResult.ToString()}");

// Wait for the result of the build from RouteCloud
var taskUriBuilder = new UriBuilder(new Uri(baseUri, (string)buildResult["wait_url"]));
var query = HttpUtility.ParseQueryString(taskUriBuilder.Query);
query["cancel_on_disconnect"] = "1"; // Cancel task if we disconnect/crash while waiting for a response from the server
taskUriBuilder.Query = query.ToString();
var taskResultUri = taskUriBuilder.Uri;
var taskResult = await httpClient.GetAsync(taskResultUri);
while(taskResult.StatusCode == System.Net.HttpStatusCode.Redirect) {
	taskResult = await httpClient.GetAsync(taskResultUri);
}

Console.WriteLine($"Task result: {await taskResult.Content.ReadAsStringAsync()}");

See Also