1. Overview

Blackbox optimization with supporting services

1.1. Version information

Version : v1_3

1.2. URI scheme

Host : api.rinkai.eu
BasePath : /
Schemes : HTTP, HTTPS

1.3. Tags

  • mapv1_3c

2. Paths

2.1. Given a list of addresses, find their coordinates. For each address, a list of matches will be eventually returned (asynchronously)

POST /map/v1_3c/geocoding/async

2.1.1. Description

Returns a job identifier which can be used to monitor the job’s progress and retrieve the results

2.1.2. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

List of addresses to be geocoded

GeocodingRequest

2.1.3. Responses

HTTP Code Description Schema

200

successful operation

JobStatus

2.1.4. Tags

  • mapv1_3c

2.2. Return the result for the given geocoding job

GET /map/v1_3c/geocoding/async/{id}

2.2.1. Description

If the job is not yet finished, it will block until results are available.

2.2.2. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

job identifier

string

2.2.3. Responses

HTTP Code Description Schema

200

successful operation

GeocodingResponse

2.2.4. Tags

  • mapv1_3c

2.3. Cancel the given geocode job

PUT /map/v1_3c/geocoding/async/{id}/cancel

2.3.1. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

job identifier

string

2.3.2. Responses

HTTP Code Description Schema

default

successful operation

No Content

2.3.3. Tags

  • mapv1_3c

2.4. Return the progress and status of the given geocoding job

GET /map/v1_3c/geocoding/async/{id}/status

2.4.1. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

job identifier

string

2.4.2. Responses

HTTP Code Description Schema

200

successful operation

JobStatus

2.4.3. Tags

  • mapv1_3c

2.5. Geocoding

POST /map/v1_3c/geocoding/sync

2.5.1. Description

Given a list of addresses, find their coordinates. For each address, a list of matches will be returned

2.5.2. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

List of addresses to be geocoded

GeocodingRequest

2.5.3. Responses

HTTP Code Description Schema

200

successful operation

GeocodingResponse

2.5.4. Tags

  • mapv1_3c

2.6. Map rendering

POST /map/v1_3c/map

2.6.1. Description

Renders a map as a raster image in png format. Annotations such as waypoints are supported. It can be used to produce offline images, and is fast enough to be used interactively. For the best user experience though, client rendering is recommended e.g. with Leaflet or OpenLayers. Please see the examples section to see integration of routing/optimizing with Leaflet

2.6.2. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

Description of the map to be rendered

MapRequest

2.6.3. Responses

HTTP Code Description Schema

200

successful operation

MapResponse

2.6.4. Tags

  • mapv1_3c

2.7. Optimize the sequence (asynchronously)

POST /map/v1_3c/optimization/async

2.7.1. Description

Returns a job identifier which can be used to monitor the job’s progress and retrieve the results

2.7.2. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

Description of the distribution problem to be optimized

VrpRequest

2.7.3. Responses

HTTP Code Description Schema

200

successful operation

JobStatus

2.7.4. Tags

  • mapv1_3c

2.8. Return the optimization result for the given job

GET /map/v1_3c/optimization/async/{id}

2.8.1. Description

If the job is not yet finished, it will block until results are available.

2.8.2. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

job identifier

string

2.8.3. Responses

HTTP Code Description Schema

200

successful operation

VrpResponse

2.8.4. Tags

  • mapv1_3c

2.9. Cancel the given optimization job

PUT /map/v1_3c/optimization/async/{id}/cancel

2.9.1. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

job identifier

string

2.9.2. Responses

HTTP Code Description Schema

default

successful operation

No Content

2.9.3. Tags

  • mapv1_3c

2.10. Return the progress and status of the given optimization job

GET /map/v1_3c/optimization/async/{id}/status

2.10.1. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

job identifier

string

2.10.2. Responses

HTTP Code Description Schema

200

successful operation

JobStatus

2.10.3. Tags

  • mapv1_3c

2.11. Optimize the sequence (synchronously)

POST /map/v1_3c/optimization/sync

