Pickup and Delivery

(fr) Cette page n’est plus maintenue depuis la version 2022 de Geoconcept Web. Pour accéder à la documentation à jour de ce web service, veuillez suivre ce lien.

Basic principles

The pickup and delivery service can be used to list the best solutions for pickup/collection and drop-off/delivery, whether for the transport of people or of goods.

The web service takes two types of data input:

  • Existing journeys
  • Pickup/collection points and drop-off/delivery points

The algorithm explores the solutions to find a pair that includes one pick-up point and one drop-off point in the existing journeys. It returns, for each journey, the best detours possible among the candidates (pick-up and drop-off points).

In the case where only one candidate (pickup or drop-off) is available, the web service tries to insert one step in existing journeys instead of two.

Availability

This web service is an option in Geoconcept Web : please contact us to find out how you can purchase the service.

It requires access to an accelerated graph or network.

Parameters / properties

Input

parameter type optional description

routes

array of routes/route (pickupDeliveryRouteInput)

No

Table of journeys as input. Pre-existing journeys in which candidates must be inserted.

pickupPoints

array of pickupPoints/pickupPoint (wayPoint)

Yes

Table of candidate pick-up points to insert in journeys.

deliveryPoints

array of deliveryPoints/deliveryPoint (wayPoint)

Yes

Table of possible drop-off candidates to insert in journeys.

constraints

(pickupDeliveryConstraints)

Yes

Definition of constraints to filter the journeys to use.

sortOptions

(pickupDeliverySortingOptions)

Yes

Definition of the sort on the results.

srs

projection (EPSG code such as epsg:4326 or wgs84)

yes

graphName (depreciated)

Name of the graph to use
This parameter is omitted if the configName parameter is used.

yes

profileId (depreciated)

Vehicle identifier (saved under vehicle profiles)
This parameter is omitted if the configName parameter is used.

yes

profileName (depreciated)

Vehicle profile (saved in the vehicle profiles)
This parameter is omitted if the configName parameter is used.

yes

configName

Name of the configuration to use (defined in Geoconcept Web - Administration / Tools / Road graphs)
This replaces the use of graphName, profileId and profileName

yes

snapMethod

Snap to graph method
- standard: to the nearest connectable road section
- extended: via restricted road sections (pedestrian routes…)
- nearest: to the nearest road section only
- unrestricted: without any restriction rules
- nodes: Snap directly to nodes supplied by the originNode, destinationNode and waypointNodes parameters, or, if these parameters have not been set, to the nearest nodes sourced by the origin, destination and waypoint parameters

yes

standard

exclusions

List of restriction rules to use, separated by the ; character (Example: Toll, Tunnel, Bridge)

yes

startDateTime

Start date and time (format ISO8601: local time) Example: 2014-01-21T09:00:00.000+01:00 (or 2014-01-21T09:00:00.000%2B01:00) for a start date of 21 January 2014, at 9.00am in Paris. Caution: the + character can be misinterpreted by browsers, so in this case, it should be replaced by %2B.

yes

avoidArea

Forbidden transit zone in WKT format (POLYGON or MULTIPOLYGON) in the requested projection (srs parameter)
Example in wgs84: POLYGON ((-1.556892 47.21689, -1.556892 47.216904, [...] -1.556892 47.21689)) - MULTIPOLYGON (((-1.556892 47.21689, -1.556892 47.216904, [...] -1.556892 47.21689)), ((-1.558639 47.218144, -1.558639 47.218193, [...] -1.558639 47.218144)))
Care: WKT geometries must be closed.

yes

size

(pickupDeliverySizes)

No

Number of journeys and candidates to return.

dataVersionHash

string

Yes

Graph identifier (non-utilised)

computeOptions

