API – basic features

Below you will find a description of the communication with the optimization server (for developers/programmers/computer scientists). Integrating this service with existing tools and solutions in your company may take just a few hours! If you don't want to deal with computer programming, there are more convenient ways to use OptiFacility.

1. Optimization request

The optimization service (the OptiFacility Server) receives a request from the Client via HTTP POST. The request has the json format and currently contains the following fields: 

{
  "UserID": "demo",
  "RequestID": 12345,
  "Comment": "my first testing request",
  "Quality": 2,

  "AgentSpeed": 45.0,
  "AgentStartTime": 9.0,
  "AgentWorkTime": 7.5,
  "AgentVisitTime": 0.6,
  "CostAgentWork1h": 60.0,
  "CostAgentTravel1km": 1.0,

  "Facilities": [{"Lat":52.23,  "Lon":21.012},
                 {"Lat":51.75,  "Lon":19.467},
                 {"Lat":50.061, "Lon":19.937, "Name":"KRK", "AgentVisitTime":0.85},
                 {"Lat":51.1,   "Lon":17.033},
                 {"Lat":52.407, "Lon":16.93},
                 {"Lat":53.429, "Lon":14.553, "AgentVisitTime":0.95},
                 {"Lat":53.123, "Lon":18.008, "Name":"BYD", "Importance":200},
                 {"Lat":51.25,  "Lon":22.567, "Importance":33},
                 {"Lat":51.258, "Lon":18.028}],
  "Agents": [{"Lat":52.0, "Lon":21.0, "Name":"Smith", 
              "AgentStartTime":7.0, "AgentWorkTime":7.3, "AgentSpeed":42.0,
              "CostAgentWork1h":65.0, "CostAgentTravel1km":0.98}],
  
  "Distances": [2,1,9,7,80, 2,1,0,1,90],

  "Task":"FindRoutesCommutingIncluded"
}

The meaning of these fields is explained below:

  • UserID – the registered name of the user of this service.
  • RequestID – any integer. This value will be returned in Server's response. This mechanism can be useful if the Client wants to know which response is related to which request, and responses are processed by different Client processes than those that have sent the request. If the Client does not need this mechanism, they can provide e.g. 0.
  • Comment – an optional field with any information you might want to use to describe the data. It is ignored by OptiFacility, but you may find it useful if you save the request as a file and use it in the future.
  • Quality – the number 1, 2 or 3 – a hint for the optimization service on how much computing power should be spent on the search for the best solution. The higher the number, the longer the wait for Server's response (but never longer than 60 seconds).
  • AgentSpeed – the average speed of agents traveling between locations (objects) expressed in km/h. The service assumes linear connections, so if the Client would like to display detailed and accurate data to the end user, they may, after receiving the response from the server, update the distances and times based on the current data from a navigation system.
  • AgentStartTime – clock time when an agent (salesperson/technician) starts their work. For example, 13.25 means 1:15pm (0.25 is 1/4 of an hour = 15 minutes).
  • AgentWorkTime – how many hours a day an agent (salesperson/technician) works.
  • AgentVisitTime – how many hours a visit takes at a facility (object/location).
  • CostAgentWork1h – the cost of one hour of work at a facility (object/location).
  • CostAgentTravel1km – the cost of an agent traveling one kilometer.
  • Facilities – array of objects containing latitude and longitude – coordinates of facilities. Optionally, you can individually set AgentVisitTime for each facility. Another optional field is the Importance of visiting a facility. By default, all facilities have the importance of 100, and you can set lower and higher values. For example the importance of 210 means that it is better to visit such a facility instead of two others that have importances of 100, or four others that have importances of 50. Another optional field, Name, is ignored during optimization, but can be useful for you to distinguish between facilities. Names are also displayed in GUI.
  • Agents – array of objects containing latitude and longitude – initial coordinates where agents are located (this also determines the number of agents). OptiFacility may try to find better locations for these agents, but will not change their number. As the sample request above shows, you can optionally set a number of parameters individually for each agent – so they start and finish work at different times, they travel with different speeds, and costs of their work differ.
  • Distances – an optional field with custom distances between locations.
  • Task – selection of the optimization task – one of:
    • FindRoutesCommutingIncluded optimizes the route without changing the location of the agents, including the time and cost of reaching the first facility each day, and the time and cost of returning to the base location. In this task, it is possible that some very remote locations will not be handled at all – these are the locations that cannot be reached and serviced within AgentWorkTime hours.
    • FindRoutesCommutingExcluded works as above, but the time and cost of reaching the first facility each day, and going back home from the last serviced facility, are not considered. Therefore, each facility will always be serviced, including those facilities that require a very long time to reach.
    • RecommendAgentLocationsCommutingIncluded tries to relocate agents to balance their load, to handle all the facilities, and to minimize the total time and cost.

