Search Around

Basic principles

This web service allows you to classify a list of resources positioned around a particular point in terms of distance or time. It takes as input a start point (in this case, the target location) and a list of resources with their geographic locations, plus a priority category of either 1 or 2 (this is an optional parameter). The resources are records saved in a database of the user’s choice, depending on their requirements. It is the allotted task of the client to select these resources in the database. The resources are returned sorted firstly on the attribute priority1, and then by time or distance (according to which has been chosen). The priorities are optional. The default value of the priorities is 0. This depends on the configured graph, the name of which has been specified in the Geoconcept Web administration interface.

Search around example

{
  "url": "https://api.geoconcept.com/EU/GCW/geoconcept-web/api/lbs/searchAround/v4.json",
  "method": "POST",
  "body":
  {
      "location": {
        "x": -1.553927,
        "y": 47.21858
      },
      "resources": [
        {
          "id": "1",
          "x": -1.593927,
          "y": 47.18858,
          "priority1": 1,
          "priority2": 1
        },
        {
          "id": "2",
          "x": -1.556927,
          "y": 47.21958,
          "priority1": 2,
          "priority2": 1
        }
      ],
      "method": "time",
      "reverse": "false"
    }
}

Parameters / properties

Input

parameter description optional default

location

Coordinates of the start point (or arrival point)

no

method

Method to compute the route between the start point and the resources:
- distance : shortest route
- time : fastest route
- flying : as the crow flies

yes

time

reverse

if true, the location point is considered as an arrival

yes

false

srs

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

yes

epsg:4326

exclusions

List of restriction rules to use, separated by the ; character
Available exclusion rules:
- Toll
- Infrastructure (Tunnel, Bridge)
- Hazardous material (Flammable, Dangerous, Pollutant, Toxic)
- ZFE (Zone � faible �mission, France-only) - …
- Detailled list available on the FAQ bellow.

yes

resources

List of resources, separated by ";" characters.
Each resource takes the form "id,x,y,node,priority1,priority2"
Priorities are optional.

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 on 21 January 2014, at 9.00am in Paris

yes

snapMethod

Snap to graph method
- standard: to the nearest connectable road segment
- extended: via restricted road sections (pedestrian thoroughfare…)
- nearest: to the nearest road section only
- unrestricted: without any restriction rules
- nodes: snap directly to the nodes indicated by locationNode and the node parameters of ressources or, if locationNode is not filled, snap directly to the nearest node location parameter.

yes

standard

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

configName

Name of the configuration to use:
- bicycle (not available for Japan)
- bus
- car
- delivery light vehicle
- delivery truck vehicle
- emergency truck
- emergency vehicle
- pedestrian (not available for Japan)
- taxi
- truck

yes

computeOptions

Selection of variables to use in calculations, using semi-colons ; as separators:
- speedPattern: utilization as a speed pattern. Use: "speedPattern:slow-speed"
- length: maximum authorised length in centimeters. Use: "length:950"
- width: maximum authorised width in centimeters. Use: "width:255"
- height: maximum authorised height in centimeters. Use: "height:360"
- weight: maximum authorised weight in kilograms. Use: "weight:18000"
- axles: maximum authorised number of axels. Use: "axles:2"
- weightPerAxle: maximum authorised weight per axel in kilograms. Use: "weightPerAxle:9000"
- fuelType: fuel type used to calculate carbon footprint for the journey. Available values are: "UndefinedFuelType", "NoFuel", "Diesel", "UnleadedFuel", "LGP", "CustomFuelType" and "Electrical". Use: "fuelType:Diesel"
- averageConsumption: average consumption in litres for 100 kilometers or Wh per kilometers if electrical vehicle. Use: "averageConsumption:6.45"
- cityAverageConsumption: average consumption value in city mode, in litres per 100 kilometers, or Wh per kilometers if electrical vehicle. Use: "cityAverageConsumption:4.65"
- combinedAverageConsumption: average consumption value in combined mode, in litres per 100 kilometers, or Wh per kilometers if electrical vehicle. Use: "combinedAverageConsumption:5.12"
- highwayAverageConsumption: average consumption value in highway mode, in value in litres per 100 kilometers, or Wh per kilometers if electrical vehicle. Use: "highwayAverageConsumption:5.64" - customAverageCO2UnitEmission: defines the carbon footprint in kilograms per litre. Use: "customAverageCO2UnitEmission:2.724"
- snapSpeed: snap-to-graph speed in kilometers per hour. Use: "snapSpeed:10"