List of options for the calculation,separated by ; characters
- trafficPatterns: uses routing statistics (you will need to supply a value for the startDateTime parameter and use a graph that includes traffic patterns information)
- speedPattern (M18): uses a speed pattern as defined in the SmartRoutingVehicles.xml file, located in the `‘<GEOCONCEPT_WEB_HOME>’'\smartrouting\jee\smartrouting\conf\ folder. Use as follows: "speedPattern:slow-speed"
- length (M18): maximum authorised length in centimeters (you need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "length:950"
- width (M18): maximum authorised width in centimeters (You will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "width:255"
- height (M18): maximum authorised height in centimeters (you will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "height:360"
- weight (M18): maximum authorised weight in kilograms (you will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "weight:18000"
- axles (M18): maximum authorised number of axles (you will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "axles:2"
- weightPerAxle (M18): maximum authorised weight per axle in kilograms (you will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "weightPerAxle:9000"
- snapSpeed: snap-to-graph speed in kilometers per hour. Use as follows: "snapSpeed:10"

yes

(pickupDeliveryRouteInput) journeys as input

parameter type optional description

id

string

No

Journey identifier

departure

(location)

No

Start point coordinates

arrival

(location)

No

Finish point coordinates

distance

long

Yes

Journey distance (in metres)

duration

long

Yes

Journey duration (in seconds)

waypoints

Array of wayPoint

Yes

List of journey steps

(wayPoint) steps

parameter type optional description

id

string

No

Step identifier

location

(location)

No

Step coordinates

stopoverPosition

long

Yes

Position of the step in the journey, if the step is a stop. If no values are assigned, this step is just a waypoint.

(location) coordinates

parameter type optional description

lat

double

No

Latitude of the point (in wgs84)

long

double

No

Longitude of the point (in wgs84)

nodeId

string

Yes

Graph node. Caution: a physical node does not have the same ID in another graph.

(pickupDeliveryConstraints) constraints

parameter type optional description

maxDetourDuration

long

Yes

Maximum duration of detour (in seconds). Only resulting journeys for which the duration added is less than this limit will be returned by the web service.
The detour duration is defined as:
(duration with detour) - (duration without detour)

minSharedDistance

long

Yes

Minimum value of common distance ratio. Only those resulting journeys for which the common distance ratio exceeds this limit will be returned by the web service.
The common distance ratio is defined as:
(common distance) / (total distance with detour)

(pickupDeliverySortingOptions) sort

parameter type optional description

routesAndCandidatesSortCriterium

(sortCriteriaEnum)

Yes

Sort options:
- MIN_DETOUR_DURATION = sort (ascending) results according to detour duration
- MIN_DETOUR_DISTANCE = sort (ascending) results according to detour distance
- MAX_SHARED_DISTANCE = sort (descending) results according to common distance ratio

(pickupDeliverySizes) number of returns

parameter type optional description

routes

long

No

Maximum number of journeys to return.

candidates

long

No

Maximum number of candidates to return for each journey.

Output

parameter type description

results

array of results/result (pickupDeliveryRouteResult)

List of journeys calculated.

(pickupDeliveryRouteResult) list of journeys calculated

parameter type description

routeId

string

List of journeys calculated.

candidates

array of candidates/candidate (pickupDeliveryRouteCandidate)

List of possible detours for the journey.

(pickupDeliveryRouteCandidate) list of detours possible for the journey

parameter type description

pickup

(meetingPointCandidate)

Pick-up candidate.

delivery

(meetingPointCandidate)

Drop-off candidate.

sharedRouteDuration

long

Common journey duration (in seconds).

sharedRouteDistance

long

Common journey distance (in metres).

totalDurationWithDetour

long

Total journey duration including the detour (in seconds).

totalDistanceWithDetour

long

Total journey distance including the detour (in metres).

detourDuration

long

Detour duration = (duration with detour) - (original journey duration)

detourDistance

long

Detour distance = (distance with detour) - (original journey distance)

sharedDistance

double

Common distance = ratio between (common distance) and (Total journey distance including the detour)

(meetingPointCandidate) candidates

parameter type description

meetingPointId

string

Identifier for the pickup/drop-off location

duration

long

For a pickup link: duration from the journey departure point to the pickup point (in seconds)
For a drop-off point: duration from the journey drop-off point to the arrival point (in seconds)

distance

long

For a pickup link: distance from the journey departure point to the pickup point (in metres)
For a drop-off point: the distance from the journey drop-off point to the arrival point (in metres)

meetingPointSubPath

int

Optimum segment position (in the journey) for the pickup/drop-off point.

REST (POST)

Query

Query  

http://<server>/<webapp>/api/lbs/pickupDelivery.json

Data (JSON)  

{
  "routes" : [ {
    "id" : "trip_1",
    "departure" : {
      "lat" : "47.333990",
      "lon" : "-1.805604"
    },
    "arrival" : {
      "lat" : "47.479740",
      "lon" : "-1.095251"
    },
    "waypoints" : [ {
      "id" : "waypoint_1",
      "location" : {
        "lat" : "47.157530",
        "lon" : "-1.421958"
      }
    }]
  }],
  "pickupPoints" : [ {
    "id" : "depMeet_1",
    "location" : {
      "lat" : "47.228659",
      "lon" : "-1.600995"
    }
  }],
  "deliveryPoints" : [ {
    "id" : "arrMeet_1",
    "location" : {
      "lat" : "47.293823",
      "lon" : "-1.480789"
    }
  }],
  "constraints" : {
    "maxDetourDuration" : 3600,
    "minSharedDistance" : 0.1
  },
  "sortOptions" : {
    "routesAndCandidatesSortCriterium" : "MIN_DETOUR_DURATION"
  },
  "size" : {
    "routes" : 1,
    "candidates" : 1
  }
}

Query Response

The response is always in UTF-8 format.

JSON format  

{
    "message": null,
    "status": "OK",
    "results": [
        {
            "routeId": "trip_1",
            "candidates": [
                {
                    "pickup": {
                        "meetingPointId": "depMeet_1",
                        "duration": 1349,
                        "distance": 23426,
                        "meetingPointSubPath": 0
                    },
                    "delivery": {
                        "meetingPointId": "arrMeet_1",
                        "duration": 2177,
                        "distance": 43159,
                        "meetingPointSubPath": 0
                    },
                    "sharedRouteDuration": 1333,
                    "sharedRouteDistance": 18767,
                    "totalDurationWithDetour": 4860,
                    "totalDistanceWithDetour": 85352,
                    "detourDuration": -577,
                    "detourDistance": -19590,
                    "sharedDistance": 0.21
                }
            ]
        }
    ]
}

FAQ

1. How can I use route statistics?
2. How can I perform a route calculation excluding toll roads?
3. What are Speed Patterns? How can I use them?

1.

How can I use route statistics?

Check that the graph does contain these statistics and use these two parameters: computeOptions with a value of trafficPatterns and startDateTime to specify the departure date/time.

2.

How can I perform a route calculation excluding toll roads?

If the Toll constraint has been included in the graph, place an exclusion in exclusions

3.

What are Speed Patterns? How can I use them?

In order to propose journey times that are as accurate as possible and reflect changing traffic conditions, graphs supplied by GEOCONCEPT SAS include, from version M18 upwards, 5 speed profiles (Speed Patterns) for cars and lorries, to take into account the different levels of congestion during the course of one day:

  • standard normal-speed corresponds to the speed at a time when the roads have an average congestion level (eg 11.00am)
  • night fast-speed corresponds to a very fluid traffic situation, often experienced at night-time (3.00am)
  • congested slow-speed corresponds to the times when traffic is densest (8.00am)
  • rush hour very-slow-speed corresponds to times when traffic is densest in urban and built-up areas, and is slower than the speed above (8.00am)
  • default default corresponds to speeds averaged out over an entire day

To use them, you need to pass to parameter, when calling the web service, the computeOptions parameter with the speedPattern option and specify the value of the Speed Pattern requested, without forgetting a vehicle profile
Example:

+

&computeOptions=speedPattern:fast-speed&profileId=1
How to use Heavy Goods Vehicle attributes?

The graph must include the attributes for Heavy Goods Vehicles (as standard in the graphs supplied by GEOCONCEPT SAS from version M18 upwards) and either calculate an itinerary using a vehicle profile using restrictions (cf. the catalogue of vehicles, editable, defined in the SmartRoutingVehicles.xml file, stored in the folder `‘<GEOCONCEPT_WEB_HOME>’'\smartrouting\jee\smartrouting\conf\ ), or overwrite the call to the web service by using the computeOptions parameter with the options length, width, height, weight, axles and/or weightPerAxle.
Example for a journey with a vehicle 4.5 metres high: 

&computeOptions=height:450
Prev  Up  Next
  Home