NAV
http curl javascript

BikePredict API

Introduction

All Qucit APIs are built on HTTP, according to REST principles. Our APIs:

Base URL

All URLs referenced in the documentation have the following base:

https://api.qucit.com/bikepredict/v2

Response format and compression

GET ... HTTP/1.1
Accept: application/json
Accept-Encoding: gzip

Only one format is currently available, JSON.

The response content is sent compressed in gzip.

Date format

Timestamp

We use the ISO 8601 format across our APIs. Example: 2015-03-16T13:29:14.686Z

This is indeed the simplest and safest way to pass dates, in particular with respect to daylight saving time.

date -u +%FT%TZ  #"2015-03-16T13:29:14.686Z"
var date = new Date();
date.toISOString();  //"2015-03-16T13:29:14.686Z"

Human readable

In addition to the previously defined timestamps, we accept human readable expressions as dates.

Expression Meaning
now current timestamp in UTC
in-N-hours now + N hours
in-N-minutes now + N minutes
N-hours-ago now - N hours
N-minutes-ago now - N minutes

In any of the above expressions, N is a positive integer.

Response Codes

The Qucit APIs use standard HTTP response codes to indicate whether the request was successful or not:

Code Meaning
200 OK – Everything worked as expected
304 Not Modified – The document has not been modified
400 Bad Request – A parameter is missing or is invalid
401 Unauthorized – Authentication failed
402 Request Failed – Parameters were valid but request failed
403 Forbidden – Access to the resource is denied
404 Not Found – The URL does not correspond to an available resource
406 Not Acceptable – You requested a format that is not provided
429 Too Many Requests – You have exceeded your quotas
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Authentication

Overview

All routes, except /token, need a valid access_token, which must be retrieved first.

This /token route requires a HTTP Basic Authentication using the username and passwords that were provided to you upon subscription.

Each access token is valid for 15 minutes only.

GET token

Request

GET https://api.qucit.com/bikepredict/v2/token

GET https://api.qucit.com/bikepredict/v2/token HTTP/1.1
Authorization: Basic YmlrZXByZWRpY3Q6YXV0aGVudGljYXRpb24=
Accept: application/json
Accept-Encoding: gzip
curl -u bikepredict:authentication https://api.qucit.com/bikepredict/v2/token
var API_USERNAME = "";
var API_PASSWORD = "";

$.ajax({
  type: "GET",
  url: "https://api.qucit.com/bikepredict/v2/token",
  headers: {
    "Authorization": "Basic " + btoa(API_USERNAME + ":" + API_PASSWORD)
  },
  success: function (data) {
  }
});

To obtain a token, authentication credentials must be sent using HTTP Basic Auth, using the username and password that were provided on subscription.

In the following, we use as example the username bikepredict with the password authentication, which yield the base64 string YmlrZXByZWRpY3Q6YXV0aGVudGljYXRpb24=

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19
X-RateLimit-Reset:  1441888380
{
  "data": {
    "access_token": "c0eb00747e9af3b3adda0ee4abccac49",
    "expires_in": 900
  }
}

The response provides:

Rate-Limit

We encourage you to use the same access_token for as long as possible when implementing your client. You are limited to 20 calls to /token a minute per IP address. This route has its limits counted separately from the rest of the API’s routes.

Resources

Overview

Terminology

Forecast limit

Currently set to 45 minutes in the future. This value can be raised depending on your contract.

Multiple forecasts at once

Multiple values of date can be specified in one request. This will result into an array of forecasts in the same order as the dates received.

The maximum number of simultaneous dates will depend on your contract.

GET systems

Request

GET https://api.qucit.com/bikepredict/v2/systems

GET https://api.qucit.com/bikepredict/v2/systems?access_token=c0eb00747e9af3b3adda0ee4abccac49 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
curl -X GET \
     -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
     https://api.qucit.com/bikepredict/v2/systems

Provides detailed information about available bikeshare systems.

Parameter Type Description
access_token string Access token obtained from /token required

Response

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset:  1441888380
Last-Modified: Wed, 27 Jul 2016 07:01:52 GMT
{
  "data": [
    {
      "name": "VCub",
      "city": "Bordeaux",
      "state": "Aquitaine",
      "country": "France",
      "operator": "Keolis",
      "lat": 44.807735,
      "lng": -0.560024
  },
  ...
  ]
}

For each system, the response provides:

Values will be set to null if the information is not available.

GET stations

Request

GET https://api.qucit.com/bikepredict/v2/stations

GET https://api.qucit.com/bikepredict/v2/stations?access_token=c0eb00747e9af3b3adda0ee4abccac49&location=44.8067540,-0.5595780 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
curl -X GET \
     -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
     -d location=44.8067540,-0.5595780 \
     https://api.qucit.com/bikepredict/v2/stations
