Traveling salesman problem (TSP) refers to finding the shortest path from a specified point through each location, given series of locations (if the location has a time window, then it is the traveling salesman problem with time window, TSPTW). This product provides API-based TSP/TSPTW problem solving services.

Feel free to leave contact information for any inquiries or how to get free access, we will get in touch with you within 2 working days.

The maximum use allowed for a single user in a single day is 1000 times, and the maximum size of a single optimization is 50 locations. If there is a need for more uses or a larger size, please contact us for further consultation and purchase.

Path optimization TSP/TSPTW problem API
:2019-07-08

Agreement

HTTP protocol, POST request mode, data called and returned in JSON format.

Basic specification
Request address

Please contact Cardinal Operations for access address, token and other information.

Public request parameters

In order to guarantee the authority and security of API, all API interfaces of the service platform shall contain the following information in the header of HTTP request:

reqTimestamp System Time System.currentTimeMillis() 1560331308386
key Key sent to the user by the service platform
keyToken KeyToken issued by the service platform to the user
sign Signature information, the user generates the signature of request information parameters in API according to the Secret sent to the user by the service platform. The rules for generating signatures are described below
x-access-token Token applied on the platform according to Key + KeyToken
Content-Type application/json application/json
Sign Rules

Sort from smallest to largest by the string of arguments, concatenated with “&”

The concatenation timestamp at the end of the concatenated string

The final concatenated string is converted to uppercase

Encrypt the string with salt using MD5

POST parameters and values are sorted in string order from the largest to the smallest. If the JSON result of POST has multiple levels, only the first level is sorted. And sign according to the above rules.

Example:
Request body:
{"age":12,"list":[{"age":12,"name":"Cardinal"}],"name":"Cardinal","user":{"id":1,"name":"Ming"}}
Then the signature string is:
Sort by the first key, and then concatenate. Plaintext to be encrypted after stitching:
age=12&list=[{"name":"Cardinal","age":12}]&name=Cardinal&user={"id":1,"name":"Ming"}
Request parameters
params Parameter sets are properties under a secondary name Object Yes
isTSPTW Whether time window is considered. True stands for yes, false stands for no. Boolean No true/false false
isCloseLoop Whether to return to the starting point. True stands for yes, false stands for no. Boolean No true/false false
mapVender Distance matrix provider, latitude and longitude distance: Euclidean String No euclidean euclidean
velocity Average speed unit: km/h Double Yes 0-100
departureTime Departure time, Format: hhmm String Yes
depotAddr Plaintext address of starting point. String Yes
locations Array, the following secondary names are properties in its array object Array<Object>
locationId Locations other than the starting point. The location code is non-repeatable and forbidden to be named depot String Yes
serviceTimeWindow Location's working time window, format: hhmm: hhmm. The end time must be greater than the start time. String No 0000:2400
serviceDuration Length of service in a location, in seconds Integer No 0-100000 0
priority Location priority, 1-10: High to low. Priority is considered first and the time window can be broken as long as the priority is satisfied. Integer No 1-10 10
locationAddr Plaintext address of locations, input address at least accurate to province, city and district String Yes
Parameter example:
{
 "params": {
  "isTSPTW": false,
  "isCloseLoop": false,
  "mapVender": "euclidean",
  "velocity": 0,
  "departureTime": "0930",
  "depotAddr": "No. 8, Jinian Road, Yangpu District, Shanghai"
},
 "locations": [
  {
  "locationId": "DD002",
  "serviceTimeWindow": "0000:2400",
  "serviceDuration": 0,
  "priority":10,
  "locationAddr": "Gehua Building, Dongcheng District, Beijing"
  }
 ]
}
Request result description
code Status code, success is 0, see status code description list String
message State description String
data Object
requestId The unique ID of the optimized request String
TSPResult Request result data Object
startDateTime Departure time. departureTime in the input parameter. format: hhmm String
endDateTime End time of train number in format: hhmm. Format processing will be done when outputting cross-day time String
totalDistance The total distance traveled by the vehicle, unit: m Integer
endDateTimeDaySpan Full completion takes days, 0 means no span day Integer
TSPStops The following are its parameters, null in case of error Array<Object>
stopLocationId ID of the docking site String
seq The order of the stops in the train number Integer
plannedTimeOfArrival The planned arrival time of the stop is in the format of HHMMSS and does not handle cross-day representation String
plannedTimeOfArrivalDaySpan The planned time of the stop (span day),0 means no span day Integer
plannedTimeOfDeparture The planned departure time of the docking station is in the format of HHMMSS, without cross-day representation processing String
plannedTimeOfDepartureDaySpan The planned departure time of this stop (span day), 0 means no span day Integer
handlingDuration Length of service, unit: second Integer
waitingDuration Waiting time, in seconds Integer
distanceFromPreviousStop The distance traveled between the stop point and the previous stop point, unit: meters Integer
drivingDurationFromPreviousStop The traveling time between the stop point and the previous stop point, unit: seconds Integer
timeWindowFulfilled Whether the time window constraints are met Boolean
TSPError TSP calculating error message Object
params Parameter set calibration result description String
location Location list verification result description String
Example of output (for reference only):
{
 "code": "0",
 "message": "Success",
 "data": {
  "requestId": "20180818001001",
  "TSPResult": {
   "startDateTime": "0700",
   "endDateTime": "1800",
   "totalDistance": 98710,
   "endDateTimeDaySpan": 0,
   "TSPStops": [
    {
    "stopLocationId": "depot",
    "seq": 1,
    "plannedTimeOfArrival": "073501",
    "plannedTimeOfArrivalDaySpan": 0,
    "plannedTimeOfDeparture": "074215",
    "plannedTimeOfDepartureDaySpan": 1,
    "handlingDuration": 300,
    "waitingDuration": 180,
    "distanceFromPreviousStop": 2556,
    "drivingDurationFromPreviousStop": 690,
    "timeWindowFulfilled": false
    }
   ]
  },
  "TSPError": {
   "params": " velocity value cannot be null",
   "location": "locationId value cannot be null"
   }
  }
}
Status code description
0 Success
10011000 Illegal signature
11001101 Invalid user company information
10011002 Api resource path does not exist
10011003 Empty key token parameter
10011004 Invalid key token
10011005 Key token expired, please re-acquire
10011006 Expired time limit, please repurchase
10011007 No valid number of calls, please re-purchase
10011008 Invalid timestamp
10011009 Invalid key
110011010 Request overclocking
10121012 Parameter set information error. For specific error information, please check TSPError.params
10122012 Incorrect location list information. For specific error information, please check TSPError.location
10122013 Number of address resolutions exceeds the limit of 50

: