Calculating Isochrones/Isodistances

Basic principles

This web service calculates an isochrone/isodistance from a point and returns the geometry of the zone calculated. It bases its calculations on the configured graph, the name of which has been specified in the administration interface of Geoconcept Web.

Availability

This web service is available at all times with Geoconcept Web and one road network.

Version change

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

Changes in relation to V4

Addition of "timeOut" and "computeOptions" parameters.

Changes in relation to V3

Addition of "avoidArea" and "configName" parameters.

Changes in relation to V2

Addition of "startDateTime" and "snapMethod" parameters

V4

Parameters / properties

Input

parameter	description	optional	default
id	Isochrone identifier	yes
location	Start (or arrival point, if the `reverse` parameter is set to True). The coordinates are separated by , characters.	no
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes	epsg:4326
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 under vehicle profiles) This parameter is omitted if the configName parameter is used.	yes
exclusions	List of restriction rules to use, separated by the ; character (Example: Toll, Tunnel, Bridge)	yes
method	"time" for isochrone or "distance" for isodistance	no	time
time	Maximum access time, in seconds	yes
distance	Maximum access distance, in metres	yes
reverse	if true, the `location` is considered as an arrival point	yes	false
smoothing	Smoothing	yes	false
holes	Display holes in the result zone (the geometry returned is more voluminous when this parameter is set to true)	yes	false
startDateTime	Departure 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 Januray 2014, at 9.00am in Paris. Caution: the + character may be misinterpreted by browsers, and so in this case should be replaced by %2B.	yes
snapMethod	Method for snapping to the graph - standard: at the nearest connectable road section - extended: via restricted road sections (pedestrian routes….) - nearest: only to the nearest road section - unrestricted: without any restriction rules	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)))` NOTE: WKT geometries must be closed.	yes
configName	Configuration name to use (defined in Geoconcept Web - Administration / Tools / Road networks) This replaces the use of graphName, profileId and profileName	yes
timeOut	Time out for the calculation (in milliseconds)	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

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

Output

Itinerary (isochroneResult)

parameter	type	min/max	description
id	string	0/1	Isochrone identifier
location	string	0/1	Start (or Finish if the `reverse` is set to true).
srs	string	0/1	projection
time	string	0/1	Maximum access time, in seconds
distance	string	0/1	Maximum access distance, in metres
wktGeometry	string	0/1	Geometry of the isochrone, in wkt format

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:isochroneV4>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <id>1</id>
            <location>
               <x>-1.557189</x>
               <y>47.217122</y>
            </location>
            <!--Optional:-->
            <srs></srs>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <method>distance</method>
            <!--Optional:-->
            <time></time>
            <!--Optional:-->
            <distance>5000</distance>
            <!--Optional:-->
            <reverse></reverse>
            <!--Optional:-->
            <smoothing></smoothing>
            <!--Optional:-->
            <holes></holes>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <snapMethod></snapMethod>
            <!--Optional:-->
            <avoidArea></avoidArea>
            <!--Optional:-->
            <configName></configName>
            <!--Optional:-->
            <computeOptions></computeOptions>
            <!--Optional:-->
            <timeOut></timeOut>
            </request>
      </sch:isochroneV4>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:isochroneV4Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <IsochroneResult>
            <status>OK</status>
            <id>1</id>
            <location>-1.557189,47.217122</location>
            <srs />
            <distance>5000</distance>
            <wktGeometry>POLYGON ((-1.544603 47.179044, -1.545261 47.179044, [...], -1.544603 47.179044))</wktGeometry>
         </IsochroneResult>
      </ns2:isochroneV4Response>
   </soap:Body>
</soap:Envelope>

REST (POST)

Query

Query

http://<server>/<webapp>/api/lbs/isochrone/v4.xml

Data (XML)

<?xml version="1.0" encoding="UTF-8"?>
<isochroneRequestV4>
  <id></id>
  <location>
    <x>-1.557189</x>
    <y>47.217122</y>
  </location>
  <srs></srs>
  <graphName></graphName>
  <profileId></profileId>
  <profileName></profileName>
  <exclusions>
    <exclusion></exclusion>
    <exclusion></exclusion>
    <!--...more "exclusion" elements...-->
  </exclusions>
  <method></method>
  <time>50</time>
  <distance></distance>
  <reverse></reverse>
  <smoothing></smoothing>
  <holes></holes>
  <startDateTime></startDateTime>
  <snapMethod></snapMethod>
  <avoidArea></avoidArea>
  <configName></configName>
</isochroneRequestV4>

Response

The response is always coded in UTF-8.

XML format

<isochroneResultV4>
   <status>OK</status>
   <id>1</id>
   <location>-1.557189,47.217122</location>
   <srs/>
   <time>50</time>
   <wktGeometry>POLYGON ((-1.556864 47.216487, -1.556864 47.216948, [...]))</wktGeometry>
</isochroneResultV4>

REST (GET)

Query

JSON query

http://<server>/<webapp>/api/lbs/isochrone/v4.json?location=-1.557189,47.217122&method=distance&distance=5000

JSON-P query

http://<server>/<webapp>/api/lbs/isochrone/v4.json?location=-1.557189,47.217122&method=distance&distance=5000&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/isochrone/v4.xml?location=-1.557189,47.217122&method=distance&distance=2000&holes=true

Response

The response is always coded in UTF-8.

JSON format

{
   "message": null,
   "status": "OK",
   "id": null,
   "location": "-1.557189,47.217122",
   "srs": "epsg:4326",
   "time": null,
   "distance": "5000",
   "wktGeometry": "POLYGON ((-1.545312 47.178178, -1.545312 47.180418, ...))"
}

JSON-P format

myCallback(
    {
       "message": null,
       "status": "OK",
       "id": null,
       "location": "-1.557189,47.217122",
       "srs": "EPSG:4326",
       "time": null,
       "distance": "5000",
       "wktGeometry": "POLYGON ((-1.545312 47.178178, -1.545312 47.180418, ...))"
    }
);

XML format

<isochroneResultV4>
   <status>OK</status>
   <location>-1.557189,47.217122</location>
   <srs>EPSG:4326</srs>
   <distance>2000</distance>
   <wktGeometry>POLYGON ((-1.546926 47.202309, -1.546926 47.202752, ...))</wktGeometry>
</isochroneResultV4>

Possible responses

Case of an isochrone/isodistance that has been found (isochroneResultV2/status is OK)

<isochroneResultV4>
   <status>OK</status>
   <location>-1.557189,47.217122</location>
   <srs>EPSG:4326</srs>
   <distance>2000</distance>
   <wktGeometry>POLYGON ((-1.546926 47.202309, -1.546926 47.202752, ...))</wktGeometry>
</isochroneResultV4>

Case whereby method = distance and distance is not supplied (isochroneResult/status is ERROR)

<isochroneResultV4>
    <message>distance parameter must not be null or 0 !</message>
    <status>ERROR</status>
</isochroneResultV4>

Case whereby method + time are not supplied (isochroneResult/status is ERROR)

<isochroneResultV4>
    <message>time parameter must not be null or 0 !</message>
    <status>ERROR</status>
</isochroneResultV4>

Case whereby the location tag is missing (isochroneResult/status is ERROR)

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

Case whereby the start point is supplied with errors (isochroneResult/status is ERROR)

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

Case of a snap-to-graph error (serviceResult/status is ERROR)

<serviceResult>
        <message>
                ServiceException: Error in isochrone computation Error in smartrouting Failed to execute calculateConcentricReachableAreas com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect isochrone orign { 52.324230, 48.803256, 0.000000 } failed to connect isochrone orign { 52.324230, 48.803256, 0.000000 }
        </message>
        <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
   <message>ServiceException: Error in isochrone computation
        Error in smartrouting
        datasource is null
    </message>
   <status>ERROR</status>
</serviceResult>

V3

Parameters / properties

Input

parameter	description	optional	default
id	Isochrone identifier	yes
location	Start (or arrival point, if the `reverse` parameter is set to True). The coordinates are separated by , characters.	no
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes	epsg:4326
graphName	Name of the graph to use This parameter is omitted if the configName parameter is used.	yes
profileId	Vehicle identifier (saved under vehicle profiles) This parameter is omitted if the configName parameter is used.	yes
profileName	Vehicle profile (saved under vehicle profiles) This parameter is omitted if the configName parameter is used.	yes
exclusions	List of restriction rules to use, separated by the , or ; character (Example: "Toll", "Tunnel", "Bridge")	yes
method	"time" for isochrone or "distance" for isodistance	no	time
time	Maximum access time, in seconds	yes
distance	Maximum access distance, in metres	yes
reverse	if true, the `location` is considered as an arrival point	yes	false
smoothing	Smoothing	yes	false
holes	Display holes in the result zone (the geometry returned is more voluminous when this parameter is set to true)	yes	false
startDateTime	Departure 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 Januray 2014, at 9.00am in Paris. Caution: the + character may be misinterpreted by browsers, and so in this case should be replaced by %2B.	yes
snapMethod	Method for snapping to the graph - standard: at the nearest connectable road section - extended: via restricted road sections (pedestrian routes….) - nearest: only to the nearest road section - unrestricted: without any restriction rules	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)))` NOTE: WKT geometries must be closed.	yes
configName	Configuration name to use (defined in Geoconcept Web - Administration / Tools / Road networks) This replaces the use of graphName, profileId and profileName	yes

