API Reference
API Reference

Quickstart

This will get you on the road in no time.

Send our API the addresses of your visits and your fleet. We will return the optimal allocation and order in which you should visit them. Simple and straightforward!

The following is a tiny example of one vehicle and three visits in Vancouver.

curl -L https://routific.com/demo.json | \
curl https://api.routific.com/v1/vrp \
      -X POST \
      -H "Content-Type: application/json" \
      -H "Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1MzEzZDZiYTNiMDBkMzA4MDA2ZTliOGEiLCJpYXQiOjEzOTM4MDkwODJ9.PR5qTHsqPogeIIe0NyH2oheaGR-SJXDsxPTcUQNq90E" \
      -d @-

// Step 1: npm install routific

// Step 2: Initialize client
const Routific = require('routific')

// This is your demo token
const token   = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1MzEzZDZiYTNiMDBkMzA4MDA2ZTliOGEiLCJpYXQiOjEzOTM4MDkwODJ9.PR5qTHsqPogeIIe0NyH2oheaGR-SJXDsxPTcUQNq90E'

const options = {token: token}
const client  = new Routific.Client(options);

// Step 3: Initialize VRP service
const vrp = new Routific.Vrp();

// Step 4: Add your visits
const visits = [
  {
    id: "visit_1",
    location: {name: "Jack Smith", lat: 49.227607, lng: -123.1363085},
    start: "8:00",
    end: "16:00",
    duration: 10
  },
  {
    id: "visit_2",
    location: {name: "Bill Mayers", lat: 49.227607, lng: -123.1363085},
    start: "8:00",
    end: "16:00",
    duration: 10
  },
  {
    id: "visit_3",
    location: {name: "Marc Kuo", lat: 49.227607, lng: -123.1363085},
    start: "8:00",
    end: "16:00",
    duration: 10
  }
]

visits.map((visit) => {
  vrp.addVisit(visit.id, visit);
})

// Step 5: Add your vehicles
const vehicles = [
  {
    id: "vehicle_1",
    start_location: {
        id: "depot",
        lat: 49.2553636,
        lng: -123.0873365
    },
    end_location: {
        id: "depot",
        lat: 49.2553636,
        lng: -123.0873365
    }
  }
]

vehicles.map((vehicle) => {
  vrp.addVehicle(vehicle.id, vehicle);
})

// Step 6: Add traffic speed
vrp.addOption("traffic", "slow");

// Step 7: Send request
client.route(vrp, (err, solution, jobId) => {
  if (err) {
    console.log("An error occurred");
    console.log(err);
  } else if (solution.status == "success") {
    console.log("Solution is:")
    console.log(solution)
  }
})

# Step1: Install the Routific gem: gem install routific

# Step 2: Initialize the client
require 'routific'

# This is your demo token
token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1MzEzZDZiYTNiMDBkMzA4MDA2ZTliOGEiLCJpYXQiOjEzOTM4MDkwODJ9.PR5qTHsqPogeIIe0NyH2oheaGR-SJXDsxPTcUQNq90E'

Routific.set_token(token)
routific = Routific.new

# Step 3: Set your visits
visits = [
  {
    "id" => "order_1",
    "start" => "9:00",
    "end" => "12:00",
    "duration" => 10,
    "location" => {
      "name" => "6800 Cambie",
      "lat" => 49.227107,
      "lng" => -123.1163085,
    }
  },
  {
    "id" => "order_2",
    "start" => "9:00",
      "end" => "12:00",
      "duration" => 10,
      "location" => {
        "name"=> "3780 Arbutus",
        "lat"=> 49.2474624,
        "lng"=> -123.1532338
      }
  },
  {
    "id" => "order_5",
    "start" => "9:00",
    "end" => "12:00",
    "duration" => 10,
    "location" => {
      "name" => "6800 Cambie",
      "lat" => 49.227107,
      "lng" => -123.1163085,
    }
  },
]

visits.each do |visit|
  routific.set_visit(visit["id"], visit)
end

