API Documentation

Navora provides three REST APIs for route optimization and navigation. All endpoints accept JSON via POST, require authentication, and return JSON responses.

Base URL

https://resolt-navora-api.azurewebsites.net

All endpoint paths below are relative to this base URL.

Authentication

Every request must include your accountId and apiKey in the JSON body. These are validated against your account on every call. If invalid or suspended, the API returns 401 Unauthorized.

// Include in every request body
{
  "accountId": "your-account-guid",
  "apiKey": "your-api-key",
  ...
}
                    

Error Handling

Status	Meaning
`200`	Success
`400`	Bad request — invalid input, too many tasks/vehicles, or route could not be calculated
`401`	Unauthorized — invalid `accountId` or `apiKey`, or account suspended
`500`	Internal server error — includes detail message

Error responses return JSON: { "error": "description" }

POST /api/navigate

Point-to-point navigation with turn-by-turn instructions. Ideal for in-app driver navigation. For re-routing, simply call again with the driver's current position as the origin.

Request Body

Field	Type	Required	Description
`accountId`	string	Yes	Your account GUID
`apiKey`	string	Yes	Your API key
`origin`	GeoLocation	Yes	Start point
`destination`	GeoLocation	Yes	End point
`profile`	string	No	`Car` (default) or `Bike`
`preference`	string	No	`Fastest` (default) or `Shortest`
`waypoints`	GeoLocation[]	No	Optional intermediate points

Example Request

POST https://resolt-navora-api.azurewebsites.net/api/navigate
Content-Type: application/json

{
  "accountId": "6ffdea07-8957-49ba-9e0b-5dbce4b86d87",
  "apiKey": "your-api-key",
  "origin": { "latitude": -26.2041, "longitude": 28.0473 },
  "destination": { "latitude": -26.1076, "longitude": 28.0567 },
  "profile": "Car",
  "preference": "Fastest",
  "waypoints": [
    { "latitude": -26.1452, "longitude": 28.0364 }
  ]
}
                    

Response

{
  "distanceKm": 14.23,
  "duration": "00:18:45",
  "encodedPolyline": "~pq~FhtciC...",
  "steps": [
    {
      "instruction": "Head south onto Main Rd",
      "distanceKm": 0.5,
      "duration": "00:01:00",
      "maneuver": "depart-south",
      "location": { "latitude": -26.2041, "longitude": 28.0473 }
    },
    {
      "instruction": "Turn right onto N1",
      "distanceKm": 5.2,
      "duration": "00:06:30",
      "maneuver": "turn-right",
      "location": { "latitude": -26.1890, "longitude": 28.0410 }
    },
    ...
  ]
}
                    

POST /api/route

Multi-stop ordered routing. Supply a sequence of locations and receive a route that visits them in the exact order provided. Returns the same response format as /api/navigate.

Request Body

Field	Type	Required	Description
`accountId`	string	Yes	Your account GUID
`apiKey`	string	Yes	Your API key
`locations`	GeoLocation[]	Yes	Ordered list of stops (minimum 2)
`profile`	string	No	`Car` (default) or `Bike`
`preference`	string	No	`Fastest` (default) or `Shortest`

Example Request

POST https://resolt-navora-api.azurewebsites.net/api/route
Content-Type: application/json

{
  "accountId": "6ffdea07-8957-49ba-9e0b-5dbce4b86d87",
  "apiKey": "your-api-key",
  "profile": "Car",
  "preference": "Fastest",
  "locations": [
    { "latitude": -26.2041, "longitude": 28.0473 },
    { "latitude": -26.1452, "longitude": 28.0364 },
    { "latitude": -26.1076, "longitude": 28.0567 },
    { "latitude": -25.9891, "longitude": 28.1275 }
  ]
}
                    

Response

Same format as /api/navigate response — distanceKm, duration, encodedPolyline, and steps.

POST /api/optimize

Fleet Matrix Routing — assign tasks to vehicles optimally. Supports capacity constraints, time windows, multi-depot, chained stops, priority levels, vehicle specialties, and four quality tiers.

Request Body

Field	Type	Required	Description
`accountId`	string	Yes	Your account GUID
`apiKey`	string	Yes	Your API key
`tasks`	RouteTask[]	Yes	Tasks to assign (max 200)
`vehicles`	Vehicle[]	Yes	Available vehicles (max 20)
`mode`	string	No	`Balanced` (default), `Shortest`, or `Fastest`
`quality`	string	No	`Quick` (default), `Standard`, `Refined`, or `Exhaustive`
`chains`	TaskChain[]	No	Task ordering constraints
`departureTime`	DateTimeOffset	No	Departure time (defaults to UTC now)
`includeGeometry`	bool	No	Include road polylines per route

