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.

Availability

This web service is available at all times with Geoconcept Web and a graph or network.

Version change

Earlier versions of the web service are conserved in Geoconcept Web to ensure compatibility with earlier software developments. We reommend using the most recent version.

Changes in relation to v4

Addition of "maxCost", "timeOut" and "computeOptions" parameters.
Addition in the "nodes" snapMethod of snapping to nearest nodes.

Changes in relation to v3

Addition of the notion of mode, faster, to snap to graph nodes rather than to geographic coordinates. Addition of the following elements: "locationNode", of the "node" parameter in resources, and "nodes" in snapMethods.
Addition of the "graphName", "profileId", "profileName", "avoidArea" and "configName" parameters.

Changes in relation to v2

Addition of the "snapMethod" parameter
Deletion of the "targetX" and "targetY" double type parameters, replaced by the string type parameter "location"
Deletion of the "searchMethod" parameter, replaced by "method"
Deletion of the "rejectFlags" parameter, replaced by "exclusions"
Deletion of the "projection" parameter, replaced by "srs"
The "distances" parameter has been renamed "distanceMeters" and it has changed type from integer to double
The "time" parameter has been renamed "durationSeconds" and has changed type from integer to double

V4

Parameters / properties

Input

parameter	description	optional	default
location	Coordinates of the start point (or arrival point) in SOAP, points are stored in the "x" and "y" parameters themselves in the "geographicPoint" parameter in REST, the points are separated by the , character	yes *
locationNode	Start node (or arrival node). Care: a physical node does not have the same ID in another graph.	yes *
method	The shortest (distance) or fastest (time) route, or the route as the crow flies (flying)	yes	time
reverse	if true, the target is considered as an arrival	yes	false
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
exclusions	List of restriction rules to use, separated by the ";" character (Example: Toll; Tunnel; Bridge)	yes
resources	List of resources, separated by ";" characters. Each resource takes the form "id,x,y,node,priority1,priority2"	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 departure on 21 January 2014, at 9.00am in Paris. Caution: the + character can be misinterpreted by browsers, so it is best to substitute it when encountered with %2B.	yes
snapMethod	Snap to graph method - standard: to the nearest connectable road segment - extended: via restricted road sections (pedestrian routes…) - nearest: to the nearest road section only - unrestricted: without any restriction rules - nodes: snap directly to the nodes provided by the locationNode parameter, or, if no value is assigned, to the node(s) nearest to the location parameter	yes	standard
graphName (depreciated)	Name of the graph to use This parameter is omitted if the configName parameter is used.	yes
profileId (depreciated)	Vehicle identifier (saved in the 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
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 (defined in Geoconcept Web - Administration / Tools / Road graphs) This replaces the use of graphName, profileId and profileName	yes
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
maxCost	Maximum cost not to exceed in the calculation -1: no maximum cost to take into account 0: take the default value defined in the SmartRouting Server configuration if not: value in metres if method=distance or in seconds if method=time	yes
timeOut	Time out for the calculation (in milliseconds)	yes

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

(M18) Available from version M18 and later versions of graphs supplied by GEOCONCEPT SAS.

Output

Search Around (searchAroundWebResultsV4)

parameter	type	min/max	description
location	double	0/1	Coordinates of the start point (or arrival point) in SOAP, points are stored in the "x" and "y" parameters themselves in the "geographicPoint" parameter in REST, the points 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	searchAroundWebResultV4 (or array in JSON / JSON-P)	0/unlimited	List of results for each candidate.

Search Around element (searchAroundWebResultV4)

parameter	type	min/max	description
id	string	0/1	Candidate identifier
distanceMeters	double	1/1	Distance in metres
durationSeconds	double	1/1	Time in seconds

SOAP

WSDL

http://<server>/<webapp>/api/ws/searchAroundService?wsdl

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:searchAroundV4>
         <!--Optional:-->
         <request>
            <location>
               <x>-1.553927</x>
               <y>47.218580</y>
            </location>
            <!--Optional:-->
            <locationNode></locationNode>
            <!--Optional:-->
            <method>time</method>
            <reverse></reverse>
            <!--Optional:-->
            <srs></srs>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <resources>
               <!--Zero or more repetitions:-->
               <resource>
                  <x>-1.593927</x>
                  <y>47.188580</y>
                  <!--Optional:-->
                  <id>1</id>
                  <!--Optional:-->
                  <node></node>
                  <!--Optional:-->
                  <priority1>1</priority1>
                  <!--Optional:-->
                  <priority2>2</priority2>
               </resource>
               <resource>
                  <x>-1.556927</x>
                  <y>47.219580</y>
                  <!--Optional:-->
                  <id>2</id>
                  <!--Optional:-->
                  <node></node>
                  <!--Optional:-->
                  <priority1>1</priority1>
                  <!--Optional:-->
                  <priority2>2</priority2>
               </resource>
            </resources>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <snapMethod></snapMethod>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <avoidArea></avoidArea>
            <!--Optional:-->
            <configName></configName>
            <!--Optional:-->
            <computeOptions></computeOptions>
            <!--Optional:-->
            <maxCost></maxCost>
            <!--Optional:-->
            <timeOut></timeOut>
         </request>
      </sch:searchAroundV4>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:searchAroundV4Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <SearchAroundResult>
            <status>OK</status>
            <location>-1.553927,47.21858</location>
            <method>time</method>
            <srs/>
            <exclusions/>
            <searchAroundResult>
               <id>2</id>
               <distanceMeters>424.0</distanceMeters>
               <durationSeconds>100.0</durationSeconds>
            </searchAroundResult>
            <searchAroundResult>
               <id>1</id>
               <distanceMeters>6682.0</distanceMeters>
               <durationSeconds>942.0</durationSeconds>
            </searchAroundResult>
         </SearchAroundResult>
      </ns2:searchAroundV4Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/searchAround/v4.json?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1

JSON-P query

http://<server>/<webapp>/api/lbs/searchAround/v4.json?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/searchAround/v4.xml?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1

Response

The response is always in UTF-8 format.

JSON format

{
   "message": null,
   "status": "OK",
   "location": "-1.593927,47.21858",
   "locationNode": null,
   "method": "time",
   "srs": null,
   "exclusions": [],
   "searchAroundResult":    [
            {
         "id": "2",
         "distanceMeters": 4474,
         "durationSeconds": 796
      },
            {
         "id": "1",
         "distanceMeters": 10453,
         "durationSeconds": 1114
      }
   ]
}

JSON-P format

myCallback(
    {
       "message": null,
       "status": "OK",
       "location": "-1.593927,47.21858",
       "method": "time",
       "srs": null,
       "exclusions": [],
       "searchAroundResult":    [
                {
             "id": "2",
             "distanceMeters": 4474,
             "durationSeconds": 796
          },
                {
             "id": "1",
             "distanceMeters": 10453,
             "durationSeconds": 1114
          }
       ]
    }
);

XML format

<searchAroundResponseV4>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distanceMeters>4474.0</distanceMeters>
      <durationSeconds>796.0</durationSeconds>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distanceMeters>10453.0</distanceMeters>
      <durationSeconds>1114.0</durationSeconds>
   </searchAroundResult>
</searchAroundResponseV4>

Possible responses

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

<searchAroundResponseV4>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distanceMeters>4474.0</distanceMeters>
      <durationSeconds>796.0</durationSeconds>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distanceMeters>10453.0</distanceMeters>
      <durationSeconds>1114.0</durationSeconds>
   </searchAroundResult>
</searchAroundResponseV4>

Case of a problem with the graph: file missing, faulty filepath, etc… (searchAroundResponse/status is OK)

<searchAroundResponseV4>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponseV4>

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

<searchAroundResponseV4>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponseV4>

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

<searchAroundResponseV4>
   <message>Location must be not null</message>
   <status>ERROR</status>
</searchAroundResponseV4>

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

<searchAroundResponseV4>
   <message>Location point must have 2 components separated with a ,</message>
   <status>ERROR</status>
</searchAroundResponseV4>

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

<searchAroundResponseV4>
    <message>resources not defined</message>
    <status>ERROR</status>
</searchAroundResponseV4>

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

<serviceResult>
   <message>ServiceException: not enough fields in candidate 1.-1.5939</message>
   <status>ERROR</status>
</serviceResult>

V3

Parameters / properties

Input

parameter	description	optional	default
location	Coordinates of the start point (or arrival point) in SOAP, points are stored in the "x" and "y" parameters themselves in the "geographicPoint" parameter in REST, the points are separated by the , character	yes *
locationNode	Start node (or arrival node). Care: a physical node does not have the same ID in another graph.	yes *
method	The shortest (distance) or fastest (time) route, or the route as the crow flies (flying)	yes	time
reverse	if true, the target is considered as an arrival	yes	false
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
exclusions	List of restriction rules to use, separated by the ";" character (Example: "Toll"; "Tunnel"; "Bridge")	yes
resources	List of resources, separated by ";" characters. Each resource takes the form "id,x,y,node,priority1,priority2"	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 departure on 21 January 2014, at 9.00am in Paris. Caution: the + character can be misinterpreted by browsers, so it is best to substitute it when encountered with %2B.	yes
snapMethod	Snap to graph method - standard: to the nearest connectable road segment - extended: via restricted road sections (pedestrian routes…) - 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 resources	yes	standard
graphName	Name of the graph to use This parameter is omitted if the configName parameter is used.	yes
profileId	Vehicle identifier (saved in the vehicle profiles) This parameter is omitted if the configName parameter is used.	yes
profileName	Vehicle profile (saved in the vehicle profiles) This parameter is omitted if the configName parameter is used.	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
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

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

Output

Search Around (searchAroundWebResultsV3)

parameter	type	min/max	description
location	double	0/1	Coordinates of the start point (or arrival point) in SOAP, points are stored in the "x" and "y" parameters themselves in the "geographicPoint" parameter in REST, the points 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	searchAroundWebResultV3 (or array in JSON / JSON-P)	0/unlimited	List of results for each candidate.

Search Around element (searchAroundWebResultV3)

parameter	type	min/max	description
id	string	0/1	Candidate identifier
distanceMeters	double	1/1	Distance in metres
durationSeconds	double	1/1	Time in seconds

SOAP

WSDL

http://<server>/<webapp>/api/ws/searchAroundService?wsdl

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:searchAroundV3>
         <!--Optional:-->
         <request>
            <location>
               <x>-1.553927</x>
               <y>47.218580</y>
            </location>
            <!--Optional:-->
            <locationNode></locationNode>
            <!--Optional:-->
            <method>time</method>
            <reverse></reverse>
            <!--Optional:-->
            <srs></srs>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <resources>
               <!--Zero or more repetitions:-->
               <resource>
                  <x>-1.593927</x>
                  <y>47.188580</y>
                  <!--Optional:-->
                  <id>1</id>
                  <!--Optional:-->
                  <node></node>
                  <!--Optional:-->
                  <priority1>1</priority1>
                  <!--Optional:-->
                  <priority2>2</priority2>
               </resource>
               <resource>
                  <x>-1.556927</x>
                  <y>47.219580</y>
                  <!--Optional:-->
                  <id>2</id>
                  <!--Optional:-->
                  <node></node>
                  <!--Optional:-->
                  <priority1>1</priority1>
                  <!--Optional:-->
                  <priority2>2</priority2>
               </resource>
            </resources>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <snapMethod></snapMethod>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <avoidArea></avoidArea>
            <!--Optional:-->
            <configName></configName>
         </request>
      </sch:searchAroundV3>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:searchAroundV3Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <SearchAroundResult>
            <status>OK</status>
            <location>-1.553927,47.21858</location>
            <method>time</method>
            <srs/>
            <exclusions/>
            <searchAroundResult>
               <id>2</id>
               <distanceMeters>424.0</distanceMeters>
               <durationSeconds>147.0</durationSeconds>
            </searchAroundResult>
            <searchAroundResult>
               <id>1</id>
               <distanceMeters>6682.0</distanceMeters>
               <durationSeconds>1059.0</durationSeconds>
            </searchAroundResult>
         </SearchAroundResult>
      </ns2:searchAroundV3Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/searchAround/v3.json?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1

JSON-P query

http://<server>/<webapp>/api/lbs/searchAround/v3.json?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/searchAround/v3.xml?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1

Response

The response is always in UTF-8 format.

JSON format

{
   "message": null,
   "status": "OK",
   "location": "-1.593927,47.21858",
   "locationNode": null,
   "method": "time",
   "srs": null,
   "exclusions": [],
   "searchAroundResult":    [
            {
         "id": "2",
         "distanceMeters": 4474,
         "durationSeconds": 796
      },
            {
         "id": "1",
         "distanceMeters": 10453,
         "durationSeconds": 1114
      }
   ]
}

JSON-P format

myCallback(
    {
       "message": null,
       "status": "OK",
       "location": "-1.593927,47.21858",
       "method": "time",
       "srs": null,
       "exclusions": [],
       "searchAroundResult":    [
                {
             "id": "2",
             "distanceMeters": 4474,
             "durationSeconds": 796
          },
                {
             "id": "1",
             "distanceMeters": 10453,
             "durationSeconds": 1114
          }
       ]
    }
);

XML format

<searchAroundResponseV3>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distanceMeters>4474.0</distanceMeters>
      <durationSeconds>796.0</durationSeconds>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distanceMeters>10453.0</distanceMeters>
      <durationSeconds>1114.0</durationSeconds>
   </searchAroundResult>
</searchAroundResponseV3>

Possible responses

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

<searchAroundResponseV3>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distanceMeters>4474.0</distanceMeters>
      <durationSeconds>796.0</durationSeconds>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distanceMeters>10453.0</distanceMeters>
      <durationSeconds>1114.0</durationSeconds>
   </searchAroundResult>
</searchAroundResponseV3>

Case of a problem with the graph: file missing, faulty filepath, etc… (searchAroundResponse/status is OK)

<searchAroundResponseV3>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponseV3>

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

<searchAroundResponseV3>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponseV3>

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

<searchAroundResponseV3>
   <message>Location must be not null</message>
   <status>ERROR</status>
</searchAroundResponseV3>

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

<searchAroundResponseV3>
   <message>Location point must have 2 components separated with a ,</message>
   <status>ERROR</status>
</searchAroundResponseV3>

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

<searchAroundResponseV3>
   <status>OK</status>
</searchAroundResponseV3>

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

<serviceResult>
   <message>ServiceException: not enough fields in candidate 1.-1.5939</message>
   <status>ERROR</status>
</serviceResult>

V2

Parameters / properties

Input

parameter	description	optional	default
location	Coordinates of the start point (or arrival point) in SOAP, points are stored in the "x" and "y" parameters themselves in the "geographicPoint" parameter in REST, the points are separated by the , character	no
method	The shortest (distance) or fastest (time) route, or the route as the crow flies (flying)	yes	time
reverse	if true, the target is considered as an arrival	yes	false
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
exclusions	List of restriction rules to use, separated by the ";" character (Example: "Toll"; "Tunnel"; "Bridge")	yes
resources	List of resources, separated by ";" characters. Each resource takes the form "id,x,y,priority1,priority2"	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 routes…) - nearest: to the nearest road section only - unrestricted: without any restriction rules	yes	standard