2.11.1. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

Description of the distribution problem to be optimized

VrpRequest

2.11.2. Responses

HTTP Code Description Schema

200

successful operation

VrpResponse

2.11.3. Tags

  • mapv1_3c

2.12. Routing

POST /map/v1_3c/routing

2.12.1. Description

Compute the optimal routes on the road for an M to N matrix

2.12.2. Parameters

Type Name Description Schema Default

Query

key
required

Your API key

string

Body

body
required

Points to be routed to and from

RoutingRequest

2.12.3. Responses

HTTP Code Description Schema

200

successful operation

RoutingResponse

2.12.4. Tags

  • mapv1_3c

3. Definitions

3.1. Address

Address fields used for geocoding. For unstructured search, use the freetext field,and for structured search use the corresponding fields (i.e. city, street, etc)

Name Description Schema

city
optional

Used for structured search

string

country
optional

Used for structured search

string

county
optional

Used for structured search

string

freeText
optional

Freetext address. Using commas to seperate the components yields better results e.g. Flat 2, 12 Arbour Road, Highbury, London N13NW, United Kingdom

string

houseNumber
optional

Used for structured search

string

postCode
optional

Used for structured search

string

state
optional

Used for structured search

string

street
optional

Used for structured search

string

suburb
optional

Used for structured search

string

3.2. AddressMatch

A single position returned for geocoding an address

Name Description Schema

airDistanceToRefLocationMeters
optional

If a refLocation was provided, this field contains the air distance from the refLocation to the address

number(double)

areaKm2
optional

Area of the address, in square kilometers

number(double)

bbox
required

Bounding box of the match

Area

coordinates
optional

Coordinates of the address

Coordinates

distanceToKnownSamePostCodeMeters
optional

Distance to the nearest known point were the same postcode is used

number(double)

internalScore
optional

The confidence attached to this result. A higher number indicates a higher confidence.

number(double)

matchingAddress
optional

The address found matching the request

Address

routableFromRefLocation
optional

If a refLocation was provided, this field indicates whether a route could be found between refLocation and the geocoded coordinates
Default : false

boolean

3.3. AddressWithId

Address fields ussed for geocoding + id

Name Description Schema

city
optional

Used for structured search

string

country
optional

Used for structured search

string

county
optional

Used for structured search

string

freeText
optional

Freetext address. Using commas to seperate the components yields better results e.g. Flat 2, 12 Arbour Road, Highbury, London N13NW, United Kingdom

string

houseNumber
optional

Used for structured search

string

id
optional

arbitrary id of the address

string

postCode
optional

Used for structured search

string

state
optional

Used for structured search

string

street
optional

Used for structured search

string

suburb
optional

Used for structured search

string

3.4. Area

An area is defined by the rectangle between 2 coordinates. Note that when an Area is used inside a request the two fields do not need to be actually the top left and bottom right corner, any combination of opposite corners is fine

Name Description Schema

max
required

North-East corner’s coordinates

Coordinates

min
required

South-West corner’s coordinates

Coordinates

3.5. BaseResponseStats

Contains meta metrics

Name Description Schema

creditsLeft
required

creditsLeft

number(double)

info
required

information in text format

string

3.6. BasicVehicleInfo

Information regarding the vehicle, used to compute the feasability of a given route on the road, but also its time, distance and hence its cost. To retrieve the fastest route, specify a cost per hour of 1 and a cost per km of 0, and vice-versa for the shortest route.

Name Description Schema

avoidTollRoads
optional

Prevent the vehicle from driving on a toll road. Note that since the toll is applied according to the gross vehicle weight, the field grossWeightTon must also be set to avoid toll roads. Default value is false.
Default : false

boolean

costsPerHour
required

Costs of the vehicle , used for driving, loading, unloading, waiting etc. Either the cost per hour or per kilometer must be >0. Default value is 1.

number(double)

costsPerKm
required

Costs of the vehicle per kilometer. Either the cost per hour or per kilometer must be >0. Default value is 0.

