Importing Routes¶

Importing a route requires using our asynchronous import route API. The API will check for possible errors in the input and then return a transaction id. This transaction id should be used to check for the import status of that route. A route is not successfully imported until the import status API returns a successful response. Errors are returned as soon as possible, but network latency may prevent all error detection from happening at the time of route import (e.g. duplicate request to send the same route) so it is possible for error to come back from the import status API.

The following is a sample pseudocode to import a route.

Important

In order for a driver to receive a route, it must be activated after a successful import or you can set the activate_after_successful_import flag to true during route creation.

response = POST_route(dc_id, route)
if is_http_status_202(response):
  txid = response.json()["data"]["txid"]

  while True:
    sleep(1)
    import_status_response = GET_route_import_status(dc_id, txid)
    if is_http_status_202(import_status_response):
      continue
    elif is_http_status_200(import_status_response):
      # Successfully imported the route
      route_id = import_status_response.json()["data"]["route_id"]
      break
    else:
      # Do error handling here.
else:
  # Do error handling here.

Models¶

The models used by the import route endpoint are drastically different from the ones described in models documentation. Here are the models needed by the import route endpoint for a successful import.

Importable Route¶

Property	Type	Required	Description
route	Route	true	The route information that is being imported

Route¶

Note

You can control the start and end location of a route by specifying a warehouse. If you want to define different start and end locations for a route, use the start_warehouse and end_warehouse parameters. If a warehouse or start_warehouse and end_warehouse are not supplied, Foxtrot will use the default warehouse location for that DC (Under Account > Settings > DC > Warehouse).

Important

Route id has to be globally unique. You cannot have multiple routes with the same id.

Important

If you are not sure the driver has been imported into Foxtrot, pass in the driver parameter and the driver will be imported if the driver does not exist. driver_id and driver cannot be used together.

Property	Type	Required	Description
id	string	true	The globally unique id of the route.
name	string	false	The name of the route, can be the same as the id.
driver_id	string	false	The id of the driver to be assigned to this route. Note that a route can also be assigned to a driver after import.
driver	Driver	false	The driver assigned to this route. If this driver does not exist in Foxtrot, it will be created.
activate_after_successful_import	boolean	false	Setting to automatically activate a route after a successful import.
start_time	long	true	The start time of the route as a UNIX epoch since January 1st, 1970 in milliseconds.
warehouse	Warehouse	false	The route start and end location. If this is specified, you cannot use start_warehouse and end_warehouse
start_warehouse	Warehouse	false	The route starting location. end_warehouse is required if specified.
end_warehouse	Warehouse	false	The route ending location. start_warehouse is required if specified.
waypoints	Array[Waypoint]	true	An array of waypoint objects.
vehicle	Vehicle	false	The vehicle to be associated to this route.

{
"route": {
  "id": "globally unique route id",
  "name": "route name",
  "driver_id": "globally unique driver id",
  "activate_after_successful_import": false,
  "start_time": 1510860915000,
  "start_warehouse": {
    "id": "globally unique warehouse id",
    "name": "warehouse name",
    "address": "physical address",
    "location": {
      "latitude": 3.0,
      "longitude": 4.0
    }
  },
  "end_warehouse": {
    "id": "globally unique warehouse id",
    "name": "warehouse name",
    "address": "physical address",
    "location": {
      "latitude": 3.0,
      "longitude": 4.0
    }
  },
  "waypoints": [{
      "id": "globally unique waypoint id",
      "customer_id": "customer id",
      "name": "waypoint name",
      "address": "physical address",
      "location": {
        "latitude": 1.0,
        "longitude": 2.0
      },
      "service_time_minutes": 999,
      "time_windows": [{
          "start": 1510864915000,
          "end": 1510868515000
        }],
      "deliveries": [{
          "id": "globally unique delivery id",
          "product": "product sku or description",
          "quantity": 4355.0
        }]
    }, {
      "id": "globally unique waypoint id",
      "customer_id": "customer id",
      "name": "waypoint name",
      "address": "physical address",
      "location": {
        "latitude": 3.0,
        "longitude": 4.0
      },
      "service_time_minutes": 999,
      "time_windows": [],
      "deliveries": [{
          "id": "globally unique delivery id",
          "product": "product sku or description",
          "quantity": 342.0
      }]
  }],
  "vehicle": {
    "id": "globally unique vehicle id"
  }
}

}

Driver¶

Property	Type	Required	Description
id	string	true	The dc unique id of the driver.
name	string	false	The name of the driver.
phone	string	false	The phone number to contact the driver.

{
  "id": "globally unique driver id",
  "name": "driver name",
  "phone": "driver's phone"
}

Warehouse¶

Note

Only the id property is required when importing a new route if and only if a warehouse with that same id has previously been imported into Foxtrot. If this is a new warehouse, all fields are required!

Property	Type	Required	Description
id	string	true	The id of the warehouse.
name	string	false	The name of the warehouse.
address	string	false	Physical address of the warehouse
location	Location	false	The location of the warehouse

{
  "id": "globally unique warehouse id",
  "name": "warehouse name",
  "address": "physical address",
  "location": {
    "latitude": 123.0,
    "longitude": 456.0
  }
}

Waypoint¶

Important

If a waypoint id is supplied, it must be globally unique. You cannot have multiple waypoints share an id across routes or in the same route.

Property	Type	Required	Description
id	string	false	The globally unique id of the waypoint. If not specified, a random id will be generated.
customer_id	string	true	The id of the customer at this waypoint.
name	string	false	The name of the waypoint.
address	string	false	Physical address of the waypoint
contact_name	string	false	The name of a contact for the waypoint
contact_phone	string	false	The phone number of a contact for the waypoint
contact_email	string	false	The email address of a contact for the waypoint
location	Location	false	The location of the waypoint
service_time_minutes	integer	false	The approximate service time needed to service this stop in minutes.
time_windows	Array[TimeWindow]	false	An array of time windows for time restriction to visit this stop.
deliveries	Array[Delivery]	true	An array of deliveries at this stop. There must be at least one delivery.

{
  "id": "globally unique waypoint id",
  "customer_id": "customer id",
  "name": "customer name",
  "address": "physical address",
  "location": {
    "latitude": 1.0,
    "longitude": 2.0
  },
  "service_time_minutes": 999,
  "time_windows": [{
    "start": 1510864915000,
    "end": 1510868515000
  }],
  "deliveries": [{
    "id": "delivery A",
    "product": "product",
    "quantity": 4355.0
  }]
}

TimeWindow¶

Note

Time windows interval cannot be too restrictive. That threshold is configured per DC.

Property	Type	Required	Description
start	long	true	The start time of the time windows as a UNIX epoch since January 1st, 1970 in milliseconds.
end	long	true	The end time of the time windows as a UNIX epoch since January 1st, 1970 in milliseconds.

{
  "start": 1510872073000,
  "end": 1510893673000,
}

Delivery¶

Important

If a delivery id is supplied, it must be globally unique. You cannot have multiple deliveries share an id across routes or in the same route.

Property	Type	Required	Description
id	string	false	The globally unique id of this delivery. If not specified, a random id will be generated.
product	string	true	The name of the product.
quantity	float	false	The quantity.

{
  "id": "globally unique delivery id",
  "product": "cases of beer",
  "quantity": 3.0
}

Vehicle¶

Property	Type	Required	Description
id	string	true	The globally unique id of the vehicle.

{
  "id": "globally unique vehicle id"
}

Location¶

Property	Type	Required	Description
latitude	float	true	The latitude coordinate point.
longitude	float	true	The longitude coordinate point.

{
  "latitude": 12.0,
  "longitude": 45.0
}