Output

Search Around (searchAroundWebResultsV2)

parameter	type	min/max	description
location	double	0/1	Coordinates of the start point (or arrival point) in SOAP, points are stored in the "x" and "y" parameters themselves in the "geographicPoint" parameter in REST, the points 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	searchAroundWebResultV2 (or array in JSON / JSON-P)	0/unlimited	List of results for each candidate.

Search Around element(searchAroundWebResultV2)

parameter	type	min/max	description
id	string	0/1	Candidate identifier
distanceMeters	double	1/1	Distance in metres
durationSeconds	double	1/1	Time in seconds

SOAP

WSDL

http://<server>/<webapp>/api/ws/searchAroundService?wsdl

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:searchAroundV2>
         <!--Optional:-->
         <request>
            <location>
               <x>-1.553927</x>
               <y>47.218580</y>
            </location>
            <!--Optional:-->
            <method>time</method>
            <reverse></reverse>
            <!--Optional:-->
            <srs></srs>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <resources>
               <!--Zero or more repetitions:-->
               <resource>
                  <x>-1.593927</x>
                  <y>47.188580</y>
                  <!--Optional:-->
                  <id>1</id>
                  <!--Optional:-->
                  <priority1>1</priority1>
                  <!--Optional:-->
                  <priority2>2</priority2>
               </resource>
               <resource>
               <x>-1.556927</x>
               <y>47.219580</y>
                  <!--Optional:-->
                  <id>2</id>
                  <!--Optional:-->
                  <priority1>1</priority1>
                  <!--Optional:-->
                  <priority2>2</priority2>
               </resource>
            </resources>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <snapMethod></snapMethod>
         </request>
      </sch:searchAroundV2>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:searchAroundV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <SearchAroundResult>
            <status>OK</status>
            <location>-1.553927,47.21858</location>
            <method>time</method>
            <srs/>
            <exclusions/>
            <searchAroundResult>
               <id>2</id>
               <distanceMeters>424.0</distanceMeters>
               <durationSeconds>147.0</durationSeconds>
            </searchAroundResult>
            <searchAroundResult>
               <id>1</id>
               <distanceMeters>6682.0</distanceMeters>
               <durationSeconds>1059.0</durationSeconds>
            </searchAroundResult>
         </SearchAroundResult>
      </ns2:searchAroundV2Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/searchAround/v2.json?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1