number(double)

grossWeightTon
optional

Gross vehicle weight

number(double)

heightMeter
optional

Height of the vehicle, in meters

number(double)

limitToCountryIso
optional

List of strings representing countries onto which the vehicle is allowed to drive. The country is specified in ISO 3166-2 format (e.g. es for Spain, tr for Turkey, etc). Default is empty, which means all countries are allowed.

< string > array

widthMeter
optional

Width of the vehicle, in meters

number(double)

3.7. Coordinates

A point on the Map

Name Description Schema

label
optional

string

x
required

x, or longitude

number(double)

y
required

y, or latitude

number(double)

3.8. Depot

Name Description Schema

adminTimeInSeconds
optional

Administrative time required after the arrival of a vehicle. Specified in seconds

integer(int32)

adminTimeOutSeconds
optional

Administrative time required after loading and before a vehicle leaves the depot. Specified in seconds

integer(int32)

location
required

Location of the depot

Location

timeWindow
optional

Opening time of the depot, defining from when vehicles can start and up to when vehicles have to be back.

TimeWindow

3.9. DimensionsCost

Name Description Schema

costsPerOther
optional

Costs of the vehicle per other

number(double)

costsPerVolume
optional

Costs of the vehicle per volume

number(double)

costsPerWeight
optional

Costs of the vehicle per weight

number(double)

3.10. DurationLimitation

Name Description Schema

breakDurationSeconds
optional

Driving/Usage breaks duration

integer(int32)

breakEnabled
optional

Determines, if driving/usage breaks are enabled
Default : false

boolean

breakPeriodSeconds
optional

Period of driving/usage breaks

integer(int32)

limitSeconds
optional

Driving/Usage time limit for the vehicle

integer(int32)

limited
optional

Determines, if driving/usage time of the vehicle is limited
Default : false

boolean

3.11. ErrorMessage

Name Description Schema

errorCode
required

Error code

enum (CANNOT_GEOCODE_LOCATION, CANNOT_ROUTE_TO_LOCATION, CANNOT_PLAN_LOCATION, FATAL_OPT_ERROR, FATAL_INTERNAL_ERROR, CANCELLED_BY_USER)

errorMessage
required

Description of the error, in English

string

3.12. GeocodingRequest

Request to find coordinates given addresses

Name Description Schema

addresses
required

List of addresses

Address

refLocation
optional

Location of the depot, if specified, a check will be performed to ensure that the geocoded addreses are routable from this point. This is typically the depot’s location

Location

3.13. GeocodingResponse

Response for a GeocodingRequest

Name Description Schema

bbox
required

Bounding box of the whole response, including the refLocation if specified

Area

matchesForRequestedAddresses
optional

List of matches per requested address. The matches are in the same order as in the request

MatchesForRequestedAddress

request
optional

The geocoding request, with optinally geocoded refLocation

GeocodingRequest

stats
required

Stats e.g. time spent, credits left…

BaseResponseStats

3.14. JobStatus

Information about the progress of a geocoding or optimization job

Name Description Schema

details
optional

Details regarding the progress

string

finalStatus
optional

final status of the job

enum (COMPLETED, FAILED)

jobId
required

Job identifier

string

progress
required

Estimated progress of the job, 0 means not started, 1 is done

number(double)

3.15. Load

Name Description Schema

other
optional

Third dimension of capacity, that can be carried by vehicle

number(double)

volume
optional

Volume that can be carried by vehicle. Specified in arbitrary units (usually palettes or m3).. The same unit must be used when specifying orders' volume

number(double)

weight
optional

Weight that can be carried by vehicle. Specified in arbitrary units (usually kg). The same unit must be used when specifying orders' weight

number(double)

3.16. Location

A location either defined by its address or coordinates

Name Description Schema

address
optional

Address of the location

AddressWithId

coordinates
optional

if not specified, the coordinate will be geocoded based on the address

Coordinates

3.17. LocationAndOrder

Specifies a pickup/delivery

Name Description Schema

