Route Web Service 2.0

Table of contents

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.

Technical

The web service is accessible using:

Overview of provided functions

get

Get information of one or multiple routes by id

Input

  1. id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
  2. language (String|Null): language in iso2
  3. options (Struct|Null):
    • possibility to strip HTML-tags: array('stripTags' => true)
    • possibility to return route media: array('media' => true)

Output

getGeometry

Get geometry of one or multiple routes by id

Input

  1. id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
  2. language (String|Null): language in iso2
  3. options (Struct|Null):
    • possibility to strip HTML-tags: array('stripTags' => true)
    • possibility to return route media: array('media' => true)

Output

getFull

Get all information of one or multiple routes by id. Includes geometry and height-information.

Input

  1. id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
  2. language (String|Null): language in iso2
  3. options (Struct|Null):
    • possibility to strip HTML-tags: array('stripTags' => true)
    • possibility to return route media: array('media' => true)

Output

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

  1. id (Integer): get the instructions of the given route

Output

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

  1. id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)

Output

search

Get the routes that meet the conditions

Input

  1. 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
    • 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
    • characteristic.id: integer|array
    • 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
  2. 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]
    • owner.id [ASC|DESC]
    • viewCount [ASC|DESC]
    • viewCountThisMonth [ASC|DESC]
  3. limit (Integer): maximum number of routes returned (default of 10, maximum 100 routes per call)
  4. offset (Integer): number of routes to skip
  5. cache (boolean|null): when null, the web service chooses if cache is activated. Otherwise overruled by the boolean

Output

searchBounds

Retrieves the bounding box around all routes matching the given conditions

Input

  1. conditions(s) (Struct|null): the conditions the routes has to meet. Default only public routes.
    Identical to conditions of function search.
  2. cache (boolean|null): when null, the web service chooses if cache is activated. Otherwise overruled by the boolean

Output

getType

Get route type by id

Input

  1. id(s) (Integer|Array(Integer)): get the route type(s) with the given id(s)
  2. language (String|Null): language in iso2

Output

getTypeHierarchy

Get route type with their hierarchy by id

Input

  1. id(s) (Integer|Array(Integer)): get the routetype(s) with the given id(s)
  2. language (String|Null): language in iso2

Output

changeLanguage

Change the language of a route

Input

  1. id (Integer)): the id of the route you want to change
  2. current language (String): the current language
  3. new language (String): the language the route has to be

Output

save

Make changes to a route. The right permissions are necessary

Input

  1. data (Struct): the data to update

Output

isFavorite

Checks if a route is marked as favorite. The right permissions are necessary

Input

  1. routeId (Integer): the id of the route
  2. userId (Null|Integer): optional parameter. Default the userId of the logged in user is used.

Output

addFavorite

Mark a route as favorite. The right permissions are necessary

Input

  1. routeId (Integer): the id of the route
  2. userId (Null|Integer): optional parameter. Default the userId of the logged in user is used.

Output

removeFavorite

Unmark a route as favorite. The right permissions are necessary

Input

  1. routeId (Integer): the id of the group
  2. userId (Null|Integer): optional parameter. Default the userId of the logged in user is used.

Output

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

  1. id(s) (Integer|Array(Integer)): get the route(s) with the given id(s)
  2. minZoomLevel (Integer): between 0 and 19
  3. maxZoomLevel(Integer): between 0 and 19, greater than or equal to minZoomLevel

Output

Example

Example of inputparameters:

getShape

Get the shape-files of one or multiple routes by id

Input

  1. id(s) (Integer|Array(Integer)): the route(s) with the given id(s)
  2. language (String|Null): language in iso2
  3. options(Struct|null):
    Possible options:
    • SRID (integer):
      • 4326: WGS84 (default)
      • 31370: Belge Lambert 72

Output

getShapeFromSearch

Get the shape-files of the routes that meet the conditions. Conditions and sorting are identical to the search-function

Input

  1. conditions(s) (Struct|null): the conditions the routes has to meet.
  2. sorting (String|Array): determines the order of the routes.
  3. limit (Integer): maximum number of routes returned
  4. offset (Integer): number of routes to skip
  5. options(Struct|null):
    Possible options:
    • SRID (integer):
      • 4326: WGS84 (default)
      • 31370: Belge Lambert 72

Output

getRegions

Get the top regions of a route.

Input

  1. id(s) (Integer|Array(Integer)): get the region of the route(s) with the given id(s)
  2. language (String|Null): language in iso2. Regions not available in the specified language are omitted.
  3. limit (Integer): maximum number of regions returned (default of 5, maximum 10)

Output

© 2006-2019 RouteYou - www.routeyou.com