JSON-P query

http://<server>/<webapp>/api/lbs/searchAround/v2.json?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/searchAround/v2.xml?method=time&location=-1.593927,47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1

Response

The response is always in UTF-8 format.

JSON format

{
   "message": null,
   "status": "OK",
   "location": "-1.593927,47.21858",
   "method": "time",
   "srs": null,
   "exclusions": [],
   "searchAroundResult":    [
            {
         "id": "2",
         "distanceMeters": 3376,
         "durationSeconds": 735
      },
            {
         "id": "1",
         "distanceMeters": 10453,
         "durationSeconds": 1114
      }
   ]
}

JSON-P format

myCallback(
    {
       "message": null,
       "status": "OK",
       "location": "-1.593927,47.21858",
       "method": "time",
       "srs": null,
       "exclusions": [],
       "searchAroundResult":    [
                {
             "id": "2",
             "distanceMeters": 3376,
             "durationSeconds": 735
          },
                {
             "id": "1",
             "distanceMeters": 10453,
             "durationSeconds": 1114
          }
       ]
    }
);

XML format

<searchAroundResponse>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distanceMeters>3376.0</distanceMeters>
      <durationSeconds>735.0</durationSeconds>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distanceMeters>10453.0</distanceMeters>
      <durationSeconds>1114.0</durationSeconds>
   </searchAroundResult>