yes

(*) At least one of the two parameters location, and locationNode must be entered.

Output

Search Around

parameter type min/max description

location

couple of double, separated with a comma

0/1

Coordinates of the start point (or arrival point). The longitude and latitude coordinates are separated by the , character.

method

string

0/1

Specified input method (time, distance or flying), and time by default.

srs

string

0/1

Input projection specified.

exclusions

string

0/unlimited

List of rules for specified input restrictions

searchAroundResult

Array of SearchAroundElement

0/unlimited

List of results for each candidate.

Search Around element (SearchAroundElement)

parameter type min/max description

id

string

0/1

Candidate identifier

distanceMeters

double

1/1

Distance in meters

durationSeconds

double

1/1

Time in seconds

Possible returns

Case of a proximity search finding(searchAroundResponse/status is OK) 

{
  "message": null,
  "status": "OK",
  "location": "-1.553927,47.21858",
  "locationNode": null,
  "method": "TIME",
  "srs": "epsg:4326",
  "exclusions": [],
  "searchAroundResult": [
    {
      "id": "1",
      "distanceMeters": 6681,
      "durationSeconds": 877
    },
    {
      "id": "2",
      "distanceMeters": 425,
      "durationSeconds": 100
    }
  ]
}

Case of a snap-to-graph error (searchAroundResponse/status is OK) 

{
  "message": null,
  "status": "OK",
  "location": "47.21858,-1.553927",
  "locationNode": null,
  "method": "TIME",
  "srs": "epsg:4326",
  "exclusions": [],
  "searchAroundResult": [
    {
      "id": "1",
      "distanceMeters": -1,
      "durationSeconds": -1
    },
    {
      "id": "2",
      "distanceMeters": -1,
      "durationSeconds": -1
    }
  ]
}

Case of an absent location parameter (searchAroundResponse/status is ERROR) 

{
  "message":"Location must be not null",
  "status":"ERROR",
  "location":null,
  "locationNode":null,
  "method":null,
  "srs":null,
  "exclusions":[],
  "searchAroundResult":[]
}

Case of an incomplete location parameter, or one with the wrong separator (searchAroundResponse/status is ERROR) 

{
  "message": "Location point must have 2 components separated with a ,",
  "status": "ERROR",
  "location": null,
  "locationNode": null,
  "method": null,
  "srs": null,
  "exclusions": [],
  "searchAroundResult": []
}

Case of the absence of a resource (searchAroundResponse/status is ERROR) 

{
  "message":"resources not defined",
  "status":"ERROR",
  "location":null,
  "locationNode":null,
  "method":null,
  "srs":null,
  "exclusions":[],
  "searchAroundResult":[]
}

Case of a badly formatted resource (searchAroundResponse/status is ERROR) 

{
  "message":"ServiceException: not enough fields in candidate 1,-1.59392",
  "status":"ERROR"
}

FAQ

1. Is it possible to give priority to either journey time or journey distance?
2. How does one structure the classification of returned addresses, in relation to the distance, the time, and to priorities generally?
3. What format should the priority take and is it possible to define a classification order? (increasing/decreasing)
4. If just one address in the list has a priority of 0, is the priority taken into account for one of the addresses in the list?
5. How do you perform a search around calculation without including any road tolls?
6. What are the maximum values allowed by predefined configName?
7. What are the exclusions available?
8. What are the Hazardous material exclusions?
9. What are Speed Patterns? How are they used?
10. How do you use heavy goods vehicle attributes?

1.

Is it possible to give priority to either journey time or journey distance?

Yes, by changing the method: distance, time or flying = as the crow flies (at a speed of 30 km/h)..

2.

How does one structure the classification of returned addresses, in relation to the distance, the time, and to priorities generally?

The classification creates a hierarchy of priority 1 in increasing order, then priority2 in increasing order, then by time or distance as the crow flies in increasing order.

3.

What format should the priority take and is it possible to define a classification order? (increasing/decreasing)

The priority is an integer, and currently the result is always in increasing order. To obtain the reverse ordering, you should put n-priority in the attribute.

4.