Output

Itinerary (isochroneResult)

parameter	type	min/max	description
id	string	0/1	Isochrone identifier
location	string	0/1	Start (or Finish if the `reverse` is set to true).
srs	string	0/1	projection
time	string	0/1	Maximum access time, in seconds
distance	string	0/1	Maximum access distance, in metres
wktGeometry	string	0/1	Geometry of the isochrone, in wkt format

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:isochroneV3>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <id>1</id>
            <location>
               <x>-1.557189</x>
               <y>47.217122</y>
            </location>
            <!--Optional:-->
            <srs></srs>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <method>distance</method>
            <!--Optional:-->
            <time></time>
            <!--Optional:-->
            <distance>5000</distance>
            <!--Optional:-->
            <reverse></reverse>
            <!--Optional:-->
            <smoothing></smoothing>
            <!--Optional:-->
            <holes></holes>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <snapMethod></snapMethod>
            <!--Optional:-->
            <avoidArea></avoidArea>
            <!--Optional:-->
            <configName></configName>
         </request>
      </sch:isochroneV3>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:isochroneV3Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <IsochroneResult>
            <status>OK</status>
            <id>1</id>
            <location>-1.557189,47.217122</location>
            <srs/>
            <distance>5000</distance>
            <wktGeometry>POLYGON ((-1.544603 47.179044, -1.545261 47.179044, [...]))</wktGeometry>
         </IsochroneResult>
      </ns2:isochroneV3Response>
   </soap:Body>