var latitude = 48.8588377;
var longitude = 2.2775177;

$.ajax({
  type: "GET",
  url: "https://api.qucit.com/bikepredict/v2/stations",
  data: {
    access_token: "c0eb00747e9af3b3adda0ee4abccac49",
    location: latitude + "," + longitude
  },
  success: function (data) {
  }
});

Provides detailed information about bikeshare stations.

Parameter Type Description
access_token string Access token obtained from /token required
location string Comma separated floats lat,lng required
system string Commercial name of the bikeshare system
radius integer A radius in meters within which stations will be selected (more)
limit integer A maximum number of stations to be returned (more)
sid array[string] Selects stations within the given list (more)

Response

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset:  1441888380
Last-Modified: Wed, 27 Jul 2016 07:01:52 GMT
{
  "metadata": {
    "system": {
      "name": "VCub",
      "operator": "Keolis Bordeaux Métropole",
      "type": "bikeshare"
    }
  },
  "data": [
    {
      "sid": "75",
      "name": "Begles Poste",
      "total_docks": 20,
      "banking": 1,
      "address": "111 AVENUE LUCIEN LEROUSSEAU",
      "lat": 44.807735,
      "lng": -0.560024
  },
  ...
  ]
}

For each station, the response provides:

Values will be set to null if the information is not available.

Stations are sorted based on their distance from location.

GET predictions

Request

Chances of finding bikes and docks at a given date up to the forecast limit.

GET https://api.qucit.com/bikepredict/v2/predictions

GET https://api.qucit.com/bikepredict/v2/predictions?access_token=c0eb00747e9af3b3adda0ee4abccac49&location=44.8067540,-0.5595780&date=in-45-minutes&riders=4 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
curl -X GET \
  -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
  -d location=44.8067540,-0.5595780 \
  -d date=in-45-minutes \
  -d riders=4 \

  https://api.qucit.com/bikepredict/v2/predictions
var latitude = 48.8588377;
var longitude = 2.2775177;
var now_tms = new Date().toJSON();

$.ajax({
  type: "GET",
  url: "https://api.qucit.com/bikepredict/v2/predictions",
  data: {
    access_token: "c0eb00747e9af3b3adda0ee4abccac49",
    location: latitude + "," + longitude,
    date: [now_tms, "in-15-minutes"]
  },
  traditional: true,
  success: function (data) {
  }
});

Provides predictions for a selection of stations for each date given in parameter.

Parameter Type Description
access_token string Access token obtained from /token required
location string Comma separated floats lat,lng required
system string Commercial name of the bikeshare system
date array[string] one or an array of timestamps at which predictions are needed (in the future) required
riders integer Number of riders. Must be in [1, 2, 3, 4, 5] defaults to 1
radius integer A radius in meters within which stations will be selected (more)
limit integer A maximum number of stations to be returned (more)
sid array[string] Selects stations within the given list (more)

Response

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset:  1441888380
Last-Modified: Wed, 27 Jul 2016 07:01:52 GMT
{
  "metadata": {
    "system": {
      "name": "VCub",
      "operator": "Keolis Bordeaux Métropole",
      "type": "bikeshare"
    }
  },
  "data": [
    {
      "sid": "129",
      "status": 1,
      "realtime": {
        "docks": 3,
        "bikes": 27
      },
      "predictions": [
        {
          "date": "2016-07-26T12:55:00Z",
          "docks": 0.3442622951,
          "bikes": 1
        }
      ]
  },
  ...
  ]
}

For each station, the response provides:

Values will be set to null if the information is not available.

Stations are sorted based on their distance from location.

GET occupations

Request

Projected number of available bikes and docks at a given date up to the forecast limit.

GET https://api.qucit.com/bikepredict/v2/occupations

GET https://api.qucit.com/bikepredict/v2/occupations?access_token=c0eb00747e9af3b3adda0ee4abccac49&location=44.8067540,-0.5595780&date=in-45-minutes HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
curl -X GET \
  -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
  -d location=44.8067540,-0.5595780 \
  -d date=in-45-minutes \

  https://api.qucit.com/bikepredict/v2/occupations
var latitude = 48.8588377;
var longitude = 2.2775177;
var now_tms = new Date().toJSON();

$.ajax({
  type: "GET",
  url: "https://api.qucit.com/bikepredict/v2/occupations",
  data: {
    access_token: "c0eb00747e9af3b3adda0ee4abccac49",
    location: latitude + "," + longitude,
    date: [now_tms, "in-15-minutes"]
  },
  traditional: true,
  success: function (data) {
  }
});

Provides occupations for a selection of stations for each date given in parameter.