There are more advanced features of OptiFacility you can read about later: skills required by facilities and provided by agents, capacities (pickup and delivery) and availability time windows.

Facilities and Agents are numbered as a single 0-based sequence – this way, every facility and every agent receives a unique number (id, index), which will be used in responses from the Server.

After a moment, the Server will respond in the json format containing specifications of routes (lists of facility indexes) assigned to agents, agent optimized locations, and various additional information about the returned solution.

During the optimization, the Server tries to maximize the number of facilities that are serviced by agents, to minimize the total time (and therefore the distance and costs) of the service, and to balance the load of agents.

2. Server response

A sample response to the above request looks like this: 

{
  "Version": 224,
  "RequestID": 777,
  "StatusCode": 0,
  "StatusMessage": "OK",
  "Solution": {
    "InstanceHash": "9,1,0,0",
    "EstimatedCost": 1147.204614948091,
    "Unvisited": [ 2, 3, 4, 5, 6, 8 ],
    "Assignments": [
      {
        "AgentID": 9,
        "LatLon": [ 52.0, 21.0 ],
        "UsedHours": 11.853208505539666,
        "UsedDays": 2,
        "Route": [
  {"Location":9, "Context":1, "TimeArrival": 7.0, "TimeDeparture": 7.0, "ProductLoad":[] },
  {"Location":7, "Context":0, "TimeArrival": 8.9, "TimeDeparture": 9.8, "ProductLoad":[] },
  {"Location":9, "Context":1, "TimeArrival":11.7, "TimeDeparture":31.0, "ProductLoad":[] },
  {"Location":1, "Context":0, "TimeArrival":33.5, "TimeDeparture":34.4, "ProductLoad":[] },
  {"Location":0, "Context":0, "TimeArrival":36.6, "TimeDeparture":37.5, "ProductLoad":[] },
  {"Location":9, "Context":1, "TimeArrival":38.1, "TimeDeparture":38.1, "ProductLoad":[] }
        ]
      }
    ]
  }
}

The meaning of the fields in this response is explained below:

  • Version – version number of the Server optimization software and algorithms.
  • RequestID – the ID that was provided in the request by the Client.
  • StatusCode, StatusMessage – information about potential problems, eg. an incorrect query, an incorrect format, the lack of a field or an incorrect value type, etc. StatusCode=0 means no error.
  • Solution – assignment of optimized routes to locations of agents.
    • InstanceHash – a short summary of the problem instance that this solution concerns.
    • EstimatedCost – an estimate of the cost (which is the product of kilometers traveled and the cost per kilometer + the product of the number of facilities serviced and the servicing cost). Does not include penalties for unserviced facilities.
    • Unvisited – a set of facilities that were not serviced by any agent because they were located too far away (reaching them and the service time would take longer than the daily time of work of an agent) or it was impossible to fulfill skill, time window or capacity constraints that were provided. The particular ordering of the numbers of facilities does not matter (there are six of them in the example above).
    • Assignments – an array of routes assigned to agents:
      • AgentID – the unique number of the agent (as described in the "Optimization request" section above).
      • LatLon – coordinates fo the base location of an agent. For Task equal FindRoutesCommutingIncluded or FindRoutesCommutingExcluded, agent's location remains unchanged just as it was provided in the request. For RecommendAgentLocationsCommutingIncluded, agent's base location may be different from the one provided in the request – agents can be relocated by the Server to better locations.
      • UsedHours – how many hours the agent needed in total to travel and service facilities in their Route.
      • UsedDays – how many days (integer) the agent needed to travel and service facilities in their Route.
      • Route – a sequence of structures that correspond to subsequent locations visited by an agent. Each structure contains:
        • Location – the index of the location visited. If this is the same as the number AgentID, it means that the agent visited its base location.
        • TimeArrival and TimeDeparture are what you think they are.
        • Context – the reason/purpose of the visit. For now, it can be 0 (regular visit at a facility), 1 (coming back to the base for the night) or 2 (coming back to the base because the pickup/delivery capacity constraints have been exceeded).
        • ProductLoad – the current state of the load of individual products, only meaningful when you used capacities (pickup and delivery).