</soap:Envelope>

REST (POST)

Query

Query

http://<server>/<webapp>/api/lbs/isochrone/v3.xml

Data (XML)

<?xml version="1.0" encoding="UTF-8"?>
<isochroneRequestV3>
  <id></id>
  <location>
    <x>-1.557189</x>
    <y>47.217122</y>
  </location>
  <srs></srs>
  <graphName></graphName>
  <profileId></profileId>
  <profileName></profileName>
  <exclusions>
    <exclusion></exclusion>
    <exclusion></exclusion>
    <!--...more "exclusion" elements...-->
  </exclusions>
  <method></method>
  <time>50</time>
  <distance></distance>
  <reverse></reverse>
  <smoothing></smoothing>
  <holes></holes>
  <startDateTime></startDateTime>
  <snapMethod></snapMethod>
  <avoidArea></avoidArea>
  <configName></configName>
</isochroneRequestV3>

Response

The response is always coded in UTF-8.

XML format

<isochroneResultV3>
   <status>OK</status>
   <id>1</id>
   <location>-1.557189,47.217122</location>
   <srs/>
   <time>50</time>
   <wktGeometry>POLYGON ((-1.556864 47.216487, -1.556864 47.216948, [...]))</wktGeometry>
</isochroneResultV3>

REST (GET)

Query

JSON query

http://<server>/<webapp>/api/lbs/isochrone/v3.json?location=-1.557189,47.217122&method=distance&distance=5000

JSON-P query

http://<server>/<webapp>/api/lbs/isochrone/v3.json?location=-1.557189,47.217122&method=distance&distance=5000&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/isochrone/v3.xml?location=-1.557189,47.217122&method=distance&distance=2000&holes=true

Response

The response is always coded in UTF-8.

JSON format