Example Request

POST https://resolt-navora-api.azurewebsites.net/api/optimize
Content-Type: application/json

{
  "accountId": "6ffdea07-8957-49ba-9e0b-5dbce4b86d87",
  "apiKey": "your-api-key",
  "mode": "Balanced",
  "quality": "Refined",
  "includeGeometry": false,
  "vehicles": [
    {
      "id": "v1",
      "name": "Small Van",
      "startDepot": {
        "id": "depot-1",
        "name": "JHB Central",
        "location": { "latitude": -26.2041, "longitude": 28.0473 }
      },
      "endDepot": {
        "id": "depot-1",
        "name": "JHB Central",
        "location": { "latitude": -26.2041, "longitude": 28.0473 }
      },
      "capacity": 50,
      "required": true
    }
  ],
  "tasks": [
    {
      "id": "t1",
      "name": "Deliver to Sandton",
      "location": { "latitude": -26.1076, "longitude": 28.0567 },
      "type": "Delivery",
      "serviceDuration": "00:10:00",
      "demand": 15
    }
  ]
}
                    

Response

{
  "accountId": "6ffdea07-8957-49ba-9e0b-5dbce4b86d87",
  "solution": {
    "quality": "Refined",
    "mode": "Balanced",
    "totalDistanceKm": 42.5,
    "totalDuration": "01:15:00",
    "computedAt": "2025-01-15T10:30:00Z",
    "routes": [
      {
        "vehicleId": "v1",
        "vehicleName": "Small Van",
        "stops": [ ... ],
        "distanceKm": 42.5,
        "duration": "01:15:00"
      }
    ],
    "unassignedTasks": []
  }
}
                    

Enums

All enums can be passed as string names or integer values.

NavigationProfile

`Car`	0	Standard driving profile
`Bike`	1	Bicycle routing

RoutePreference

`Fastest`	0	Minimise travel time
`Shortest`	1	Minimise distance

OptimizationMode

`Balanced`	0	Balance distance and time
`Shortest`	1	Minimise total distance
`Fastest`	2	Minimise total time

SolutionQuality

`Quick`	0	~5 seconds
`Standard`	1	~15 seconds
`Refined`	2	~30 seconds
`Exhaustive`	3	~120 seconds

RouteTaskType

`Delivery`	0	Drop-off task
`Collection`	1	Pick-up task
`Service`	2	On-site service

Models

GeoLocation

Field	Type	Description
`latitude`	double	Latitude in decimal degrees
`longitude`	double	Longitude in decimal degrees

Vehicle

Field	Type	Required	Description
`id`	string	Yes	Unique vehicle identifier
`name`	string	Yes	Display name
`startDepot`	Depot	Yes	Where the vehicle starts
`endDepot`	Depot	Yes	Where the vehicle returns
`capacity`	double?	No	Load capacity
`maxTasks`	int?	No	Maximum tasks this vehicle can handle
`maxDistanceKm`	double?	No	Maximum route distance
`maxDuration`	TimeSpan?	No	Maximum route duration
`required`	bool	No	If true, vehicle must be used
`specialties`	string?	No	Comma-delimited specialties (e.g. `"refrigerated,hazmat"`)

Depot

Field	Type	Required	Description
`id`	string	Yes	Unique depot identifier
`name`	string	Yes	Display name
`location`	GeoLocation	Yes	Depot coordinates

RouteTask

Field	Type	Required	Description
`id`	string	Yes	Unique task identifier
`name`	string	Yes	Display name
`location`	GeoLocation	Yes	Task coordinates
`type`	string	No	`Delivery` (default), `Collection`, or `Service`
`serviceDuration`	TimeSpan?	No	Time spent at location
`timeWindow`	TimeWindow?	No	Earliest/latest arrival constraint
`priority`	int	No	1 (default) = normal, higher = more important
`demand`	double	No	Load demand (counted against vehicle capacity)
`chainId`	string?	No	Chain group identifier
`chainOrder`	int	No	Order within the chain
`specialties`	string?	No	Required vehicle specialties

TaskChain

Field	Type	Required	Description
`chainId`	string	Yes	Matches the `chainId` on tasks
`taskIds`	string[]	Yes	Ordered list of task IDs in this chain
`allowInterleavedStops`	bool	No	If true, other stops may appear between chained tasks

TimeWindow

Field	Type	Description
`earliest`	DateTimeOffset	Earliest allowed arrival
`latest`	DateTimeOffset	Latest allowed arrival