</searchAroundResponse>

Possible responses

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

<searchAroundResponse>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distanceMeters>3376.0</distanceMeters>
      <durationSeconds>735.0</durationSeconds>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distanceMeters>10453.0</distanceMeters>
      <durationSeconds>1114.0</durationSeconds>
   </searchAroundResult>
</searchAroundResponse>

Case of a problem with the graph: file missing, faulty filepath, etc… (searchAroundResponse/status is OK)

<searchAroundResponse>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponse>

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

<searchAroundResponse>
   <status>OK</status>
   <location>-1.593927,47.21858</location>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponse>

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

<searchAroundResponse>
   <message>Location must be not null</message>
   <status>ERROR</status>
</searchAroundResponse>

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

<searchAroundResponse>
   <message>Location point must have 2 components separated with a ,</message>
   <status>ERROR</status>
</searchAroundResponse>

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

<searchAroundResponse>
   <status>OK</status>
</searchAroundResponse>

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

<serviceResult>
   <message>ServiceException: not enough fields in candidate 1.-1.5939</message>
   <status>ERROR</status>
</serviceResult>

V1

Parameters / properties

Input

parameter	description	optional	default
targetX	X coordinates or longitude of the target location	yes
targetY	Y coordinates or latitude of the target location	yes
searchMethod	Deprecated, replaced by method	yes	time
method	The shortest (distance) or fastest (time) route	yes	time
reverse	if true, the target is considered as a finish point	yes	false
projection	Deprecated, replaced by srs	yes
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
rejectFlags	Deprecated, replaced by exclusions	yes
exclusions	List of restriction rules to use, separated by the ";" character (Example: "Toll"; "Tunnel"; "Bridge")	yes
resources	List of resources, separated by ";" characters. Each resource takes the form "id,x,y,priority1,priority2"	yes

