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/parkpredict/

Response format

Only one format is currently available, JSON. The response content is sent compressed in gzip.

Accept: application/json
Accept-Encoding: gzip

Authentication

All routes, except /token, need an access token, which must be retrieved first.

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

Each access token is valid for 15 minutes only.

Date format

The dates and timestamps returned are in UTC and in the ISO 8601 format: 2015-03-16T13:29:14.686Z

Likewise, when using a timestamp as a parameter for a request, be sure to be using UTC and the ISO 8601 format.

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"

Response Codes

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

Code	Meaning
200	OK – Everything worked as expected
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 temporally offline for maintenance. Please try again later.

Tokens

Generate an access token

GET https://api.qucit.com/parkpredict/v1/token

GET https://api.qucit.com/parkpredict/v1/token HTTP/1.1
Authorization: Basic YmlrZXByZWRpY3Q6YXV0aGVudGljYXRpb24=
Accept: application/json
Accept-Encoding: gzip

curl -u John:Doe https://api.qucit.com/parkpredict/v1/token

// to be written

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 an example the username John with the password Doe, which yield the base64 string YmlrZXByZWRpY3Q6YXV0aGVudGljYXRpb24=

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: the token to use in subsequent requests
expires_in: number of seconds left until the token expires

Supported cities

GET Cities

GET https://api.qucit.com/parkpredict/v1/cities

GET https://api.qucit.com/parkpredict/v1/cities?access_token=c0eb00747e9af3b3adda0ee4abccac49 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip

curl -X GET \
    -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
    https://api.qucit.com/parkpredict/v1/cities

Get the list of available cities.

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

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 16
X-RateLimit-Reset:  1441888380

{
  "data": [
    {
      "city": "Bordeaux",
      "distance": 212,
      "country": "France",
      "longitude": -0.5792,
      "state": "Nouvelle-Aquitaine",
      "latitude": 44.8391,
      "scheme_id": "bordeaux_fr"
    },
    ...
  ]
}

On Street

GET Average time

GET https://api.qucit.com/parkpredict/v1/on-street/average-time

GET https://api.qucit.com/parkpredict/v1/on-street/average-time?access_token=c0eb00747e9af3b3adda0ee4abccac49&longitude=-0.5815833&latitude=44.8829943&arrival_tms=2016-01-13T14:00:00Z&city_code=bordeaux_fr HTTP/1.1
Accept: application/json
Accept-Encoding: gzip

curl -X GET \
    -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
    -d arrival_tms=2016-01-13T14:00:00Z \
    -d latitude=44.8390062 \
    -d longitude=-0.5815833 \
    -d scheme_id=bordeaux_fr \
    https://api.qucit.com/parkpredict/v1/on-street/average-time

Get the average parking time on street for a given location.

Parameter	Type	Description
access_token	string	Access token obtained from `/token`	required
longitude	number	Longitude	required
latitude	number	Latitude	required
arrival_tms	date	ISO 8601 UTC	required
scheme_id	string	Internal city ID, as obtained from `/v1/cities`	required

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 16
X-RateLimit-Reset:  1441888380

{
  "data": {
      "parking_id": null,
      "avgtime_in_seconds": 653
  }
}

Off Street

GET Parkings

GET https://api.qucit.com/parkpredict/v1/off-street/parkings

GET https://api.qucit.com/parkpredict/v1/off-street/parkings?access_token=c0eb00747e9af3b3adda0ee4abccac49&scheme_id=bordeaux_fr HTTP/1.1
Accept: application/json
Accept-Encoding: gzip

curl -X GET \
    -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
    -d scheme_id=bordeaux_fr \
    https://api.qucit.com/parkpredict/v1/off-street/parkings

Get the list of available parkings for a given city (scheme_id), with associated information.

Parameter	Type	Description
access_token	string	Access token obtained from `/token`	required
scheme_id	string	Internal city ID, as obtained from `/v1/cities`	required
parking_id	string	Identifier of a selected parking	optional

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 16
X-RateLimit-Reset:  1441888380

{
  "data": [
      {
        "scheme_id": "bordeaux_fr",
        "parking_id": "2325",
        "name": "Front du Médoc",
        "status": 1,
        "provider": "parcub",
        "total_spots": 230,
        "free_spots": 124,
        "is_full_probability": 0,
        "banking": null,
        "address": null,
        "longitude": -0.587818,
        "latitude": 44.838921
      },
     ...
  ]
}

For each parking, the response provides:

scheme_id(string): Internal ID of the city.
parking_id(string): Identifier of the parking in the city.
status(integer): Whether the parking is open AND has real-time occupation data.
provider(string): Company that manages the parking.
name(string): The parking’s name if available.
address(string): The parking’s address if provided by the system’s data feed.
latitude(float): Parking latitude.
longitude(float): Parking longitude.
total_spots(integer): The total number of spots in the parking.
free_spots(integer): The number of free spots available in the parking (if a real-time occupation data feed is available for the given parking).
is_full_probability(float): (between 0 and 1) the probability that the parking is currently full (useful in several cities only)
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.

GET Predictions

GET https://api.qucit.com/parkpredict/v1/off-street/predictions

GET https://api.qucit.com/parkpredict/v1/off-street/predictions?access_token=c0eb00747e9af3b3adda0ee4abccac49&scheme_id=bordeaux_fr HTTP/1.1
Accept: application/json
Accept-Encoding: gzip

curl -X GET \
    -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
    -d scheme_id=bordeaux_fr \
    https://api.qucit.com/parkpredict/v1/off-street/predictions

For all available parkings for a given city (scheme_id), or for only one parking (specified with parking_id), get probabilities of finding free spots in the near future.