If just one address in the list has a priority of 0, is the priority taken into account for one of the addresses in the list?

Currently, a priority of 0 is not treated in any special way. You need to therefore set all priorities to 0 if you want to ignore the criterion.

5.

How do you perform a search around calculation without including any road tolls?

Place the exclusion Toll in exclusions.

6.

What are the maximum values allowed by predefined configName?

See list below:

configName axles weightPerAxle weight height length width

bicycle

bus

2

9500

19000

350

1350

250

car

delivery light vehicle

2

1700

3400

300

680

220

delivery truck vehicle

2

9500

19000

350

1350

250

emergency truck vehicle

2

9000

18000

360

920

255

emergency vehicle

pedestrian

taxi

truck

4

19000

39000

387

1850

255

7.

What are the exclusions available?

See list below:

Exclusion Description

Toll

if added on exclusions toll road sections are not used.

BoatFerry

if added on exclusions ferry itineraries (shipping) over water are not used.

RailFerry

if added on exclusions ferry (or train) itineraries (over water and land respectively) are not used.

Tunnel

if added on exclusions tunnels are not used.

Bridge

if added on exclusions bridges are not used.

Frontage

if added on exclusions Frontage roads (local roads running parallel to a higher-speed, limited-access road) are not used.

Paved

if added on exclusions tarmac road sections are not used.

Private

if added on exclusions road sections for which maintenance is provided by a private organization are not used.

Pedestrians

if added on exclusions road sections unauthorised for pedestrian use are not used. The configName parameter with a value of pedestrian uses this exclusion.

Automobiles

if added on exclusions road sections with restricted automobile access are not used. The configName parameter with a value of car uses this exclusion.

Trucks

if added on exclusions road sections with restricted access for lorries are not used. The configName with a value of truck or delivery truck vehicle or emergency truck uses this exclusion.

Bus

if added on exclusions road sections with restricted access for buses are not used. The configName with a value of bus uses this exclusion.

Deliveries

if added on exclusions road sections with restricted access for deliveries are not used. The configName with a value of delivery light vehicle or delivery truck vehicle uses this exclusion.

Taxis

if added on exclusions road sections with restricted access for taxis are not used. The configName with a value of taxi uses this exclusion.

Emergencies

if added on exclusions road sections with restricted access for emergencies are not used. The configName with a value of emergency truck or emergency vehicle uses this exclusion.

Carpools

if added on exclusions road sections with restricted access for carpools are not used.

Throughtraffic

if added on exclusions road sections with restricted access for non-local traffic are not used.

ZFE

if added on exclusions low carbon emmission areas in France will be excluded

(Hazardous material)

See description bellow.

8.

What are the Hazardous material exclusions?

Hazardous material defines a restriction to a road for any vehicle carrying the specific hazardous material. Hazardous material restrictions are government regulations and can be different per country.

  • Flammable: explosives, flammable, gas, combustible, …
  • Pollutant: goods harmful for water
  • Toxic: organic, poison, radioactive, corrosive, …
  • Dangerous: tunnel categories and others restrictions

9.

What are Speed Patterns? How are they used?

With the aim of suggesting journey times that take traffic conditions into account as accurately as possible, cars and trucks have 5 speed profiles (Speed Patterns) so various levels of road congestion can be taken into account over the timespan of a whole day:

  • standard normal-speed corresponds to the speed at a time when the traffic congestion is moderate (11h)
  • night fast-speed corresponds to very fluid traffic conditions, most often found at night time (3h)
  • busy slow-speed corresponds to the times when traffic congestion is at its densest (8h)
  • peak travel time very-slow-speed corresponds to times when traffic is densest in urban areas, and is slower than the category given above (8h)
  • default default corresponds to average speeds over a whole day

To use these, you will need to pass to parameter, when calling the web service, the following parameter computeOptions with the option speedPattern and specify the value of the Speed Pattern requested, always remembering to include a vehicle configName.
Example:

&computeOptions=speedPattern:fast-speed&configName=car

10.

How do you use heavy goods vehicle attributes?

You need to calculate an itinerary using either a vehicle configName using the restrictions, or by overwriting the call to the web service using the parameter computeOptions with the options length, width, height, weight, axles and/or weightPerAxle.
Example for a journey with a vehicle with a height of 4.5m:

&computeOptions=height:450