locationInfo
required

Information about the customer location

LocationInfo

orderId
optional

external id of the order

string

orderInfo
optional

Information specific to the order picked/delivered

OrderInfo

vehicleTypeRestrictions
optional

List of strings, where each string is a flag representing a vehicle’s capability which is required for this location and/or order (e.g. refrigerator,crane,lifting platform,etc).

< string > array

3.18. LocationAndOrderErrorMessage

Describes an error that prevented an order to be planned

Name Description Schema

error
optional

The reason why the order could not be planned

ErrorMessage

locationAndOrder
optional

The order that could not be planned

LocationAndOrder

3.19. LocationInfo

Information regarding a customer location

Name Description Schema

grossVehicleWeightLimitTons
optional

Maximum Gross Vehicle Weight authorized for vehicles at this location, in tons

number(double)

location
required

Address and/or coordinates of the customer

Location

timeWindow1
optional

1st time window

TimeWindow

timeWindow2
optional

2nd time window

TimeWindow

3.20. MapRequest

Request a bitmap image of the map. Either geometry or geometryAroundArea must be defined

Name Description Schema

geometry
optional

Specifies which area should be displayed on the map, around a given center coordinates

MapRequestGeometry

geometryAroundArea
optional

Specifies which area should be displayed on the map

MapRequestGeometryAroundArea

pois
optional

List of individual points to be shown as markers on the map. The id field of each point will used as label

Coordinates

traces
optional

List of traces to be shown on the map

Trace

3.21. MapRequestGeometry

Specifies an exact map geometry

Name Description Schema

center
required

Center of the map

Coordinates

viewportHeight
required

Height of the returned image

integer(int32)

viewportWidth
required

Width of the returned image

integer(int32)

zoomLevel
required

Level of zoom, allowed values range from 3 (largest scale, to display countries/continents) to 18 (lowest scale, to display individual buildings)

integer(int32)

3.22. MapRequestGeometryAroundArea

Partially specifies the map geometry, so that the given area fits inside the viewport

Name Description Schema

area
optional

Area that should be displayed. If not set, the area will be computed based on other elements of the map request , e.g. waypoints

Area

paddingPix
optional

Minimum padding around the area in pixels (default 30)

integer(int32)

viewportHeight
required

Height of the returned image

integer(int32)

viewportWidth
required

Width of the returned image

integer(int32)

3.23. MapResponse

Contains a map image, in PNG format

Name Description Schema

area
required

The area displayed on the map

Area

fullyLoaded
required

Indicates whether the map is fully assembled. If false, some areas might be grayed out or with a lower resolution, and hence the client should display the image, and after a short delay repeat the request
Default : false

boolean

imageBytes
required

Png image, encoded in base 64. E.g. to render in javascript, use something like: $('#map').attr('src', 'data:image/png;base64,' + mapResponse.imageBytes).

string

stats
required

Stats e.g. time spent, credits left…

BaseResponseStats

usedGeometry
required

The actual geometry used to display the map (i.e. center coordinates, zoomlevel and viewport size)

MapRequestGeometry

3.24. MatchesForRequestedAddress

Possible coordinates for a given address

Name Description Schema

bbox
optional

Bounding box of all the matches, if any

Area

matches
optional

List of matches ordered in decreasing order of confidence

AddressMatch

requestedAddress
optional

Address searched for

Address

3.25. OrderInfo

Name Description Schema

load
optional

dimensions of the order to deliver

Load

loadBack
optional

dimensions of the order to pick

Load

timeAtCustomer
optional

administrative and (un)loading time at customer, in seconds

integer(int32)

3.26. Plan

Contains the plan, i.e. the list of routes that include all orders, if such plan exists. If it is not possible to find a valid plan, a partial plan will be returned

Name Description Schema

bbox
optional

Bounding box containing all the routes in the plan

Area

expectedTotalCosts
required

Estimated costs after the planning of unplanned orders, defined as the cost of planned orders, plus the cost of direct roads for each unplanned order

number(double)