{
   "message": null,
   "status": "OK",
   "id": null,
   "location": "-1.557189,47.217122",
   "srs": "EPSG:4326",
   "time": null,
   "distance": "5000",
   "wktGeometry": "POLYGON ((-1.545312 47.178178, -1.545312 47.180418, ...))"
}

JSON-P format

myCallback(
    {
       "message": null,
       "status": "OK",
       "id": null,
       "location": "-1.557189,47.217122",
       "srs": "EPSG:4326",
       "time": null,
       "distance": "5000",
       "wktGeometry": "POLYGON ((-1.545312 47.178178, -1.545312 47.180418, ...))"
    }
);

XML format

<isochroneResultV3>
   <status>OK</status>
   <location>-1.557189,47.217122</location>
   <srs>EPSG:4326</srs>
   <distance>2000</distance>
   <wktGeometry>POLYGON ((-1.546926 47.202309, -1.546926 47.202752, ...))</wktGeometry>
</isochroneResultV3>

Possible responses

Case of an isochrone/isodistance that has been found (isochroneResultV2/status is OK)

<isochroneResultV3>
   <status>OK</status>
   <location>-1.557189,47.217122</location>
   <srs>EPSG:4326</srs>
   <distance>2000</distance>
   <wktGeometry>POLYGON ((-1.546926 47.202309, -1.546926 47.202752, ...))</wktGeometry>
</isochroneResultV3>

Case whereby method = distance and distance is not supplied (isochroneResult/status is ERROR)

<isochroneResultV3>
    <message>distance parameter must not be null or 0 !</message>
    <status>ERROR</status>
</isochroneResultV3>

Case whereby method + time are not supplied (isochroneResult/status is ERROR)

<isochroneResultV3>
    <message>time parameter must not be null or 0 !</message>
    <status>ERROR</status>
</isochroneResultV3>

Case whereby the location tag is missing (isochroneResult/status is ERROR)

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

Case whereby the start point is supplied with errors (isochroneResult/status is ERROR)

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

Case of a snap-to-graph error (serviceResult/status is ERROR)

<serviceResult>
        <message>
                ServiceException: Error in isochrone computation Error in smartrouting Failed to execute calculateConcentricReachableAreas com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect isochrone orign { 52.324230, 48.803256, 0.000000 } failed to connect isochrone orign { 52.324230, 48.803256, 0.000000 }
        </message>
        <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
   <message>ServiceException: Error in isochrone computation
        Error in smartrouting
        datasource is null
    </message>
   <status>ERROR</status>
</serviceResult>

V2

Parameters / properties

Input

parameter	description	optional	default
id	Isochrone identifier	yes
location	Start (or arrival point, if the `reverse` parameter is set to True). The coordinates are separated by , characters.	no
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes	epsg:4326
graphName	Name of the graph to use	yes
profileId	Vehicle identifier (saved under vehicle profiles) to use	yes
profileName	Vehicle profile (saved under vehicle profiles) to use	yes
exclusions	List of restriction rules to use, separated by the , or ; character (Example: "Toll", "Tunnel", "Bridge")	yes
method	"time" for isochrone or "distance" for isodistance	no	time
time	Maximum access time, in seconds	yes
distance	Maximum access distance, in metres	yes
reverse	if true, the `location` is considered as an arrival point	yes	false
smoothing	Smoothing	yes	false
holes	Display holes in the result zone (the geometry returned is more voluminous when this parameter is set to true)	yes	false
startDateTime	Departure 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 Januray 2014, at 9.00am in Paris	yes
snapMethod	Method for snapping to the graph - standard: at the nearest connectable road section - extended: via restricted road sections (pedestrian routes….) - nearest: only to the nearest road section - unrestricted: without any restriction rules	yes	standard

Output

Itinerary (isochroneResult)