Parameter Type Description
access_token string Access token obtained from /token required
location string Comma separated floats lat,lng required
system string Commercial name of the bikeshare system
date array[string] one or an array of timestamps at which predictions are needed (in the future) required
radius integer A radius in meters within which stations will be selected (more)
limit integer A maximum number of stations to be returned (more)
sid array[string] Selects stations within the given list (more)

Response

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset:  1441888380
Last-Modified: Wed, 27 Jul 2016 07:01:52 GMT
{
  "metadata": {
    "system": {
      "name": "VCub",
      "operator": "Keolis Bordeaux Métropole",
      "type": "bikeshare"
    }
  },
  "data": [
    {
      "sid": "129",
      "status": 1,
      "realtime": {
        "docks": 3,
        "bikes": 27
      },
      "occupations": [
        {
          "date": "2016-07-26T12:55:00Z",
          "docks": 6,
          "bikes": 24
        }
      ]
  },
  ...
  ]
}

For each station, the response provides:

Values will be set to null if the information is not available.

Stations are sorted based on their distance from location.

GET https://api.qucit.com/bikepredict/v2/predictions?access_token=c0eb00747e9af3b3adda0ee4abccac49&location=44.8067540,-0.5595780&date=in-45-minutes&date=in-1-hours&riders=4 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
curl -X GET \
  -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
  -d location=44.8067540,-0.5595780 \
  -d date=in-45-minutes \
  -d date=in-1-hours\
  -d riders=4 \

  https://api.qucit.com/bikepredict/v2/predictions
HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset:  1441888380
Last-Modified: Wed, 27 Jul 2016 07:01:52 GMT
{
  "metadata": {
    "system": {
      "name": "VCub",
      "operator": "Keolis Bordeaux Métropole",
      "type": "bikeshare"
    }
  },
  "data": [
    {
      "sid": "129",
      "status": 1,
      "realtime": {
        "docks": 3,
        "bikes": 27
      },
      "predictions": [
        {
          "date": "2016-07-26T12:55:00Z",
          "docks": 0.3442622951,
          "bikes": 1
        },
        {
          "date": "2016-07-26T13:10:00Z",
          "docks": 0.3129281,
          "bikes": 1
        }
      ]
    },
    ...
  ]
}

Filters

In order to control the number of predictions made, results can be filtered.

For both /stations and /predictions, it is possible to filter the stations returned by the API. The filtering can either be location based or simply by restricting the search to a list of stations provided by the client.

Both methods can be combined.

Based on location

It’s possible to filter stations based on their location by providing values for the following parameters:

In the example, we limit our search for predictions to the closest two stations in 1KM radius.

GET https://api.qucit.com/bikepredict/v2/predictions?access_token=c0eb00747e9af3b3adda0ee4abccac49&location=44.8067540,-0.5595780&date=in-45-minutes&riders=4&radius=1000&limit=2 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
curl -X GET \
  -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
  -d location=44.8067540,-0.5595780 \
  -d date=in-45-minutes \
  -d riders=4 \
  -d radius=1000 \
  -d limit=2

  https://api.qucit.com/bikepredict/v2/predictions
HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset:  1441888380
Last-Modified: Wed, 27 Jul 2016 07:01:52 GMT
{
  "metadata": {
    "system": {
      "name": "VCub",
      "operator": "Keolis Bordeaux Métropole",
      "type": "bikeshare"
    }
  },
  "data": [
    {
      "status": 1,
      "realtime": {
        "docks": 11,
        "bikes": 7
      },
      "predictions": [
        {
          "docks": 1,
          "bikes": 1
        }
      ],
      "sid": "75"
    },
    {
      "status": 1,
      "realtime": {
        "docks": 6,
        "bikes": 11
      },
      "predictions": [
        {
            "date": "2016-07-26T12:55:00Z",
          "docks": 0.9986394558,
          "bikes": 1
        }
      ],
      "sid": "129"
    }
  ]
}

Based on station

It’s possible to limit stations to a restricted list of stations the following parameters:

In the example, we ask for information about the station with sid = "75".

GET https://api.qucit.com/bikepredict/v2/predictions?access_token=c0eb00747e9af3b3adda0ee4abccac49&location=44.8067540,-0.5595780&sid=75 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
curl -X GET \
  -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
  -d location=44.8067540,-0.5595780 \
  -d sid=75 \

  https://api.qucit.com/bikepredict/v2/stations
HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset:  1441888380
Last-Modified: Wed, 27 Jul 2016 07:01:52 GMT
{
  "data": [
    {
      "name": "Begles Poste",
      "total_docks": 20,
      "sid": "75",
      "banking": 1,
      "address": "111 AVENUE LUCIEN LEROUSSEAU",
      "lat": 44.807735,
      "lng": -0.560024
    }
  ]
}