Output

Search Around (searchAroundWebResults)

parameter	type	min/max	description
targetX	double	1/1	X coordinates or longitude of the target location
targetY	double	1/1	Y coordinates or latitude of the target location
method	string	0/1	Specified input method
projection	string	0/1	Deprecated, replaced by srs
srs	string	0/1	Specified input projection
exclusions	string	0/unlimited	List of restriction rules specified as input
searchAroundResult	array	0/unlimited	List of responses

Search Around element(searchAroundWebResult)

parameter	type	min/max	description
id	string	0/1	Candidate identifier
distance	int	1/1	Distance in metres
time	int	1/1	Time in seconds

SOAP

WSDL

http://<server>/<webapp>/api/ws/searchAroundService?wsdl

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:searchAround>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <target>
               <x>-1.553927</x>
               <y>47.218580</y>
            </target>
            <!--Optional:-->
            <searchMethod></searchMethod>
            <!--Optional:-->
            <method>time</method>
            <reverse></reverse>
            <!--Optional:-->
            <srs></srs>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <rejectFlags>
               <!--Zero or more repetitions:-->
               <rejectFlag></rejectFlag>
            </rejectFlags>
            <!--Optional:-->
            <resources>
               <!--Zero or more repetitions:-->
               <resource>
               <x>-1.593927</x>
               <y>47.188580</y>
                  <!--Optional:-->
                  <id>1</id>
                  <!--Optional:-->
                  <priority1>1</priority1>
                  <!--Optional:-->
                  <priority2>2</priority2>
               </resource>
               <resource>
               <x>-1.556927</x>
               <y>47.219580</y>
                  <!--Optional:-->
                  <id>2</id>
                  <!--Optional:-->
                  <priority1>1</priority1>
                  <!--Optional:-->
                  <priority2>2</priority2>
               </resource>
            </resources>
         </request>
      </sch:searchAround>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:searchAroundResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <SearchAroundResult>
            <status>OK</status>
            <targetX>-1.553927</targetX>
            <targetY>47.21858</targetY>
            <method>time</method>
            <projection/>
            <srs/>
            <exclusions/>
            <searchAroundResult>
               <id>2</id>
               <distance>485</distance>
               <time>87</time>
            </searchAroundResult>
            <searchAroundResult>
               <id>1</id>
               <distance>6788</distance>
               <time>526</time>
            </searchAroundResult>
         </SearchAroundResult>
      </ns2:searchAroundResponse>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/searchAround.json?method=time&targetX=-1.593927&targetY=47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1

