JSONP web service

Table of contents

• Endpoint
• Construct request
  • Response
• Example (PHP)

Endpoint

Send requests to the following URL:

https://api.routeyou.com/%service-version%/json/%service-name%/%token%

The parts between % should be replaced with the following:

• %service-version%: the version of the service
• %service-name%: the name of the service
• %token%: a token which gives you access to the web service
  • This token can be generated by using the Session web service's "start" method.
  • When calling the Session web service's "start" method, the token can be omitted or replaced by a dash (-).
  • When calls where it is not necessary to log in, you can use the key directly instead of the token by adding the prefix "k-". You can then replace the token by "k-<key>"

Construct request

A JSONP request is sent using HTTP GET, with these URL parameters:

• id (integer - required)
  A number that identifies your request. You can choose this yourself. It is sent back unaltered in the response, so you can use it to match responses to requests in an asynchronous application.
• method (string - required)
  The name of the web service method you want to call.
• params (array - optional)
  A JSON encoded array of parameters for the web service method.
• callback (string - optional)
  The name of the JavaScript function that has to be called with the resulting data.

Keep in mind that most browsers have a limit on URL length, passing large amounts of data to the web service may not be possible with this protocol (it is not a problem for the response).

Response

The server sends back a JSON encoded object containing these keys:

• id (integer)
  A number that identifies your request. See above.
• result (any - only on success)
  The resulting data from your web service call.
• error (object - only on failure)
  Information about why the call failed.

If you have provided the callback parameter in the request, your callback function is called with the response.

Example (PHP)

The following code fetches all the routes (private ones included) you have marked as favorite. Note that there is no error handling in this example.

// Start session. Acquire the token that is needed for the subsequent web service calls.
$params = array(
    '<key>'
);
$url = 'https://api.routeyou.com/2.0/json/Session?id=1&method=start&params=' .
    json_encode($params);
$response = json_decode(file_get_contents($url), true);
$token = $response['result'];

// Log in.
$params = array(
    '<email>',
    '<password>'
);
$url = 'https://api.routeyou.com/2.0/json/User/' . $token .
    '?id=1&method=loginWithEmail&params=' . json_encode($params);
$response = json_decode(file_get_contents($url), true);
$user = $response['result'];

// Fetch favourite routes.
// When parameter permission.readable is omitted, only public routes are returned.
$params = array(
    array(
        'favorite.user.id' => $user['id'],
        'permission.readable' => true
    )
);
$url = 'https://api.routeyou.com/2.0/json/Route/' . $token .
    '?id=1&method=search&params=' . json_encode($params);
$response = json_decode(file_get_contents($url), true);
$favorites = $response['result'];
var_dump($favorites);

Back to RouteYou