expectedTotalKms
required

Estimated total distance in km after the planning of unplanned orders, defined as the cost of planned orders, plus the distance of direct roads for each unplanned order

number(double)

expectedTotalTimeSeconds
required

Estimated total time in seconds after the planning of unplanned orders, defined as the cost of planned orders, plus the time of direct roads for each unplanned order

integer(int32)

plannedCosts
required

Costs for the delivery of planned orders

number(double)

plannedKms
required

Total distance in km for the delivery of planned orders

number(double)

plannedTimeSeconds
required

Total time in seconds for the delivery of planned orders

integer(int32)

routes
optional

List of routes

Route

unplannedOrders
required

Number of orders wich could not be planned

integer(int32)

3.27. Point2PointRoute

Route to go from one point to another

Name Description Schema

bbox
optional

Bounding box of the routes

Area

coordinatesPolyline
optional

string

distanceKm
optional

Distance of this route, in kms

number(double)

found
required

Indicates whether a route was found or not
Default : false

boolean

timeSeconds
optional

Estimation of the duration of this route, in seconds

integer(int32)

violationCnt
required

Total number of violations on this road

integer(int32)

violations
optional

List of violations on this road. Only populated when the detailedTrace field of the request’s BasicVehicleInfo is true

Violation

3.28. Route

Name Description Schema

bbox
optional

Bounding box of the route

Area

drivingDistanceMeters
required

Driving distance in meters

integer(int32)

drivingTimeSeconds
required

Driving time in seconds

integer(int32)

endTime
required

End time, right after unloading and administrative time. In seconds since midnight

TimeOfDay

legs
required

List of legs

Point2PointRoute

load
required

Weight of the goods loaded at the depot for this route

Load

loadBack
required

Volume of the goods loaded at the depot for this route

Load

minimalGrossVehicleWeightLimitTons
required

Minimal Gross Vehicle Weight limit of all visited customer

number(double)

startTime
required

Start time at the depot; loading of goods starts at this time. In seconds since midnight

TimeOfDay

stops
required

List of stops

Stop

vehicle
required

Vehicle planned for this route

Vehicle

waitingTimeOnReturnToDepotSeconds
required

Waiting time on way back to the depot

integer(int32)

3.29. RoutingRequest

Request to compute routes to go from N to M points. Please note that the algorithm is optimized for large matrices, but for a single point to point route it is relatively slow.

Name Description Schema

basicVehicleInfo
optional

Vehicle properties used to compute the feasability and cost of a given road

BasicVehicleInfo

detailedTraces
optional

Indicates that the routes' waypoints should be returned in the response
Default : false

boolean

pointsM
required

list of points defining the matrix 1st dimension

Coordinates

pointsN
required

list of points defining the matrix 2nd dimension

Coordinates

3.30. RoutingResponse

List of routes as a response for a RoutingRequest

Name Description Schema

bbox
optional

Bounding box that contains all routes

Area

routes
optional