JSON-P query

http://<server>/<webapp>/api/lbs/searchAround.json?method=time&targetX=-1.593927&targetY=47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/searchAround.xml?method=time&targetX=-1.593927&targetY=47.218580&resources=1,-1.593927,47.188580,1,2;2,-1.556927,47.219580,1,1

Response

The response is always in UTF-8 format.

JSON format

{
   "message": null,
   "status": "OK",
   "targetX": -1.593927,
   "targetY": 47.21858,
   "method": "time",
   "projection": null,
   "srs": null,
   "exclusions": [],
   "searchAroundResult":    [
            {
         "id": "2",
         "distance": 3880,
         "time": 777
      },
            {
         "id": "1",
         "distance": 10448,
         "time": 1178
      }
   ]
}

JSON-P format

myCallback(
        {
           "message": null,
           "status": "OK",
           "targetX": -1.593927,
           "targetY": 47.21858,
           "method": "time",
           "projection": null,
           "srs": null,
           "exclusions": [],
           "searchAroundResult":    [
                                {
                         "id": "2",
                         "distance": 3880,
                         "time": 777
                  },
                                {
                         "id": "1",
                         "distance": 10448,
                         "time": 1178
                  }
           ]
        }
);

XML format

<searchAroundResponse>
   <status>OK</status>
   <targetX>-1.593927</targetX>
   <targetY>47.21858</targetY>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>3880</distance>
      <time>777</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>10448</distance>
      <time>1178</time>
   </searchAroundResult>