parameter	type	min/max	description
id	string	0/1	Isochrone identifier
location	string	0/1	Start (or Finish if the `reverse` is set to true).
srs	string	0/1	projection
time	string	0/1	Maximum access time, in seconds
distance	string	0/1	Maximum access distance, in metres
wktGeometry	string	0/1	Geometry of the isochrone, in wkt format

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:isochroneV2>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <id>1</id>
            <location>
               <x>-1.557189</x>
               <y>47.217122</y>
            </location>
            <!--Optional:-->
            <srs></srs>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <method>distance</method>
            <!--Optional:-->
            <time></time>
            <!--Optional:-->
            <distance>5000</distance>
            <!--Optional:-->
            <reverse></reverse>
            <!--Optional:-->
            <smoothing></smoothing>
            <!--Optional:-->
            <holes></holes>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <snapMethod></snapMethod>
         </request>
      </sch:isochroneV2>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:isochroneV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <IsochroneResult>
            <status>OK</status>
            <id/>
            <location>-1.557189,47.217122</location>
            <srs/>
            <distance>5000</distance>
            <wktGeometry>POLYGON ((-1.544603 47.179044, -1.545261 47.179044, [...]))</wktGeometry>
         </IsochroneResult>
      </ns2:isochroneV2Response>
   </soap:Body>
</soap:Envelope>

REST (POST)

Query

Query

http://<server>/<webapp>/api/lbs/isochrone/v2.xml

Data (XML)

<?xml version="1.0" encoding="UTF-8"?>
<isochroneRequestV2>
  <id></id>
  <location>
    <x>-1.557189</x>
    <y>47.217122</y>
  </location>
  <srs></srs>
  <graphName></graphName>
  <profileId></profileId>
  <profileName></profileName>
  <exclusions>
    <exclusion></exclusion>
    <exclusion></exclusion>
    <!--...more "exclusion" elements...-->
  </exclusions>
  <method></method>
  <time>50</time>
  <distance></distance>
  <reverse></reverse>
  <smoothing></smoothing>
  <holes></holes>
  <startDateTime></startDateTime>
  <snapMethod></snapMethod>
</isochroneRequestV2>

Response

The response is always coded in UTF-8.

XML format

<isochroneResultV2>
   <status>OK</status>
   <id>1</id>
   <location>-1.557189,47.217122</location>
   <srs/>
   <time>50</time>
   <wktGeometry>POLYGON ((-1.556864 47.216487, -1.556864 47.216948, [...]))</wktGeometry>
</isochroneResultV2>

REST (GET)

Query

JSON query

http://<server>/<webapp>/api/lbs/isochrone/v2.json?location=-1.557189,47.217122&method=distance&distance=5000

JSON-P query

http://<server>/<webapp>/api/lbs/isochrone/v2.json?location=-1.557189,47.217122&method=distance&distance=5000&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/isochrone/v2.xml?location=-1.557189,47.217122&method=distance&distance=2000&holes=true

Response

The response is always coded in UTF-8.

JSON format

{
   "message": null,
   "status": "OK",
   "id": null,
   "location": "-1.557189,47.217122",
   "srs": "EPSG:4326",
   "time": null,
   "distance": "5000",
   "wktGeometry": "POLYGON ((-1.545312 47.178178, -1.545312 47.180418, ...))"
}

JSON-P format

myCallback(
    {
       "message": null,
       "status": "OK",
       "id": null,
       "location": "-1.557189,47.217122",
       "srs": "EPSG:4326",
       "time": null,
       "distance": "5000",
       "wktGeometry": "POLYGON ((-1.545312 47.178178, -1.545312 47.180418, ...))"
    }
);

XML format

<isochroneResultV2>
   <status>OK</status>
   <location>-1.557189,47.217122</location>
   <srs>EPSG:4326</srs>
   <distance>2000</distance>
   <wktGeometry>POLYGON ((-1.546926 47.202309, -1.546926 47.202752, ...))</wktGeometry>
</isochroneResultV2>

Possible responses

Case of an isochrone/isodistance that has been found (isochroneResultV2/status is OK)

<isochroneResultV2>
   <status>OK</status>
   <location>-1.557189,47.217122</location>
   <srs>EPSG:4326</srs>
   <distance>2000</distance>
   <wktGeometry>POLYGON ((-1.546926 47.202309, -1.546926 47.202752, ...))</wktGeometry>
</isochroneResultV2>

Case whereby method = distance and distance is not supplied (isochroneResult/status is ERROR)

<isochroneResultV2>
    <message>distance parameter must not be null or 0 !</message>
    <status>ERROR</status>
</isochroneResultV2>

Case whereby method + time are not supplied (isochroneResult/status is ERROR)

<isochroneResultV2>
    <message>time parameter must not be null or 0 !</message>
    <status>ERROR</status>
