BikePredict API

Introduction

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

use predictable, resource-oriented URLs
use built-in HTTP features for passing parameters and authentication
use standard HTTP response codes to indicate API errors
return JSONs

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:

access_token(string): the token to use in subsequent requests
expires_in(integer): number of seconds left until the token expires

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: A projected value in the future that might take various forms:
- Projected occupations.
- Chances of finding available bikes or docks.
Forecast limit: The further accepted date in the future while asking for forecasts.

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:

name(string): The system’s commercial name.
city(string): The city served by the system.
state(string): The state where the city is located.
country(string): The country where the city is located.
operator(string): The company operating the system.
lat(float): A latitude within the system range.
lng(float): A longitude within the system range.

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:

sid(string): Identifier for the station.
name(string): The station name if provided by the system’s data feed.
address(string): If provided by the system’s data feed.
lat(float): Station latitude.
lng(float): Station longitude.
total_docks(integer): The total number of docks in the station.
banking(integer): 1 means a payment terminal is present, 0 if it’s not.

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:

sid(string): Identifier for the station.
status(integer): 1 if the station is active, otherwise 0.
realtime(object):
- bikes(integer): the current number of available bikes in the station.
- docks(integer): the current number of free docks in the station.
- Will be empty if the station is not active.
predictions(array):
- A prediction for each date given as parameter in the same order as dates.
- Each prediction has the follwing information:
  - date(date-time): a timestamp of the date at which the prediction apply.
  - bikes(float): chances of finding a bike at the given date
  - docks(float): chances of finding a dock at the given date
- Will be set to an empty array if the station is not active.

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:

sid(string): Identifier for the station.
status(integer): 1 if the station is active, otherwise 0.
realtime(object):
- bikes(integer): the current number of available bikes in the station.
- docks(integer): the current number of free docks in the station.
- Will be empty if the station is not active.
occupations(array):
- A projected occupation for each date given as parameter in the same order as dates.
- Each occupation has the follwing information:
  - date(date-time): a timestamp of the date at which the projected occupation apply.
  - bikes(float): projected number of available bikes at the given date
  - docks(float): projected number of available docks at the given date
- Will be set to an empty array if the station is not active.

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:

radius(integer): will select stations within the cercle centred on location and having the given input as radius in meters.
limit(integer): will select a maximum number of stations equal to the given input.

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:

sid(array[string]): One or more stations that will be selected.

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
    }
  ]
}