\n\n
Change Record
\n
\n\n\n| Date | \nAuthor | \nVersion | \nChange Description | \n
\n\n\n\n| 03 Feb 2021 | \nGanesh Raja | \n1.0 | \nInitial APIs and their descriptions | \n
\n\n
\n
Authentication
\n
Locus uses Basic Authentication for authentication. The credentials are shared separately over email.
\n
Your API keys can be used to access and modify the data related to your account, so be sure to keep them secure. Do not share your secret API key in publicly accessible areas such as GitHub, client-side code, and so forth. Locus APIs operate exclusively on HTTPS. Requests that are over HTTP without encryption will fail. Requests without authentication will also fail.
\n
Errors
\n
When the API request encounters an error with your request, it will respond with an HTTP status code and a JSON-formatted body with additional details. Locus uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx series indicate success. Codes in the 4xx series indicate an error that failed given the information provided. Codes in the 5xx series indicate an error with Locus servers. Although 5xx are rare we would recommend setting retries for the API request in-case an error code in this series is received.
\n
Human readable error messages can be found under message key in the response JSON.
\n
A sample response is provided below
\n
{
\n
\"errorCode\": -1,
\n
\"message\": \"A human readable error message\"
\n
}
\n
Prerequisites
\n
\n- Create Teams
\n- Create Homebases
\n- Create Riders
\n- Create Vehicle Models
\n
\n
Team
\n
A team is a group of riders. Tasks are assigned to teams and personnel can manage tasks using teams. \nNOTE: A team can have multiple homebases\nExample: Manhattan_East\nUse-case: All\nDependencies: None
\n
Homebase
\n
A Homebase is the centre of operations from where riders start, and end routes and/or goods are collected for delivery. A homebase can have multiple teams and a team can have multiple homebases.\nExample: A warehouse, kitchen\nUse-case: SPMD and MPSD\nDependencies: Team
\n
Riders
\n
Members of a team who perform ground actions using the LOTR app. They execute task visits to complete a task.\nExample: Delivery person, Field executive\nUse-case: ALL\nDependencies: Team
\n
Vehicle
\n
A four/two-wheeler for the rider to complete the task.\nExample: KA53X1000\nUse-case: Mandatory when using Fleet Config and Vehicle is the primary resource of the client\nDependencies: Team, Vehicle Model
\n
Vehicle Model
\n
A generic entity that represents a type of vehicle from a specific manufacturer with attributes such as volume and weight capacity, limits, dimensions, skills etc.\nExample: TATA Ace Mega\nUse-case: Mandatory if Vehicle is the primary resource of the client\nDependencies: Transporter
\n
Plan
\n
A plan is the outcome of LOCUS’ algorithm executed on a batch of tasks. The outcome is a set of routes called TOURS which are performed by riders to complete the tasks.\nDependencies: Batch
\n
Batch
\n
A set of tasks that are to be performed by a single or multiple riders from a team in a day. \nDependencies: Task
\n
Tasks
\n
Tasks are your customer’s orders. They have visits associated with them, that personnel create and assign to riders for completion.\nDependencies: Team, Homebase (if SPMD/MPSD)
\n
This will create the client warehouse location which will be the pickup point for all vehicles tagged to the client
\n","urlObject":{"protocol":"https","path":["v1","client","shyft-demo","homebase",":homebaseId"],"host":["locus-api","com"],"query":[],"variable":[{"id":"fbe1f681-fae4-4755-bef5-35a3bcbe546a","type":"string","value":"","key":"homebaseId"}]}},"response":[{"id":"bd11e9e8-91bf-4d9d-a9c1-50554cac34c8","name":"Create new homebase (physical warehouse/SPMD pickup location)","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"address\": {\n \"id\": \"pickup-wh-001\",\n \"lat\": 12.920903,\n \"lng\": 77.52036,\n \"latLngAccuracy\": 0,\n \"name\": \"Pickup Warehouse 001\",\n \"address\": \"Jawaharlal Nehru Main Road, BEML Layout, RR Nagar, Bengaluru, Karnataka 560010\",\n \"type\": \"PLACE\",\n \"userTat\": 0\n },\n \"tat\": 0,\n \"readinessTime\": 0,\n \"teams\": [\n {\n \"clientId\": \"shyft-demo\",\n \"teamId\": \"client-001\",\n \"status\": \"ENABLED\"\n }\n ],\n \"pincodes\": [\n \"string\"\n ],\n \"type\": \"CLIENT\"\n}","options":{"raw":{"language":"json"}}},"url":"https://locus-api.com/v1/client/shyft-demo/homebase/pickup-wh-001"},"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"clientId\": \"shyft-demo\",\n \"id\": \"pickup-wh-001\",\n \"name\": \"Pickup Warehouse 001\",\n \"address\": {\n \"id\": \"pickup-wh-001\",\n \"lat\": 12.920903,\n \"lng\": 77.52036,\n \"latLngAccuracy\": 0,\n \"name\": \"Pickup Warehouse 001\",\n \"address\": \"Jawaharlal Nehru Main Road, BEML Layout, RR Nagar, Bengaluru, Karnataka 560010\",\n \"type\": \"PLACE\",\n \"userTat\": 0\n },\n \"teams\": [\n {\n \"clientId\": \"shyft-demo\",\n \"teamId\": \"client-001\",\n \"status\": \"ENABLED\"\n }\n ],\n \"shouldGeofence\": true,\n \"pincodes\": []\n}"}],"_postman_id":"025562b0-d18f-4a70-86c4-83709d986321"}],"id":"661c293d-20a7-4f3e-9292-224775941f4e","_postman_id":"661c293d-20a7-4f3e-9292-224775941f4e","description":""},{"name":"Vehicle Model","item":[{"name":"Create a new vehicle model","id":"b9ae6b76-0a06-47af-ab67-2047bf6da8d9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"string\",\n \"volumeLimit\": {\n \"unit\": \"ITEM_COUNT\",\n \"higherThresh\": \"string\"\n },\n \"resourceLimits\": [\n {\n \"name\": \"string\",\n \"unit\": \"COUNT\",\n \"lowerThresh\": 0,\n \"higherThresh\": 0\n }\n ],\n \"travelParams\": {\n \"trafficFactor\": 0,\n \"maxSpeed\": 0\n },\n \"vehicleType\": \"NONE\",\n \"costModel\": {\n \"fixedCost\": 0\n },\n \"additionalProperties\": {\n \"isColdChain\": true,\n \"unladenWeight\": 0,\n \"fuelType\": \"PETROL\",\n \"mileage\": 0\n },\n \"loadingParams\": {\n \"loadingDuration\": 0,\n \"unloadingDuration\": 0\n },\n \"allowMultiTrip\": true,\n \"skills\": {\n \"tags\": [\n \"string\"\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://locus-api.com/v1/client/shyft-demo/vehicleModel/:vehicleModelId","description":"This will help create new distinct vehicle models with different capacity, type and necessary carrying properties
\n","urlObject":{"protocol":"https","path":["v1","client","shyft-demo","vehicleModel",":vehicleModelId"],"host":["locus-api","com"],"query":[],"variable":[{"id":"72d7417e-1aa1-46b3-b872-11a2b6a1f7c4","type":"string","value":"","key":"vehicleModelId"}]}},"response":[{"id":"ec2a54f1-5a3d-4b3c-a1ae-7a43fdf24d20","name":"Create a new vehicle model","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Maruthi Eeco Refrigerated\",\n \"volumeLimit\": {\n \"unit\": \"ITEM_COUNT\",\n \"higherThresh\": \"100\"\n },\n \"resourceLimits\": [\n {\n \"name\": \"string\",\n \"unit\": \"COUNT\",\n \"lowerThresh\": 0,\n \"higherThresh\": 0\n }\n ],\n \"travelParams\": {\n \"trafficFactor\": 0,\n \"maxSpeed\": 0\n },\n \"vehicleType\": \"TRUCK\",\n \"costModel\": {\n \"fixedCost\": 0\n },\n \"additionalProperties\": {\n \"isColdChain\": true,\n \"unladenWeight\": 0,\n \"fuelType\": \"PETROL\",\n \"mileage\": 0\n },\n \"loadingParams\": {\n \"loadingDuration\": 0,\n \"unloadingDuration\": 0\n },\n \"allowMultiTrip\": false,\n \"skills\": {\n \"tags\": [\n \"FREEZER\"\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://locus-api.com/v1/client/shyft-demo/vehicleModel/eeco-ref"},"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"name\": \"Maruthi Eeco Refrigerated\",\n \"volumeLimit\": {\n \"unit\": \"ITEM_COUNT\",\n \"higherThresh\": \"100\"\n },\n \"resourceLimits\": [\n {\n \"name\": \"string\",\n \"unit\": \"COUNT\",\n \"lowerThresh\": 0,\n \"higherThresh\": 0\n }\n ],\n \"travelParams\": null,\n \"vehicleType\": \"TRUCK\",\n \"costModel\": null,\n \"additionalProperties\": {\n \"isColdChain\": null,\n \"unladenWeight\": null,\n \"fuelType\": \"PETROL\",\n \"mileage\": null\n },\n \"loadingParams\": null,\n \"allowMultiTrip\": false,\n \"skills\": {\n \"tags\": [\n \"FREEZER\"\n ]\n },\n \"id\": {\n \"clientId\": \"shyft-demo\",\n \"version\": 1,\n \"modelId\": \"eeco-ref\"\n }\n}"}],"_postman_id":"b9ae6b76-0a06-47af-ab67-2047bf6da8d9"}],"id":"941a4500-c31e-43c9-993f-e5e326ca2055","_postman_id":"941a4500-c31e-43c9-993f-e5e326ca2055","description":""}],"id":"66a9ef6e-1eab-49ef-81e7-c451a71a0535","_postman_id":"66a9ef6e-1eab-49ef-81e7-c451a71a0535","description":""},{"name":"SPMD Flow APIs","item":[{"name":"SPMD Batch Creation","id":"bbfb8652-c61e-4453-8e7a-64b6c657668a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[],"body":{"mode":"raw","raw":"{\n \"homebaseId\": \"string\",\n \"teamId\": \"string\",\n \"tasksDate\": \"YYYY-MM-DD\",\n \"inputTasks\": [\n {\n \"taskId\": \"string\",\n \"userId\": \"string\",\n \"lineItems\": [\n {\n \"id\": \"string\",\n \"name\": \"string\",\n \"quantity\": number,\n \"price\": {\n \"amount\": number\n }\n }\n ],\n \"taskType\": \"string\",\n \"contactPoint\": {\n \"name\": \"string\",\n \"number\": \"string\"\n },\n \"locationAddress\": {\n \"formattedAddress\": \"string\",\n \"pincode\": \"string\",\n \"city\": \"string\",\n \"state\": \"string\"\n },\n \"slot\": {\n \"start\": \"2020-04-23T08:30:00.000+0530\",\n \"end\": \"2020-04-23T22:30:00.000+0530\"\n },\n \"transactionDuration\": number,\n \"volume\": {\n \"value\": number,\n \"unit\": \"string\",\n \"exchangeType\": \"string\"\n },\n \"amountTransaction\": {\n \"amount\": {\n \"amount\": number\n },\n \"exchangeType\": \"string\"\n },\n \"appFields\": {\n \"items\": [\n {\n \"item\": \"string,\n \"format\": \"TEXT\"\n }\n ]\n }\n },\n {\n \"taskId\": \"string\",\n \"userId\": \"string\",\n \"lineItems\": [\n {\n \"id\": \"string\",\n \"name\": \"string\",\n \"quantity\": number,\n \"price\": {\n \"amount\": number\n }\n },\n {\n \"id\": \"string\",\n \"name\": \"string\",\n \"quantity\": number,\n \"price\": {\n \"amount\": number\n }\n }\n ],\n \"taskType\": \"string\",\n \"contactPoint\": {\n \"name\": \"string\",\n \"number\": \"string\"\n },\n \"locationAddress\": {\n \"formattedAddress\": \"string\",\n \"pincode\": \"string\",\n \"city\": \"string\",\n \"state\": \"string\"\n },\n \"slot\": {\n \"start\": \"2020-04-23T08:30:00.000+0530\",\n \"end\": \"2020-04-23T22:30:00.000+0530\"\n },\n \"transactionDuration\": number,\n \"volume\": {\n \"value\": number,\n \"unit\": \"string\",\n \"exchangeType\": \"string\"\n },\n \"amountTransaction\": {\n \"amount\": {\n \"amount\": number\n },\n \"exchangeType\": \"string\"\n },\n \"appFields\": {\n \"items\": [\n {\n \"item\": \"string\",\n \"format\": \"TEXT\"\n }\n ]\n }\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://locus-api.com/v1/client/:clientId/spmdbatch/:batchId","description":"\n\n
Single Pick Multi Drop - The rider picks up all goods to complete a set of tasks from the homebase in a single visit. The rider then completes the tasks by performing customer visits, delivering the goods.\nExample: E-retailers
\n