# Step 4: Set your vehicles
vehicles = [
  {
    "id" => "vehicle_1",
    "start_location" => {
      "name" => "800 Kingsway",
      "lat" => 49.2553636,
      "lng" => -123.0873365,
    },
    "end_location" => {
      "name" => "800 Kingsway",
      "lat" => 49.2553636,
      "lng" => -123.0873365,
    },
    "shift_start" => "8:00",
    "shift_end" => "12:00",
  },
  {
    "id" => "vehicle_2",
    "start_location" => {
      "name" => "800 Kingsway",
      "lat" => 49.2553636,
      "lng" => -123.0873365,
    },
    "end_location" => {
      "name" => "800 Kingsway",
      "lat" => 49.2553636,
      "lng" => -123.0873365,
    },
    "shift_start" => "8:00",
    "shift_end" => "12:00",
  }
]

vehicles.each do |vehicle|
  routific.set_vehicle(vehicle["id"], vehicle)
end

# Step 5: Retrieve route
route = routific.get_route()

puts route.status # => "success"
puts route.total_travel_time # => 29

vehicle_routes = route.vehicle_routes

v1_route = vehicle_routes["vehicle_1"]
v2_route = vehicle_routes["vehicle_2"]

# Step 6: Print out route
puts v1_route.length
v1_route.each do |w|
  puts "#{w.location_id}: #{w.arrival_time} ~ #{w.finish_time}"
end

# Step 1: Import http client and set routific vrp url
import urllib3
import json

URL   = "https://api.routific.com/v1/vrp"

# Step 2: Prepare visits
visits = {
    "order_1": {
      "location": {
        "name": "6800 Cambie",
        "lat": 49.227107,
        "lng": -123.1163085
      }
    },
    "order_2": {
      "location": {
        "name": "3780 Arbutus",
        "lat": 49.2474624,
        "lng": -123.1532338
      }
    },
    "order_3": {
      "location": {
        "name": "800 Robson",
        "lat": 49.2819229,
        "lng": -123.1211844
      }
    }
}

# Step 3: Prepare vehicles
fleet = {
    "vehicle_1": {
      "start_location": {
        "id": "depot",
        "name": "800 Kingsway",
        "lat": 49.2553636,
        "lng": -123.0873365
      }
    },
    "vehicle_2": {
      "start_location": {
        "id": "depot",
        "name": "800 Kingsway",
        "lat": 49.2553636,
        "lng": -123.0873365
      }
    }
}

# Step 4: Prepare data payload
data = {
    "visits": visits,
    "fleet": fleet
}

# Step 5: Put together request
# This is your demo token
token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1MzEzZDZiYTNiMDBkMzA4MDA2ZTliOGEiLCJpYXQiOjEzOTM4MDkwODJ9.PR5qTHsqPogeIIe0NyH2oheaGR-SJXDsxPTcUQNq90E'

http = urllib3.PoolManager()
req = http.request('POST', URL, body=json.dumps(data), headers={'Content-Type': 'application/json', 'Authorization': "bearer " + token})

# Step 6: Get route
res = json.loads(req.data.decode('utf-8'))

print res

<?php

// Step 1: Prepare http client and set routific base url

require 'vendor/autoload.php';
use GuzzleHttp\Client;
$url = 'https://api.routific.com/v1/';
$client = new Client([
    'base_uri' => $url,
]);

// Step 2: Prepare visits
$order1 = array(
  "location" => array(
    "name" => "6800 Cambie",
    "lat" => 49.227107,
    "lng" => -123.1163085
));
$order2 = array(
  "location" => array(
    "name" => "3780 Arbutus",
    "lat" => 49.2474624,
    "lng" => -123.1532338
));
$order3 = array(
  "location" => array(
    "name" => "800 Robson",
    "lat" => 49.2819229,
    "lng" => -123.1211844
));
$visits = array(
  "order_1" => $order1,
  "order_2" => $order2,
  "order_3" => $order3
);

// Step 3: Prepare vehicles
$vehicle1 = array(
  "start_location" => array(
    "id" => "depot",
    "name" => "800 Kingsway",
    "lat" => 49.2553636,
    "lng" => -123.0873365
));

$vehicle2 = array(
  "start_location" => array(
    "id" => "depot",
    "name" => "800 Kingsway",
    "lat" => 49.2553636,
    "lng" => -123.0873365
));

$vehicles = array(
  "vehicle_1" => $vehicle1,
  "vehicle_2" => $vehicle2,
);

// Step 4: Prepare data payload
$payload = array(
  "visits" => $visits,
  "fleet" => $vehicles
);

// Step 5: Send request
// This is your demo token
$token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1MzEzZDZiYTNiMDBkMzA4MDA2ZTliOGEiLCJpYXQiOjEzOTM4MDkwODJ9.PR5qTHsqPogeIIe0NyH2oheaGR-SJXDsxPTcUQNq90E';

$response = $client->post('vrp', [
  'json' => $payload,
  'headers' => [
    "Content-type" => "application/json",
    "Authorization" => "bearer " . $token
  ]
]);
echo $response->getBody();
?>

This example is populated with a demo token, so you can copy and paste the above for a working example. Sign up for an account to get your API access token.

The contents of the JSON input and output are shown to the right.

📘

Time formats

All examples in this documentation uses the hh:mm time formats with a 24-hour military notation. Our API also supports UNIX times, which would make dealing with routing across multiple timezones easier.

UNIX time values are defined as number of seconds since epoch time in UTC (00:00:00, January 1st, 1970).

When the input uses UNIX time formats, the output will also returned in UNIX time. When the input is in hh:mm format, so will the output. Note: Unix time stamps are numbers.

Here's an example:

"order_1": {
      "location": {
        "name": "6800 Cambie",
        "lat": 49.227107,
        "lng": -123.1163085
      },
      "start": 1531324800,
      "end": 1531335600,
      "duration": 10
    }

{
  "visits": {
    "order_1": {
      "location": {
        "name": "6800 Cambie",
        "lat": 49.227107,
        "lng": -123.1163085
      },
      "start": "9:00",
      "end": "12:00",
      "duration": 10
    },
    "order_2": {
      "location": {
        "name": "3780 Arbutus",
        "lat": 49.2474624,
        "lng": -123.1532338
      },
      "start": "9:00",
      "end": "12:00",
      "duration": 10
    },
    "order_3": {
      "location": {
        "name": "800 Robson",
        "lat": 49.2819229,
        "lng": -123.1211844
      },
      "start": "8:00",
      "end": "9:00",
      "duration": 10
    }
  },
  "fleet": {
    "vehicle_1": {
      "start_location": {
        "id": "depot",
        "name": "800 Kingsway",
        "lat": 49.2553636,
        "lng": -123.0873365
      },
      "end_location": {
        "id": "depot",
        "name": "800 Kingsway",
        "lat": 49.2553636,
        "lng": -123.0873365
      },
      "shift_start": "8:00",
      "shift_end": "12:00"
    }
  }
}

{
  "status": "success",
  "total_travel_time": 31.983334,
  "total_idle_time": 0,
  "num_unserved": 0,
  "unserved": null,
  "solution": {
    "vehicle_1": [
      {
        "location_id": "depot",
        "location_name": "800 Kingsway",
        "arrival_time": "08:00"
      },
      {
        "location_id": "order_3",
        "location_name": "800 Robson",
        "arrival_time": "08:10",
        "finish_time": "08:20"
      },
      {
        "location_id": "order_2",
        "location_name": "3780 Arbutus",
        "arrival_time": "08:29",
        "finish_time": "09:10"
      },
      {
        "location_id": "order_1",
        "location_name": "6800 Cambie",
        "arrival_time": "09:19",
        "finish_time": "09:29"
      },
      {
        "location_id": "depot",
        "location_name": "800 Kingsway",
        "arrival_time": "09:39"
      }
    ]
  }
}

To play around with a few worked examples we recommend a REST client called Postman. Simply tap the button below to import a pre-made collection of API requests.

Run in Postman