</isochroneResultV2>

Case whereby the location tag is missing (isochroneResult/status is ERROR)

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

Case whereby the start point is supplied with errors (isochroneResult/status is ERROR)

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

Case of a snap-to-graph error (serviceResult/status is ERROR)

<serviceResult>
        <message>
                ServiceException: Error in isochrone computation Error in smartrouting Failed to execute calculateConcentricReachableAreas com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect isochrone orign { 52.324230, 48.803256, 0.000000 } failed to connect isochrone orign { 52.324230, 48.803256, 0.000000 }
        </message>
        <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
   <message>ServiceException: Error in isochrone computation
        Error in smartrouting
        datasource is null
    </message>
   <status>ERROR</status>
</serviceResult>

V1

Parameters / properties

Input

parameter	description	optional	default
id	Isochrone identifier	yes
location	Start (or arrival point, if the `reverse` parameter is set to True). The coordinates are separated by , characters.	no
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes	epsg:4326
graphName	Name of the graph to use	yes
profileId	Vehicle identifier (saved under vehicle profiles) to use	yes
profileName	Vehicle profile (saved under vehicle profiles) to use	yes
exclusions	List of restriction rules to use, separated by the , or ; character (Example: "Toll", "Tunnel", "Bridge")	yes
method	"time" for isochrone or "distance" for isodistance	no	time
time	Maximum access time, in seconds	yes
distance	Maximum access distance, in metres	yes
reverse	if true, the `location` is considered as an arrival point	yes	false
smoothing	Smoothing	yes	false
holes	Display holes in the result zone (the geometry returned is more voluminous when this parameter is set to true)	yes	false

Output

Itinerary (isochroneResult)

parameter	type	min/max	description
id	string	0/1	Isochrone identifier
location	string	0/1	Start (or Finish if the `reverse` is set to true).
srs	string	0/1	projection
time	string	0/1	Maximum access time, in seconds
distance	string	0/1	Maximum access distance, in metres
wktGeometry	string	0/1	Geometry of the isochrone, in wkt format

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:isochrone>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <id/>
            <location>
               <x>-1.557189</x>
               <y>47.217122</y>
            </location>
            <!--Optional:-->
            <srs/>
            <!--Optional:-->
            <graphName/>
            <!--Optional:-->
            <profileId/>
            <!--Optional:-->
            <profileName/>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion/>
            </exclusions>
            <!--Optional:-->
            <method>distance</method>
            <!--Optional:-->
            <distance>5000</distance>
            <!--Optional:-->
            <reverse/>
            <!--Optional:-->
            <smoothing/>
            <!--Optional:-->
            <holes/>
         </request>
      </sch:isochrone>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:isochroneResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <IsochroneResult>
            <status>OK</status>
            <id/>
            <location>-1.557189,47.217122</location>
            <srs/>
            <distance>5000</distance>
            <wktGeometry>POLYGON ((-1.544603 47.179044, -1.545261 47.179044, [...]))</wktGeometry>
         </IsochroneResult>
      </ns2:isochroneResponse>
   </soap:Body>
</soap:Envelope>

REST (POST)

Query

Query

http://<server>/<webapp>/api/lbs/isochrone.xml

Data (XML)

<?xml version="1.0" encoding="UTF-8"?>
<isochroneRequest>
  <id>1</id>
  <location>
    <x>-1.557189</x>
    <y>47.217122</y>
  </location>
  <srs></srs>
  <graphName></graphName>
  <profileId></profileId>
  <profileName></profileName>
  <exclusions>
    <exclusion></exclusion>
    <exclusion></exclusion>
    <!--...more "exclusion" elements...-->
  </exclusions>
  <method></method>
  <time>50</time>
  <distance></distance>
  <reverse></reverse>
  <smoothing></smoothing>
  <holes></holes>
</isochroneRequest>

Response

The response is always coded in UTF-8.

XML format

<isochroneResult>
   <status>OK</status>
   <id>1</id>
   <location>-1.557189,47.217122</location>
   <srs/>
   <time>50</time>
   <wktGeometry>POLYGON ((-1.556864 47.216487, -1.556864 47.216948, ...))</wktGeometry>
</isochroneResult>

REST (GET)

Query

JSON query

