This is a short guide that will familiarize you with the XFleet API. You should be on track (pun intended) in less than 20 minutes.

We will cover just the basics. Please check the other sections for the in-depth API documentation.

Authentication

In order to start querying the XFleet API you need a valid token.

You will be able to retrieve the session token using your username and password.

$ curl -d '{"user": "thomas", "pass": "mys3cr3tP4ss"}' \
       -X POST \
       https://app.xfleet.io/api/v1/users/me/apiTokens
{
    "id": "4qCOjE28EZULjw4eDzHrMZ",
    "token": "5f34529edf6fbe1cfdbfeaf132481fd74qCOjE28EZULjw4eDzHrMZ",
    "expiryDate": "2019-03-25T20:49:46+00:00"
}

It's simple as that! Now you have a token (5f34529edf6fbe1cfdbfeaf132481fd74qCOjE28EZULjw4eDzHrMZ) that you can use to authenticate the following requests. Keep it safe and remember that it can only be used until the expiry date (2019-03-25T20:49:46+00:00).

Your info

You just logged it, but that's not enough to get the full picture about your identity. Let's get some additional info about the user that just signed in.

$ curl -H 'Authorization: Token 5f34529edf6fbe1cfdbfeaf132481fd74qCOjE28EZULjw4eDzHrMZ' \
       -X GET \
       https://app.xfleet.io/api/v1/users/me
{
  "email": "thomas@xfleet.io",
  "username": "thomas",
  "active": true,
  "id": "WGn88UPMOpXKSwQPyui68"
}

That's you! Let's see what you can do next.

Companies

Since you are logged in and know your XFleet account details let's retrieve the list of companies that you can access.

$ curl -H 'Authorization: Token ...' \
       -X GET \
       https://app.xfleet.io/api/v1/companies
[
  {
    "name": "XFleet Delivery Services",
    "id": "1SvEJdFjXGq9uiIjZGFUNv"
  }
]

So there is 1 company that we can choose from. Good enough. Obviously, if people will grant access to their companies, you will receive multiple results.

Vehicles

The company would be pretty useless without some vehicles that actually do the work, right? Let's get them!

$ curl -H 'Authorization: Token ...' \
       -X GET \
       https://app.xfleet.io/api/v1/companies/1SvEJdFjXGq9uiIjZGFUNv/vehicles
[
  {
    "licensePlate": "4963GV82",
    "active": true,
    "gpsDistanceMethod": "auto",
    "driver": {
      "id": "6oeA1FbXvpXa2QStD4dr6B"
    },
    "team": {
      "id": "2z04cDbxRApG22JyDMelqB"
    },
    "maxWeight": 2336,
    "maxPallets": 7.5,
    "maxVolume": 2,
    "id": "1NtkFCLdV2YEHHfg9UUZGg",
    "createdAt": "2019-03-23T13:38:44+00:00",
    "tags": [
      "repaired",
      "new"
    ]
  },
  ...
]

Note that we used the 1SvEJdFjXGq9uiIjZGFUNv id that belongs to the XFleet Delivery Services company from the previous call.

Clients

Now that we have our vehicles, let's see if we can find some clients to serve.

$ curl -H 'Authorization: Token ...' \
       -X GET \
       https://app.xfleet.io/api/v1/companies/1SvEJdFjXGq9uiIjZGFUNv/clients
[
  {
    "name": "Regency Hotel",
    "category": {
      "id": "4BuOuA9VZT0MdvJe7bF03g"
    },
    "active": true,
    "address": "540 PARK AVENUE New York NY 10065",
    "lat": 40.7645497,
    "lon": -73.9692185,
    "team": {
      "id": "2UTw0ay7lzfOyqC1rVBXxE"
    },
    "zone": {
      "id": "6FGIdB7qpAqYf8E4mKcblr"
    },
    "requiredSkills": [
      {
        "id": "rnABOl4EP9qJjKvHDhddA"
      }
    ],
    "createdAt": "2019-03-23T13:38:43+00:00",
    "id": "3YEhKrtnQ9WLdUUiAHtvqo",
    "tags": [
      "5-star"
    ]
  },
  ...
]

Great, we have some clients that are looking forward to our deliveries.

Orders

Let's see if our clients ordered anything.

$ curl -H 'Authorization: Token ...' \
       -X GET \
       https://app.xfleet.io/api/v1/companies/1SvEJdFjXGq9uiIjZGFUNv/orders
[
  {
    "orderDate": "2019-03-23",
    "name": "7QWAC285",
    "shipToLat": 40.76455,
    "shipToLon": -73.969219,
    "status": {
      "id": "24zLEf33fdoK2wIZbAvJeW"
    },
    "productName": "Spaghetti sauce",
    "productDescription": "Spaghetti sauce",
    "weight": 91,
    "volume": 3.06,
    "pallets": 4.2,
    "qty": 58,
    "client": {
      "id": "3YEhKrtnQ9WLdUUiAHtvqo"
    },
    "delivered": false,
    "id": "QjxoF95PzmOeuIwGUGz79",
    "notes": "Order number: 96"
  },
  ...
]

Sweet! Let's plan some routes!

Planning

Glad you made it so far! We know our clients, their orders and our fleet is ready to serve them. Let's plan:

$ curl -H 'Authorization: Token ...' \
       -H 'Content-type: application/json' \
       -X POST \
       -d '{
              "services": [
                {
                  "id": 1,
                  "name": "Sanremo Pizza",
                  "lat": 40.700273,
                  "lon": -73.9063134,
                  "orders": [
                    {
                      "id": "2JLZKzC28pyYvdtcseK8JB"
                    }
                  ],
                  "client": {
                    "id": "272fAjFOwIc6MIIW55UCyr"
                  }
                },
                {
                  "id": 2,
                  "name": "Glendale Pizza",
                  "lat": 40.701895,
                  "lon": -73.883638,
                  "orders": [
                    {
                      "id": "3rRAsNZwWKOzSAH6mGvt7h"
                    }
                  ],
                  "client": {
                    "id": "6T3Yl2xdeGZTQFYNPqnx4b"
                  }
                },
                ...
              ],
              "depot": {
                "id": "2P9flmOqSD09WmEDXvXync",
                "name": "Central Depot",
                "lat": 40.767072,
                "lon": -73.8421927
              },
              "departureTime": "2019-03-17T05:30:00+02:00",
              "returnToDepot": false,
              "serviceTime": 600,
              "maxServicesPerRoute": 100
            }' \
       https://app.xfleet.io/api/v1/companies/1SvEJdFjXGq9uiIjZGFUNv/deliveryPlans
{
  "routes": [
    {
      "services": [
        {
          "name": "Central Depot",
          "lat": 40.767072,
          "lon": -73.8421927,
          "depot": {
            "id": "2P9flmOqSD09WmEDXvXync"
          }
        },
        {
          "name": "Glendale Pizza",
          "lat": 40.701895,
          "lon": -73.883638,
          "orders": [
            {
              "id": "3rRAsNZwWKOzSAH6mGvt7h",
            }
          ],
          "client": {
            "id": "6T3Yl2xdeGZTQFYNPqnx4b",
          }
        },
        {
          "name": "Sanremo Pizza",
          "lat": 40.700273,
          "lon": -73.9063134,
          "orders": [
            {
              "id": "2JLZKzC28pyYvdtcseK8JB",
            }
          ],
          "client": {
            "id": "272fAjFOwIc6MIIW55UCyr",
          }
        }
      ],
      "vehicle": {
        "licensePlate": "530X76A8",
        "driver": {
          "email": "jose.king@xfleet.io",
          "name": "Jose King",
          "id": "16bniCrowZQhw0fqE8lwgh",
        },
        "maxWeight": 1195,
        "maxPallets": 9.4,
        "maxVolume": 2,
        "id": "18EXGOMRbSz9Ita6D1MaGr"
      }
    },
    ...
  ]
}

Great! We got our list of routes. This contains the delivery plan, and not the actual navigation directions. You'll get those in the next step.

Directions

You have a plan, all you need now are the driving directions to your targets.

$ curl -H 'Authorization: Token ...' \
       -H 'Content-type: application/json' \
       -X POST \
       -d '{
              "services": [
                {
                  "name": "Central Depot",
                  "lat": 40.767072,
                  "lon": -73.8421927,
                  "depot": {
                    "id": "2P9flmOqSD09WmEDXvXync"
                  }
                },
                {
                  "name": "Austin House",
                  "lat": 40.7209068,
                  "lon": -73.8463708,
                  "client": {
                    "id": "2NA2fZZRQdVo8DzdjqfzP8"
                  }
                },
                {
                  "name": "Glendale Pizza",
                  "lat": 40.701895,
                  "lon": -73.883638,
                  "client": {
                    "id": "6T3Yl2xdeGZTQFYNPqnx4b"
                  }
                },
                ...
              ],
              "departureTime": "2019-03-17T05:30:00+02:00",
              "serviceTime": 600
            }' \
       https://app.xfleet.io/api/v1/routedirections
{
  "directions": {
    "distance": 11100.0,
    "duration": 1680,
    "legs": [
      {
        "distance": 6800.0,
        "duration": 300,
        "steps": [
          {
            "distance": 6800.0,
            "duration": 300,
            "endLocation": {
              "lat": 40.720773,
              "lon": -73.846456
            },
            "polyLine": [
              [
                -73.842535,
                40.767116
              ],
              [
                -73.842435,
                40.767601
              ],
              ...
            ],
            "startLocation": {
              "lat": 40.767116,
              "lon": -73.842535
            }
          }
        ]
      },
      {
        "distance": 4300.0,
        "duration": 180,
        "steps": [
          {
            "distance": 4300.0,
            "duration": 180,
            "endLocation": {
              "lat": 40.701852,
              "lon": -73.883807
            },
            "polyLine": [
              [
                -73.846456,
                40.720773
              ],
              [
                -73.846964,
                40.720959
              ],
              ...
            ],
            "startLocation": {
              "lat": 40.720773,
              "lon": -73.846456
            }
          }
        ]
      },
      ...
    ]
  },
  "plannedDistance": 11100,
  "plannedDuration": 1680,
  "plannedFinish": "2019-03-17T05:58:00+02:00",
  "plannedStart": "2019-03-17T05:30:00+02:00",
  "services": [
    {
      "depot": {
        "id": "2P9flmOqSD09WmEDXvXync"
      },
      "lat": 40.767072,
      "lon": -73.8421927,
      "name": "Central Depot",
      "plannedArrival": "2019-03-17T05:30:00+02:00",
      "plannedDeparture": "2019-03-17T05:30:00+02:00"
    },
    {
      "client": {
        "id": "2NA2fZZRQdVo8DzdjqfzP8",
      },
      "lat": 40.7209068,
      "lon": -73.8463708,
      "name": "Austin House",
      "plannedArrival": "2019-03-17T05:35:00+02:00",
      "plannedDeparture": "2019-03-17T05:45:00+02:00",
    },
    ...
  ],
}

Summary

This was just a short intro to give you a glimpse on what you can do through the API. Check the next sections to see how to do more (like creating vehicles, defining time slots for clients, adding restrictions to delivery plans and many more).

Questions? Drop us an email us at support@xfleet.io. We usually reach back in 1-2 business days.