Parameter	Type	Description
access_token	string	Access token obtained from `/token`	required
scheme_id	string	Internal city ID, as obtained from `/v1/cities`	required
parking_id	string	Identifier of a selected parking	optional

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 16
X-RateLimit-Reset:  1441888380

{
  "data": [
      {
         "parking_id": "02",
         "scheme_id": "dijon_fr",
         "predictions": [
           {
             "tms_gmt": "2017-11-16T14:37:25",
             "free_spots": 0.998,
             "tau_in_min": 240
           },
           {
             "tms_gmt": "2017-11-16T14:37:25",
             "free_spots": 0.893,
             "tau_in_min": 360
           },
           ...
         ],
         "parking_id": "03",
         "scheme_id": "dijon_fr"
     },
     ...
  ]
}

For each parking, the response provides:

scheme_id(string): Internal ID of the city.
parking_id(string): Identifier of the parking.
predictions(array):
- A prediction for each available delta in the future:
- tms_gmt(string): current timestamp in UTC (for parkings with real-time occupation data: timestamp of last update).
- free_spots(float): probability of finding a free spot in the parking (values are between 0 and 1)
- tau_in_min(integer): number of minutes in the future where the probability applies.

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

GET Occupation Predictions

GET https://api.qucit.com/parkpredict/v1/off-street/occupation-predictions

GET https://api.qucit.com/parkpredict/v1/off-street/occupation-predictions?access_token=c0eb00747e9af3b3adda0ee4abccac49&scheme_id=bordeaux_fr HTTP/1.1
Accept: application/json
Accept-Encoding: gzip

curl -X GET \
    -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
    -d scheme_id=bordeaux_fr \
    https://api.qucit.com/parkpredict/v1/off-street/occupation-predictions

For all available parkings for a given city (scheme_id), or for only one parking (specified with parking_id), get predicted number of free spots in the near future.

Parameter	Type	Description
access_token	string	Access token obtained from `/token`	required
scheme_id	string	Internal city ID, as obtained from `/v1/cities`	required
parking_id	string	Identifier of a selected parking	optional

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 16
X-RateLimit-Reset:  1441888380

{
  "data": [
      {
         "parking_id": "02",
         "scheme_id": "dijon_fr",
         "predictions": [
           {
             "tms_gmt": "2017-11-16T14:37:25",
             "free_spots": 40.0,
             "total_spots": 215,
             "tau_in_min": 240
           },
           {
             "tms_gmt": "2017-11-16T14:37:25",
             "free_spots": 37.0,
             "total_spots": 215,
             "tau_in_min": 360
           },
           ...
         ],
         "parking_id": "03",
         "scheme_id": "dijon_fr"
     },
     ...
  ]
}

For each parking, the response provides:

scheme_id(string): Internal ID of the city.
parking_id(string): Identifier of the parking.
predictions(array):
- A prediction for each available delta in the future:
- tms_gmt(string): current timestamp in UTC (for parkings with real-time occupation data: timestamp of last update).
- free_spots(float): predicted number of free spots in the parking.
- total_spots(integer): total spots of the parking.
- tau_in_min(integer): number of minutes in the future where the probability applies.

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

GET Filling Rates

GET https://api.qucit.com/parkpredict/v1/off-street/filling-rates

GET https://api.qucit.com/parkpredict/v1/off-street/filling-rates?access_token=c0eb00747e9af3b3adda0ee4abccac49&scheme_id=bordeaux_fr HTTP/1.1
Accept: application/json
Accept-Encoding: gzip

curl -X GET \
    -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
    -d scheme_id=bordeaux_fr \
    https://api.qucit.com/parkpredict/v1/off-street/filling-rates

Get the list of parking filling rates for a given scheme_id.

Parameter	Type	Description
access_token	string	Access token obtained from `/token`	required
scheme_id	string	Internal city ID, as obtained from `/v1/cities`	required
parking_id	string	Identifier of the parking	optional

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 16
X-RateLimit-Reset:  1441888380

{
  "data": [
      {
        "filling_rate": 0.9,
        "parking_id": "2325",
        "scheme_id": "bordeaux_fr"
      },
     ...
  ]
}

For each parking, the response provides:

scheme_id(string): Internal ID of the city.
parking_id(string): Identifier of the parking.
filling_rate(float): parking’s filling rate for it to be considered as full. By default, it’s set to 0.9 which is 90% of the parking’s capacity.

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

PUT Filling Rates

PUT https://api.qucit.com/parkpredict/v1/off-street/filling-rates

PUT https://api.qucit.com/parkpredict/v1/off-street/filling-rates HTTP/1.1
Accept: application/json
Accept-Encoding: gzip

curl -X PUT \
    -d access_token=c0eb00747e9af3b3adda0ee4abccac49 \
    -d scheme_id=bordeaux_fr \
    -d parking_id=288e0b \
    https://api.qucit.com/parkpredict/v1/off-street/filling-rates

Sets filling rates for either one parking or all parkings from the given city.

Parameter	Type	Description
access_token	string	Access token obtained from `/token`	required
scheme_id	string	an Internal city code	required
filling_rate	string	Parking’s filling rate	required
parking_id	string	Identifier of the parking	optional

HTTP/1.1 200 OK
Content-Encoding: gzip
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 16
X-RateLimit-Reset:  1441888380

{
  "data": [
      {
        "filling_rate": 0.9,
        "parking_id": "2317",
        "scheme_id": "bordeaux_fr"
      },
     ...
  ]
}

For each parking, the response provides:

scheme_id(string): Internal ID of the city.
parking_id(string): Identifier of the parking.
- filling_rate(float): parking’s filling rate for it to be considered as full. By default, it’s et to 0.9 which is 90% of the parking’s capacity. Values will be set to null if the information is not available.