http://<server>/<webapp>/api/lbs/isochrone.json?location=-1.557189,47.217122&method=distance&distance=5000

JSON-P query

http://<server>/<webapp>/api/lbs/isochrone.json?location=-1.557189,47.217122&method=distance&distance=5000&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/isochrone.xml??location=-1.557189,47.217122&method=distance&distance=2000&holes=true

Response

The response is always coded in UTF-8.

JSON format

{
   "message": null,
   "status": "OK",
   "id": null,
   "location": "-1.557189,47.217122",
   "srs": "EPSG:4326",
   "time": null,
   "distance": "5000",
   "wktGeometry": "POLYGON ((-1.545312 47.178178, -1.545312 47.180418, ...))"
}

JSON-P format

myCallback(
    {
       "message": null,
       "status": "OK",
       "id": null,
       "location": "-1.557189,47.217122",
       "srs": "EPSG:4326",
       "time": null,
       "distance": "5000",
       "wktGeometry": "POLYGON ((-1.545312 47.178178, -1.545312 47.180418, ...))"
    }
);

XML format

<isochroneResult>
   <status>OK</status>
   <location>-1.557189,47.217122</location>
   <srs>EPSG:4326</srs>
   <distance>2000</distance>
   <wktGeometry>POLYGON ((-1.546926 47.202309, -1.546926 47.202752, ...))</wktGeometry>
</isochroneResult>

Possible responses

Case of an isochrone/isodistance that has been found (isochroneResult/status is OK)

<isochroneResult>
        <status>OK</status>
        <location>2.32423,48.803256</location>
        <srs>epsg:4326</srs>
        <distance>2000,000000</distance>
        <wktGeometry>
                POLYGON ((2.317525987661223 48.786657549807174, 2.317525987661223 48.787103131779986, ...))
        </wktGeometry>
</isochroneResult>

Case where the start point is empty (isochroneResult/status is ERROR)

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

Case whereby the start point is supplied with errors (isochroneResult/status is ERROR)

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

Case of a typing error

<isochroneResult>
        <message>NumberFormatException: For input string: "AAA"</message>
        <status>ERROR</status>
</isochroneResult>

Case of a snap-to-graph error (isochroneResult/status is ERROR)

<serviceResult>
        <message>
                ServiceException: Error in isochrone computation Error in smartrouting Failed to execute calculateConcentricReachableAreas com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect isochrone orign { 52.324230, 48.803256, 0.000000 } failed to connect isochrone orign { 52.324230, 48.803256, 0.000000 }
        </message>
        <status>ERROR</status>
</serviceResult>

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

<serviceResult>
   <message>ServiceException: Error in isochrone computation
        Error in smartrouting
        datasource is null
    </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 do you perform an isochrone/isodistance calculation without any tolls?
5. 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 to "time" `method` for isochrone, or "distance" for isodistance
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 do you perform an isochrone/isodistance calculation without any tolls?
	If the Toll constraint has been included in the graph, place an exclusion in `exclusions`: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas"> <soapenv:Header/> <soapenv:Body> <sch:isochroneV2> <!--Optional:--> <request> <!--Optional:--> <id>1</id> <location> <x>-1.557189</x> <y>47.217122</y> </location> <!--Optional:--> <srs></srs> <!--Optional:--> <graphName></graphName> <!--Optional:--> <profileId></profileId> <!--Optional:--> <profileName></profileName> <!--Optional:--> <exclusions> <!--Zero or more repetitions:--> <exclusions>Toll</exclusions> </exclusions> <!--Optional:--> <method>distance</method> <!--Optional:--> <time></time> <!--Optional:--> <distance>5000</distance> <!--Optional:--> <reverse></reverse> <!--Optional:--> <smoothing></smoothing> <!--Optional:--> <holes></holes> <!--Optional:--> <startDateTime></startDateTime> <!--Optional:--> <snapMethod></snapMethod> </request> </sch:isochroneV2> </soapenv:Body> </soapenv:Envelope>
5.	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 (POST)

REST (GET)

Possible responses

V3

Parameters / properties

SOAP

REST (POST)

REST (GET)

Possible responses

V2

Parameters / properties

SOAP

REST (POST)

REST (GET)

Possible responses

V1

Parameters / properties

SOAP

REST (POST)

REST (GET)

Possible responses

FAQ