Route Web Service 2.0
Table of contents
- Info
- Technical
- Overview of provided functions
Info
Remark: This is a RouteYou+ service. Please contact sales[at-r.] if you want to make use of this service and you don't have yet an agreement with RouteYou.
- Service name: Route
- Version: 2.0
Technical
The web service is accessible using:
XML-RPC: Info on how to use- JSONP: Info on how to use
- JSON-RPC: Info on how to use
Overview of provided functions
get
Get information of one or multiple routes by id
Input
- id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
- language (String|Null): language in iso2
- options (Struct|Null):
- possibility to strip HTML-tags: array('stripTags' => true)
- possibility to return route media: array('media' => true)
- possibility to return route geometry: array('geometry' => true)
- possibility to return route pois: array('pois' => true)
- possibility to return route elevation: array('elevation' => true)
- possibility to return linked group ids: array('groupIds' => true)
- possibility to return created date, updated date and edited date from a route: array('dates' => true)
- possibilty to return the instructions in the new format: array('newInstructionFormat' => true)
- possibility to return route statistics: array('statistics' => true)
Output
- route(s) (Object|Struct(Object)): if the input is just one id, an object is returned. If the input is an array, an array with the ids as key and the objects as value is returned.
getGeometry
Get geometry of one or multiple routes by id
Input
- id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
- language (String|Null): language in iso2
- options (Struct|Null):
- possibility to strip HTML-tags: array('stripTags' => true)
- possibility to return route media: array('media' => true)
- possibility to return created date, updated date and edited date from a route: array('dates' => true)
Output
- route(s) (Object|Struct(Object)): if the input is just one id, an object is returned. If the input is an array, an array with the ids as key and the objects as value is returned.
getFull
Get all information of one or multiple routes by id. Includes geometry and height-information.
Input
- id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
- language (String|Null): language in iso2
- options (Struct|Null):
- possibility to strip HTML-tags: array('stripTags' => true)
- possibility to return route media: array('media' => true)
- possibilty to return the instructions in the new format: array('newInstructionFormat' => true)
- possibility to return route statistics: array('statistics' => true)
Output
- route(s) (Object|Struct(Object)): if the input is just one id, an object is returned. If the input is an array, an array with the ids as key and the objects as value is returned.
Example output:
array (
'id' => 58826,
'length' => 6236, //length of the route in m
'begin' =>
array (
'wkt' => 'POINT(5.29525 51.69049)',
),
'end' =>
array (
'wkt' => 'POINT(5.30241 51.69471)',
),
'centroid' =>
array (
'wkt' => 'POINT(5.30302990997914 51.688292690025)',
),
'bounds' =>
array (
'wkt' => 'BOX(5.29493 51.68355,5.31264 51.69471)',
),
'owner' => //information of route owner
array (
'id' => 3,
'nick' => 'Brackie',
'type' =>
array (
'id' => 1,
),
'imageRevision' => 1,
'flag' => 'nl',
'languages' =>
array (
0 => 'nl',
),
'name' =>
array (
'nl' => 'Brackie',
),
'privileges' =>
array (
),
'configuration' => NULL,
),
'permission' => //permissions of the route
array (
'id' => 0,
'read' => 'public',
'write' => 'private',
'writable' => false,
),
'type' =>
array (
'id' => 2,
'tree' => //contains the routeTypes higher in the hierarchy
array (
0 =>
array (
'id' => 0,
'name' =>
array (
'nl' => 'Alle routes',
),
),
),
'name' =>
array (
'nl' => 'Wandelroute',
),
),
'flag' => 'nl',//iso2 country code
'score' => 1,
'payable' => false,
'duration' => NULL,
'downloadable' => false,
'ascent' =>
array (
'total' => 12,
'net' => -4, //height difference between start and end
'totalRelative' => 0.20000000000000001, //difficulty level: 80% of routes of that type are more difficult
),
'descent' =>
array (
'total' => 16,
'totalRelative' => 0.29999999999999999, //difficulty level: 70% of routes of that type are more difficult
),
'ascendingRate' =>
array (
'max' => 0.0050350000000000004,
'avg' => 0.0018959999999999999,
'maxRelative' => 0.10000000000000001, //difficulty level: 90% of routes of that type are more difficult
'avgRelative' => 0.10000000000000001, //difficulty level: 90% of routes of that type are more difficult
),
'difficultyAuthor' => NULL,
'speed' =>
array (
'max' => NULL,
'avg' => NULL,
),
'bpm' =>
array (
'min' => NULL,
'max' => NULL,
'avg' => NULL,
),
'calories' => NULL,
'cadence' =>
array (
'max' => NULL,
'avg' => NULL,
),
'planner' =>
array (
'id' => 1,
),
'parent' => NULL,
'configuration' => NULL,
'editedDate' => '2013-02-07 12:59:40.452038+00', //last edited
'languages' => //languages of the route
array (
0 => 'nl',
),
'otnId' => //internal id of RouteYou (deprecated)
array (
'nl' => '12fc8f182294270df2ae1ff8511400bd',
),
'name' =>
array (
'nl' => 'Den Bosch stadswandeling.',
),
'subName' =>
array (
'nl' => '',
),
'trackName' => //name of the route used in gpx-files (when empty field name is used)
array (
'nl' => '',
),
'description' =>
array (
'nl' => 'Stadwandeling door Den Bosch: een eerste kennismaking met deze prachtige stad die de belangrijkste punten aandoet.',
),
'viewCount' => '78110',
'viewCountThisMonth' => '361',
'downloadCount' => '2446',
'geometry' => //line of the route in Google format
array (
'google' => 'qxnzHifi_@B?DM?e@DmA?QFo@NwJM]?kDBuBvA@X?PIv@O|@Eh@Cb@C\\@nBh@FB@c@HsCKCWCm@ISADsBIWk@\\EkBaAReBp@OeASaBNOrAe@dAKZCn@@OoAMeA_@gB[eAS]ACYAJuAFy@Bu@DcApANl@HJPZFZiA?UHmB@K@ULuCiBGe@Is@MT_EBi@Du@p@FHI`AiAjARHeBDq@eDe@]GB_AD}A?QBS?Y@SBeApAKZAnAKHe@RuAT?~FF?O?P|BABnKoDf@I@I@gANwDf@OvCA|C~AIv@E`@B_@nF]`IR~BOVr@dC`A|E`@n@Vf@ZrATrBWJcAdAdAxCJ~BzMbX@DFNAz@Mt@Yj@s@Ts@}@a@k@i@y@yAuBQWy@sAeBmD[q@Y_AYs@Yw@uEvEw@s@M^c@pBCP}DoBeB_@gCa@M]?kDcEe@}AKyBUGaAsAEs@OWSmE{DX_BKs@b@qAj@cBxAaFOUk@w@iA~Cm@lAc@r@s@t@',
),
'elevation' => //height profile in Google format. (x is relative distanceà
array (
'google' => '_c`|@??eA?{D?eL?gZ?gE?eP?saC?_L_ibEsz@_ibE}g@?ap@?oM?sI~|hQw^?sa@?mV?cS?wO?c_A?uC?oK_seKqr@~hbE{E?mL?{X?eJ_seKig@?aI~reKsY_seKqd@~hbEmd@?oz@?yX_ibEwb@?oI~hbEuo@?gf@_ibEuN?wY_ibEc\\?oX~hbEeg@?{[?gN?w@?oM~hbEq]?sS?yQ?yV_ibEam@?{X?cH?{N?_]?sF~hbEqe@?iC?uF?qs@?ez@?mT?m\\_ibEsbA~hbEwM?_R?_[?qE?{k@?}i@~hbEyb@?sP?o|A?}O?iU?w_@?gE~hbEgF?_H?aF?kW?{l@?sN_ibEyk@?iM?y^?gK?ymC?oD?gE~|hQgeA?uiC_seKcbB?qD?sD?qg@_ibEofB_ibEmt@_ibEwu@?ut@~reKg^?aR?atA_ibEyoB?wl@?eK?wu@?itA?eX~hbEiR?_`@?ai@?_M~hbE_l@_seKcaA?{k@~flWy_K?kA?cF?yS~hbEiS_seK_T?_]?cc@?iW_ibE{]?u_A?aL_ibEoj@?}qA~hbEiV?oY?cV_ibEeW?{kC_ibEac@~hbEqL?ik@?sE?yoB?_y@?ukA?_L_ibEsz@~hbEamB?ss@~reKmcA~hbEiV?{m@?o\\?aN~reKacC_ibEic@?eR?ya@?mi@_seKa|A~hbEuJ?i^~hbEcdA?gd@?}Y~hbEoa@',
),
'instructions' =>
array (
),
'segments' =>
array (
0 =>
array (
0 => 5.2952500000000002,
1 => 51.690489999999997,
2 => 32,
),
1 =>
...
),
'pois' => //pois of the route
array (
0 =>
array (
'location' =>
array (
'id' => NULL,
'type' =>
array (
'id' => 48,
'name' =>
array (
'ca' => 'Estació de tren',
'de' => 'Bahnhof',
'en' => 'Trainstation',
'es' => 'Estación de tren',
'fr' => 'Gare',
'nl' => 'Treinstation',
),
),
'address' =>
array (
'city' => '\'s-Hertogenbosch',
),
'score' => NULL,
'distance' => 0,
'name' =>
array (
'nl' => 'Treinstation Den Bosch',
),
'centroid' =>
array (
'wkt' => 'POINT(5.2946805954 51.6906491617)',
),
),
'text' =>
array (
'id' => NULL,
'type' =>
array (
'id' => 1,
'name' =>
array (
'it' => 'Generale',
'es' => 'General',
'de' => 'Allgemeine',
'nl' => 'Algemeen',
'ca' => 'General',
'fr' => 'Général',
'en' => 'General',
),
),
'format' =>
array (
'id' => 1,
'name' =>
array (
'en' => 'General',
'ca' => 'General',
'de' => 'Allgemeine',
'fr' => 'Général',
'nl' => 'Algemeen',
'it' => 'Generale',
'es' => 'General',
),
),
'owner' => NULL,
'description' =>
array (
'nl' => 'Treinstation Den Bosch',
),
'source' => NULL,
'copyright' => NULL,
'infoLink' => NULL,
'media' =>
array (
'id' => NULL,
'type' =>
array (
'id' => 1,
'name' =>
array (
'nl' => 'Afbeelding',
'fr' => 'Image',
'en' => 'Image',
'it' => 'Immagine',
'es' => 'Imagen',
'de' => 'Bild',
'ca' => 'Imatge',
),
),
'owner' => NULL,
'filename' =>
array (
'nl' => 'ec4e71365e9744bfc3c26cd8639a669e_c53731769769ce9df74e9a8daa972c81cb14f785.jpeg',
),
'url' =>
array (
'nl' => 'https://image.routeyou.com/shrink/fit/500x500/ec4e71365e9744bfc3c26cd8639a669e_c53731769769ce9df74e9a8daa972c81cb14f785.jpeg',
),
'description' =>
array (
'nl' => '',
),
'source' =>
array (
'id' => NULL,
'name' =>
array (
'nl' => NULL,
),
'description' =>
array (
'nl' => '',
),
'link' =>
array (
'id' => NULL,
'name' =>
array (
'nl' => '',
),
'uri' =>
array (
'nl' => 'http://nl.wikipedia.org/wiki/Afbeelding:Station_of_%27s-Hertogenbosch.jpg',
),
),
),
'copyright' => NULL,
),
),
),
...
),
'media' =>
array (
0 =>
array (
'id' => 319316,
'score' => 0,
'type' => //type of the media: image(1), flash video (2), mp3(3), YouTube(4), Vimeo (5)
array (
'id' => 1,
),
'content' =>
array (
'nl' => 'ec4e71365e9744bfc3c26cd8639a669e_c53731769769ce9df74e9a8daa972c81cb14f785.jpeg',
),
'copyright' => NULL,
'source' => NULL,
'uri' =>
array (
'nl' => 'https://image.routeyou.com/shrink/fit/400x300/ec4e71365e9744bfc3c26cd8639a669e_c53731769769ce9df74e9a8daa972c81cb14f785.jpeg',
),
'languages' =>
array (
0 => 'nl',
),
),
),
'lengthRelative' => 0.29999999999999999, //difficulty level: 70% of routes of that type longer
'difficulty' => 0.19999999999999998, //general difficulty level: 80% of routes of that type longer
)
getInstructions
Get instructions of a route
Input
- id (Integer): get the instructions of the given route
Output
- instruction(s) (Array(Instructions)): An instruction contains following keys:
- atGeometry: place of instruction
- distance: place in the route of an instruction
- using: street
- at: only used for routing with nodes (current node)
- to: only used for routing with nodes (next node)
- fromBearing:
- toBearing:
- angle: angle to turn
Example route 4569147:
Below you find a fragment of the instructions of route 4569147. View the detailed print on our website to see the visualisation of the instructions.
array (
array (
'atGeometry' => 'POINT(3.750779 51.044232)',
'distance' => 0,
'using' => 'Maagd van Gentstraat',
'toBearing' => -95,
'at' => NULL,
'to' => NULL,
'angle' => NULL,
'fromBearing' => NULL,
),
array (
'atGeometry' => 'POINT(3.748281 51.045888)',
'distance' => 276.69999999999999,
'fromBearing' => -6,
'toBearing' => -29,
'at' => NULL,
'to' => NULL,
'using' => '',
'angle' => -23,
),
...
array (
'atGeometry' => 'POINT(3.750494 51.044217)',
'distance' => 1013.6,
'using' => 'Maagd van Gentstraat',
'fromBearing' => -3,
'toBearing' => 85,
'at' => NULL,
'to' => NULL,
'angle' => 88,
),
array (
'atGeometry' => 'POINT(3.75078 51.04423)',
'distance' => 1033.4000000000001,
'using' => 'Maagd van Gentstraat',
'fromBearing' => 85,
'at' => NULL,
'to' => NULL,
'angle' => NULL,
'toBearing' => NULL,
),
)
getClassifications
Get the classifications (themes, characteristics and groups) of one or multiple routes by id
Input
- id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
Output
- an array with keys group, themes and characteristics
search
Get the routes that meet the conditions
Input
- conditions(s) (Struct|null): the conditions the routes has to meet. Default only public routes
Possible keys:- bounds: array(
'min' => array(
'lon' => <min longitude>,
'lat' => <min latitude>
),
'max' => array(
'lon' => <max longitude>,
'lat' => <max latitude>
)
) - id: integer|array
- type.id: integer|array
- owner.id: integer|array
- score.min: float between 0 and 1
- score.max: float between 0 and 1
- length.min: integer, length in m
- length.max: integer, length in m
- difficulty.min: float between 0 and 1
- difficulty.max: float between 0 and 1
- difficultyAuthor.min: float between 0 and 1
- difficultyAuthor.max: float between 0 and 1
- editedDate.min: date (+time) in iso 8601
- editedDate.max: date (+time) in iso 8601
- flag: iso2 country code (example: 'be', 'nl', 'de', ..)
- language: iso2 language code (example: 'nl', 'en', 'fr', 'de', ...)
- keywords: words separated by spaces
- group.id: integer|array
- exclude.group.id: integer|array
- characteristic.id: integer|array
- exclude.characteristic.id: integer|array
- theme.id: integer|array
- exclude.theme.id: integer|array
- activity: boolean
- activity.owner.id: integer|array
- event: boolean
- event.owner.id: integer|array
- favorite.user.id: integer|array
- permission.readable: true //show all allowed routes. Default only public routes are returned
- bounds: array(
- sorting (String|Array): determines the order of the routes. When there are multiple sorting criteria, an array is necessary.
Possible sortings:- id [ASC|DESC]
- length [ASC|DESC]
- score [ASC|DESC]
- name [ASC|DESC]
- difficulty [ASC|DESC]
- difficultyAuthor [ASC|DESC]
- owner.id [ASC|DESC]
- viewCount [ASC|DESC]
- viewCountThisMonth [ASC|DESC]
- likeCount [ASC|DESC]
- editedDate [ASC|DESC]
- sortings used on the website
- Relevance: []
- Name A-Z: ["name ASC"]
- Name Z-A: ["name DESC"]
- Most viewed of all time: ["viewCount DESC", "editedDate DESC"]
- Most viewed this month: ["viewCountThisMonth DESC", "editedDate DESC"]
- Most recently created or edited: ["editedDate DESC"]
- Score: ["score DESC", "editedDate DESC"]
- Length ascending: ["length ASC", "editedDate DESC"]
- Length descending: ["length DESC", "editedDate DESC"]
- limit (Integer): maximum number of routes returned (default of 10, maximum 100 routes per call)
- offset (Integer): number of routes to skip (maximum 10000)
- options (Struct|Null):
- possibility to return route media: array('media' => true)
- possibility to return created date, updated date and edited date from a route: array('dates' => true)
Output
- routes(s) (Array(Object)): an array of routes in the passed order is returned
searchAdvanced
Get the routes that meet the conditions
Input
identical to search function above.
Possibility to return the number of results by cluster by adding array('clusters' => true) to the options parameter
Output
- routes (Array(Object)): an array of routes in the passed order is returned
- total: number of routes that satify the conditions. Maximum 1000, when more 1000 is returned and more field is true
- more: when more then 1000 routes satisfy the conditions, more is true.
searchBounds
Retrieves the bounding box around all routes matching the given conditions
Input
- conditions(s) (Struct|null): the conditions the routes has to meet. Default only public routes.
Identical to conditions of function search. - cache (boolean|null): when null, the web service chooses if cache is activated. Otherwise overruled by the boolean
Output
- bounding box (String): Box composed of minimum longitude, minimum latitude, maximum longitude and maximun latitude
getType
Get route type by id
Input
- id(s) (Integer|Array(Integer)): get the route type(s) with the given id(s)
- language (String|Null): language in iso2
Output
- route type(s) (Object|Array(Object)): if the input is just one id, an object is returned. If the input is an array, an array with the ids as key and the objects as value is returned.
getTypeHierarchy
Get route type with their hierarchy by id
Input
- id(s) (Integer|Array(Integer)): get the routetype(s) with the given id(s)
- language (String|Null): language in iso2
Output
- route type(s) (Object|Array(Object)): if the input is just one id, an object is returned. If the input is an array, an array with the ids as key and the objects as value is returned.
changeLanguage
Change the language of a route
Input
- id (Integer)): the id of the route you want to change
- current language (String): the current language
- new language (String): the language the route has to be
Output
- successful (boolean): true if successful
save
Make changes to a route. The right permissions are necessary
Input
- data (Struct): the data to update. The data has to be in the same format as received from a get-call. Only pass the route id and the fields that need to be changed.
Only the following fields are allowed to be changed through the web service:
beginAddress, endAddress, permission.id, type.id, flag, difficultyAuthor, name, description, trackName, infoUri, source.name, source.uri, infoUri
Output
- success (Boolean): true if successful, false if not
delete
Delete a route. The right permissions are necessary
Input
- id (integer): the id of the route
- language (Null|String): Optional, only pass this when you only want to remove the route in 1 language.
Output
- success (Boolean): true if successful, false if not
isFavorite
Checks if a route is marked as favorite. The right permissions are necessary
Input
- routeId (Integer): the id of the route
- userId (Null|Integer): optional parameter. Default the userId of the logged in user is used.
Output
- marked(Boolean): true if marked as favorite, false if not
addFavorite
Mark a route as favorite. The right permissions are necessary
Input
- routeId (Integer): the id of the route
- userId (Null|Integer): optional parameter. Default the userId of the logged in user is used.
Output
- success (Boolean): true if successful, false if not
removeFavorite
Unmark a route as favorite. The right permissions are necessary
Input
- routeId (Integer): the id of the group
- userId (Null|Integer): optional parameter. Default the userId of the logged in user is used.
Output
- success (Boolean): true if successful, false if not
getTileCoordinates
Get the tile coordinates (read here about this google's implementation) around the given routes.
Use: In case you want to cache the map related to the route(s) or create a print of the map and the route, you can get the required tiles for this route via this web service call.
You have to combine the output with the provided URL of the tile server as explained in this google's implementation. This URL and tile server depends on who provides the maps. That could be Google, or MapBox,...
Input
- id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
- minZoomLevel (Integer): between 0 and 19
- maxZoomLevel(Integer): between 0 and 19, greater than or equal to minZoomLevel
Output
- data (Struct(Object)): tile coordinates grouped by zoomLevel
Example
Example of inputparameters:
- array(44,45) //routes 44 & 45
- 12 //min zoom level 12
- 17 //max zoom level 17
getShape
Get the shape-files of one or multiple routes by id
Input
- id(s) (Integer|Array(Integer)): the route(s) with the given id(s)
- language (String|Null): language in iso2
- options(Struct|null):
Possible options:- SRID (integer):
- 4326: WGS84 (default)
- 31370: Belge Lambert 72
- SRID (integer):
Output
- content shape (Struct(String)): an array with the content of the dbf, prj, shp and shx-files. The encoding is specified in the array.
getShapeFromSearch
Get the shape-files of the routes that meet the conditions. Conditions and sorting are identical to the search-function
Input
- conditions(s) (Struct|null): the conditions the routes has to meet.
- sorting (String|Array): determines the order of the routes.
- limit (Integer): maximum number of routes returned
- offset (Integer): number of routes to skip
- options(Struct|null):
Possible options:- SRID (integer):
- 4326: WGS84 (default)
- 31370: Belge Lambert 72
- SRID (integer):
Output
- content shape (Struct(String)): an array with the content of the dbf, prj, shp and shx-files. The encoding is specified in the array.
getRegions
Get the top regions of a route.
Input
- id(s) (Integer|Array(Integer)): get the region of the route(s) with the given id(s)
- language (String|Null): language in iso2. Regions not available in the specified language are omitted.
- limit (Integer): maximum number of regions returned (default of 5, maximum 10)
Output
- an array with region-pois. When multiple ids are passed, regions are grouped by route.