</searchAroundResponse>

Possible responses

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

<searchAroundResponse>
   <status>OK</status>
   <targetX>-1.593927</targetX>
   <targetY>47.21858</targetY>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>3880</distance>
      <time>777</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>10448</distance>
      <time>1178</time>
   </searchAroundResult>
</searchAroundResponse>

Case of a problem with the graph: file missing, faulty filepath, etc… (searchAroundResponse/status is OK)

<searchAroundResponse>
   <status>OK</status>
   <targetX>-1.593927</targetX>
   <targetY>47.21858</targetY>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponse>

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

<searchAroundResponse>
   <status>OK</status>
   <targetX>-51.593927</targetX>
   <targetY>47.21858</targetY>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponse>

Case of unspecified target point (searchAroundResponse/status is OK)

<searchAroundResponse>
   <status>OK</status>
   <targetX>0.0</targetX>
   <targetY>0.0</targetY>
   <method>time</method>
   <searchAroundResult>
      <id>2</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
   <searchAroundResult>
      <id>1</id>
      <distance>-1</distance>
      <time>-1</time>
   </searchAroundResult>
</searchAroundResponse>

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

<searchAroundResponse>
   <status>OK</status>
   <targetX>0.0</targetX>
   <targetY>0.0</targetY>
</searchAroundResponse>

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

<serviceResult>
   <message>ServiceException: not enough fields in candidate 2,-1.556927,</message>
   <status>ERROR</status>
</serviceResult>

FAQ

1. Is it possible to give priority to either journey time or distance?
2. Can I use aliases instead of .siti file names to call a datasource?
3. How can I use route statistics?
4. How is the classification of returned addresses structured, in relation to distance, time and priorities generally?
5. What format should the priority take and is it possible to define a classification order? (increasing/decreasing)
6. If just one address in the list has a priority of 0, is the priority taken into account for any or all of the addresses in the list?
7. How can I perform a route calculation excluding toll roads?
8. What are Speed Patterns? How can I use them?

1.	Is it possible to give priority to either journey time or distance?
	Yes, by changing the method: distance, time or flying = as the crow flies (at a speed of 30 km/h).
2.	Can I use aliases instead of .siti file names to call a datasource?
	Yes, refer to details in the FAQ of the reverse geocoding Web Service.
3.	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.
4.	How is the classification of returned addresses structured, in relation to distance, time and priorities generally?
	The classification creates a hierarchy of priority 1 in increasing order, then priority 2 in increasing order, then by time or distance or distance as the crow flies in increasing order.
5.	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 order, you should put n-priority in the attribute.
6.	If just one address in the list has a priority of 0, is the priority taken into account for any or all of the addresses in the list?
	Currently, a priority of 0 is not treated in any special way. This means you need to set all priorities to 0 if you want to ignore the criterion.
7.	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`: <sch:searchAroundV2> <!--Optional:--> <request> <location> <x>-1.553927</x> <y>47.218580</y> </location> <!--Optional:--> <method>time</method> <reverse></reverse> <!--Optional:--> <srs></srs> <!--Optional:--> <exclusions> <!--Zero or more repetitions:--> <exclusion>Toll</exclusion> </exclusions> <!--Optional:--> <resources> <!--Zero or more repetitions:--> <resource> <x>-1.593927</x> <y>47.188580</y> <!--Optional:--> <id>1</id> <!--Optional:--> <priority1>1</priority1> <!--Optional:--> <priority2>2</priority2> </resource> </resources> <!--Optional:--> <startDateTime></startDateTime> </request> </sch:searchAroundV2>
8.	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

Web Services documentation of Geoconcept Web - Web Services

Basic principles

Availability

Version change

V4

Parameters / properties

SOAP

REST

Possible responses

V3

Parameters / properties

SOAP

REST

Possible responses

V2

Parameters / properties

SOAP

REST

Possible responses

V1

Parameters / properties

SOAP

REST

Possible responses

FAQ