Unidimensional list of routes. Given a request for a M x N matrix, the index of the route m to n corresponds to [m*M+n] ( e.g, the index of the route from m=2 to n=3 is 2*M+3

Point2PointRoute

stats
required

Stats e.g. time spent, credits left…

BaseResponseStats

3.31. Stop

Describes a stop inside a route. A Stop always corresponds to a delivery/pick up of an order,except for the last stop of the route, which might be included because it was requested explicitely for the vehicle

Name Description Schema

arrivalTime
required

Time of arrival at location. In seconds since midnight

TimeOfDay

departureTime
required

Time of departure from location. In seconds since midnight

TimeOfDay

location
optional

location of the stop. When the reason is Order, the location is same as in the locationAndOrder

Location

locationAndOrder
optional

Corresponding order

LocationAndOrder

reason
optional

Describe the reason for the stop: Depot,Order,Last

string

waitingTime
optional

Waiting time in seconds, before the delivery/pick up can be performed

integer(int32)

3.32. TimeOfDay

Local time of day

Name Description Schema

hour
optional

hour

integer(int32)

minutes
optional

minutes

integer(int32)

seconds
optional

seconds

integer(int32)

3.33. TimeWindow

Describes a slot of time when a resource is available. Used for Vehicles, and for Orders (An Order can specify 2 time windows)

Name Description Schema

from
required

start of the time window, in seconds since midnight

TimeOfDay

to
required

end of the time window, in seconds since midnight

TimeOfDay

3.34. Trace

A list of points to be displayed on the map as a continuous line

Name Description Schema

color
optional

Color of the line e.g. red,yellow,orange green blue…

string

coordinatesPolylines
required

List of strings where each string is a lists of points encoded with Google Polyline Encoding

string

3.35. Vehicle

Name Description Schema

availability
optional

Determines the time, when the vehicle is available

TimeWindow

basicVehicleInfo
optional

Vehicle properties used to compute the optimal routes on the road from one point to another

BasicVehicleInfo

costsPerStop
optional

Costs of the vehicle per stop

number(double)

doNotFinishAtDepot
optional

Whether the vehicle should return to the depot after the last order on the last route
Default : false

boolean

drivingTimeLimitation
optional

Determine driving time limits

DurationLimitation

fixedCosts
optional

Fixed costs for using the vehicle. Not taken into account if the vehicle is not used for routing.

number(double)

id
required

arbitrary id of the vehicle

string

lastStop
optional

Forces this location to be the last stop of the route (when doNotFinishAtDepot is true), or the second-to-last stop (when doNotFinishAtDepot is false, in which case the last stop is the depot)

Location

loadCosts
optional

Costs of the load for deliveries

DimensionsCost

loadCostsBack
optional

Costs of the load for pickups

DimensionsCost

maxLoad
optional

maximum load, i.e. capacity of the vehicle

Load

maxRoutes
optional

Maximumum number of routes for this vehicle

integer(int32)

skipLastLegFinishingAtDepot
optional

Whether the last leg should be included in the metrics and traces, only applicable when doNotFinishAtDepot is false
Default : false

boolean

timeAtDepotSeconds
optional

When defined, changes the loading time at depot this fixed value in seconds and unloading time at depot to zero

integer(int32)

usageTimeLimitation
optional

Determine usage time limits

DurationLimitation

vehicleTypes
optional

List of strings where each string is a flag representing a vehicle capability. e.g crane, refrigerator,…

< string > array

3.36. Violation

A Violation is when a road limitation is not respected, e.g. a road where the maximum gross weight of the vehicle exceeds the road limitation.

Name Description Schema

coordinates
required

Point where the violation happened

Coordinates

type
required

Type of the limitation which is not respected, e.g. maxweight,toll,etc

string

value
optional

Value of the limitation which is not respected, e.g.in case of a maxweight limitation, 3.5 would be a common values

number(double)

3.37. VrpRequest

Name Description Schema

depot
required

Depot, i.e. starting point of each route

Depot

detailedTraces
optional

Whether the routes returned should include metrics and waypoints (true) or should include only metrics (false)
Default : false

boolean

engine
optional

optimization engine. Valid values are RinkaiOpt(default),Brute and NoOp

string

flags
optional

debug/dev flags

string

locationsAndOrders
required

List of orders to be picked or delivered

LocationAndOrder

vehicles
optional

List of vehicles available. If not specified, a single vehicle is used

Vehicle

3.38. VrpResponse

The result of the optimization. It contains some meta information such as errors on individual orders, and a plan which is a near-optimal solution.

Name Description Schema

fullyPlanned
required

Indicates whether all the locations and orders are included in the solution
Default : false

boolean

generalError
required

Describes the error in case a solution could not be provided at all

ErrorMessage

invalidLocations
required

List of location and orders which could not be included in the solution, and the reason

LocationAndOrderErrorMessage

plan
optional

Solution for the optimization request

Plan

request
optional

The optimization request, with geocoded locations

VrpRequest

stats
required

Stats e.g. time spent, credits left…

BaseResponseStats