Let's see how this minimal, sample request listed above looks on a map. The request defined 9 facilities (numbers from 0 to 8) and one agent (number 9) staying close to facility number 0.

For the task FindRoutesCommutingIncluded, optimized routes from the Server response above look like this:

Since, in this example, facilities are hundreds of miles away (the map span is 1000km) and the agent travels relatively slowly, working for 7.5 hours per day the agent needed two days ("UsedDays": 2) to service only three facilities (7 during the first day, and 1 and 0 on the second day), so the sequence of the "Location" fields in "Route" is 9, 7, 9, 1, 0, 9. Six facilities remained out of reach (traveling to these facilities, servicing them and going back required more than the allowed work time per day).

The result of the RecommendAgentLocationsCommutingIncluded task looks as follows:

The agent number 9 was relocated (now it is near facility 6) and now the agent needs one day ("UsedDays": 1) to service two facilities – the route is 9, 6, 4, 9. Note that the agent is now able to handle one facility less than before, but facility 6 has the importance of 200, so visiting this facility is worth as much as visiting two other facilities that have a default importance (100). Note also that before relocation, the agent was visiting facility 7 which had a very low importance (33), so the sum of importances of unvisited facilities was 700. After relocation it dropped to 633, and one cannot find a location that would yield a lower value.

The purpose of this minimal example with one agent was to demonstrate the meaning of the fields in the json messages, so the example was too simple to show more interesting cases. Let's see a slightly larger example, where a company has five specialists (servicemen) who cover the area of a state. The system optimized their routes and locations so that given the constraints, it is not possible to find better assignments:

  • Agent #1 load: 8.01 days
  • Agent #2 load: 10.35 days
  • Agent #3 load: 9.89 days
  • Agent #4 load: 9.38 days
  • Agent #5 load: 5.79 days
  • Facilities out of reach: 8

More examples of OptiFacility in action are shown in the video below:

3. Using the Server to optimize transport and logistics

In practice, the end user is interested in minimizing operating costs, which requires optimizing locations of agents and their routes. Using the OptiFacility Server, the following scenarios are possible:

  1. Determining optimized routes for existing locations of agents. Use task FindRoutesCommutingIncluded or FindRoutesCommutingExcluded – in these tasks, the Server does not modify locations of agents provided in the request.
  2. Determining the minimum number of agents required to service all facilities, including their commuting times. If you want to provide base locations for agents, use the FindRoutesCommutingIncluded task. If you want OptiFacility to recommend agent locations, use the RecommendAgentLocationsCommutingIncluded task. Send successive requests to the server increasing the number of agents – start with 1 agent, then 2, 3... until the "Route" list for "AgentID":-1 becomes empty. This means that all facilities were serviced by agents.
  3. Determining the minimum number of agents required to service all facilities within a given number of days (deadline) can be achieved analogously. Note that the FindRoutesCommutingExcluded task is also a reasonable choice in this scenario. Increase the number of agents until the "Route" for "AgentID":-1 becomes empty (for the FindRoutesCommutingExcluded task, one agent will be enough) and then keep increasing the number of agents until, for all agents, their UsedDays fields become less than or equal to your desired number of days (e.g. 5). Just as in the previous scenario, in this scenario you can provide fixed base locations of agents, or let the Server try to improve them.
  4. Unusual situations and dynamically changing conditions: The OptiFacility Server can be used in more creative ways, for example:
    1. If a global operating schedule has already been planned for the entire group of agents, and for some reason you want to pass service duties of some facilities from one agent to another one, you can send two separate queries to the Server, each of them concerning only one of the two agents, and providing the list of facilities that each of them needs to service.
    2. If you want to replan (even during the day) a fragment of agent's schedule that was earlier created, you can send a request that contains only facilities for this particular agent, providing a lower number of working hours if a part of the day already passed. You can even specify agent's current location from the GPS.
    3. If you planned a schedule for 50 employees and you want to modify plans for only four of them, you can ask the Server to optimize plans just for these four agents (so the query contains only 4 agents and the facilities they should service).
    4. If, for some reason, facilities are assigned to agents and this assignment cannot be changed, you should send separate requests to the Server, each request concerning one agent and the list of facilities assigned to this particular agent. Using the RecommendAgentLocationsCommutingIncluded task allows you to ask the Server to try to find agent base locations that are more beneficial than those provided in your query.