OUIBUS API FOR DEVELOPERS

Introduction

Overview

This document describes the official OUIBUS API. We assume that you are already familiar with OUIBUS, the subsidiary of SNCF which operates coach services in Europe. We also assume that you have some experience with programming, including communicating with HTTP endpoints.

The API is free to use, it only requires you to sign up to get an API key.

Getting started

  1. Sign up and get an API key.
  2. Read this documentation.
  3. Start making requests.

API

Authentication

You authenticate to the OUIBUS API by providing your API key in the Authorization HTTP header. You will get an API key after you sign up.

Current version and endpoint

The current version of the API is v1, and the endpoint is https://api.idbus.com. A request can be made with curl with the following command:

$ curl -H "Authorization: Token $API_KEY" \
    --compressed https://api.idbus.com/v1/stops

The API version is included in the endpoint path. Bug fixes and feature additions may be added to an endpoint without advancing its version number. This can include adding optional parameters or response fields. To prevent future compatibility issues, your application should be prepared to receive response fields beyond those currently returned by a given endpoint.

Functionality is never removed from a particular version of an endpoint, nor do field names or types change.

Compression

Gzip compression should be used to reduce the amount of data transferred. When using curl, it is done with the --compressed flag. In your code, make sure you’ve properly configured the HTTP library you’re using.

Parameters

For GET requests, most parameters are sent in the query string. Example:

$ curl -H "Authorization: Token $API_KEY" \
    --compressed https://api.idbus.com/v1/fares?date=2015-04-16&origin_id=12

When documented otherwise, some parameters are sent in the url path. Example where the id of an object is in the url — you must replace :id by the id of the object:

https://api.idbus.com/v1/fares/:id/book

For POST request, you must send the parameters as JSON, with the appropriate Content-Type: application/json header. Example:

$ curl -H "Authorization: Token $API_KEY" \
    --header "Content-Type: application/json" \
    --compressed \
    --data @- \
    https://api.idbus.com/v1/search <<JSON
      {
        "origin_id": 1,
        "destination_id": 17,
        "date": "2015-08-15",
        "passengers": [
          { "id": 1, "age": 30 },
          { "id": 2, "age": 30 },
          { "id": 3, "age": 1 }
        ]
      }
JSON

Times

Times are reprensented as ISO 8601 strings. For example 2015-04-16T19:00:00+02:00.

In the case of departure and arrival times, the time zone in which the time is represented is the time zone local to the stop from which the bus departs, or at which the bus arrives. For example, the arrival time of a bus that arrives in Paris at 7pm on the 4 April, 2015 local time will always be represented by 2015-04-16T19:00:00+02:00. And the arrival time of another bus that arrives at the very same moment in London will always be represented by 2015-04-16T18:00:00+01:00.

When a time is not associated to a stop, for example an updated_at attribute, it is represented in UTC.

Methods

Stops v1

GET /stops

Returns the list of all current bus stops. New stops may be added at any time, so you should retrieve this list regularly.

Stop

Name Type Description
id integer The unique id of the stop.
short_name string Short version of the name of the station. Use it when the space is limited.
long_name string Long version of the name of the station. Use it when you have enough space for extra precision.
time_zone string Time zone of the stop, in the tz database format. Departure and arrival times will be formatted in the stop’s time zone.
latitude float Geographic latitude of the stop, expressed in decimal degrees.
longitude float Geographic longitude of the stop, expressed in decimal degrees.
destinations_ids array Ids of the destination stops for which a fare exists with the current stop as the origin.

Example

$ curl -H "Authorization: Token $API_KEY" \
    --compressed https://api.idbus.com/v1/stops
{
  "stops": [
    {
      "id": 2,
      "short_name": "Paris CDG",
      "long_name": "Paris Aéroport Roissy-Charles-de-Gaulle",
      "time_zone": "Europe/Paris",
      "latitude": 49.009691,
      "longitude": 2.547925,
      "destinations_ids": [7, 12]
    },
    ...
  ]
}

Stops v2

GET /stops

Returns the list of all current bus stops. New stops may be added at any time, so you should retrieve this list regularly.

Stop

Name Type Description
id integer The unique id of the stop.
short_name string Short version of the name of the station. Use it when the space is limited.
short_name_de string (new in v2) Short version (German) of the name of the station. Use it when the space is limited.
short_name_en string (new in v2) Short version (English) of the name of the station. Use it when the space is limited.
short_name_fr string (new in v2) Short version (French) of the name of the station. Use it when the space is limited.
short_name_it string (new in v2) Short version (Italian) of the name of the station. Use it when the space is limited.
short_name_nl string (new in v2) Short version (Dutch) of the name of the station. Use it when the space is limited.
long_name string Long version of the name of the station. Use it when you have enough space for extra precision.
long_name_de string (new in v2) Long version (German) of the name of the station. Use it when you have enough space for extra precision.
long_name_en string (new in v2) Long version (English) of the name of the station. Use it when you have enough space for extra precision.
long_name_fr string (new in v2) Long version (French) of the name of the station. Use it when you have enough space for extra precision.
long_name_it string (new in v2) Long version (Italian) of the name of the station. Use it when you have enough space for extra precision.
long_name_nl string (new in v2) Long version (Dutch) of the name of the station. Use it when you have enough space for extra precision.
time_zone string Time zone of the stop, in the tz database format. Departure and arrival times will be formatted in the stop’s time zone.
latitude float Geographic latitude of the stop, expressed in decimal degrees.
longitude float Geographic longitude of the stop, expressed in decimal degrees.
destinations_ids array Ids of the destination stops for which a fare exists with the current stop as the origin.
is_meta_gare bool (new in v2) True if the stop is a meta gare (ex. ‘Paris Toutes Gares’) and false otherwise
address string (new in v2) The address of the stop
stops array (new in v2) (empty if is_meta_gare == false) an array of children stops

Example

$ curl -H "Authorization: Token $API_KEY" \
    --compressed https://api.idbus.com/v2/stops
{
  "stops": [
    {
      "id": 3,
      "_carrier_id": "GIA",
      "short_name": "Gérone",
      "short_name_fr": "Gérone",
      "short_name_de": "Girona",
      "short_name_en": "Girona",
      "short_name_it": "Girona",
      "short_name_nl": "Gerona",
      "long_name": "Arrêt OUIBUS Estació d'autobusos de Girona",
      "long_name_fr": "Arrêt OUIBUS Estació d'autobusos de Girona",
      "long_name_de": "Estació d'autobusos de Girona",
      "long_name_en": "Estació d'autobusos de Girona",
      "long_name_it": "Estació d'autobusos de Girona",
      "long_name_nl": "Estació d'autobusos de Girona",
      "time_zone": "Europe/Madrid",
      "latitude": "41.97901",
      "longitude": "2.817476",
      "destinations_ids": [
        13,
        14,
        16,
        18,
        137,
        29,
        134
      ],
      "is_meta_gare": false,
      "address": "Plaça Espanya 2, 17002 Girona, Espagne",
      "stops": []
    },
    {
      "id": 90,
      "_carrier_id": "PAR",
      "short_name": "Paris - Tous les arrêts",
      "short_name_fr": "Paris - Tous les arrêts",
      "short_name_de": "Paris - Alle Bahnhöfe",
      "short_name_en": "Paris - All stations",
      "short_name_it": "Parigi - Tutte le stazioni",
      "short_name_nl": "Parijs - alle stations",
      "long_name": "Paris - Tous les arrêts",
      "long_name_fr": "Paris - Tous les arrêts",
      "long_name_de": "Paris - Alle Bahnhöfe",
      "long_name_en": "Paris - All stations",
      "long_name_it": "Parigi - Tutte le stazioni",
      "long_name_nl": "Parijs - alle stations",
      "time_zone": "Europe/Paris",
      "latitude": null,
      "longitude": null,
      "destinations_ids": [
        9,
        10,
        11,
        12,
        15,
        16,
        17,
        18,
        19,
        20,
        21
      ],
      "is_meta_gare": true,
      "address": null,
      "stops": [
        {
          "id": 1,
          "_carrier_id": "XPB",
          "short_name": "Paris Bercy (centre ville)",
          "short_name_fr": "Paris Bercy (centre ville)",
          "short_name_de": "Paris Bercy (Zentrum)",
          "short_name_en": "Paris Bercy (city centre)",
          "short_name_it": "Paris Bercy (centro città)",
          "short_name_nl": "Paris Bercy (stadscentrum)",
          "long_name": "Arrêt OUIBUS Gare Paris Bercy",
          "long_name_fr": "Arrêt OUIBUS Gare Paris Bercy",
          "long_name_de": "Bahnhof Paris-Bercy",
          "long_name_en": "Paris - Bercy Station",
          "long_name_it": "Stazione Paris Bercy",
          "long_name_nl": "Station van Parijs-Bercy",
          "time_zone": "Europe/Paris",
          "latitude": "48.838424",
          "longitude": "2.382411",
          "destinations_ids": [
            9,
            10,
            11
          ],
          "is_meta_gare": false,
          "address": "48 bis Boulevard de Bercy 75012 Paris"
        },
        ...
      ]
    }
  ]
}

Fares

GET /fares

The fares method returns the list of all the standard adult fares, for all routes, for buses departing after the current time. If called with certain parameters, it can be narrowed down to a specific day and/or route.

This method is designed for building a cache of all the standard adult fares. Fares change over time so you should called this method regularly (for example, every hour) to update your cache.

However, if you are building a search website and want to call the API dynamically for each of your users’ searches, you must not use this method and must use the search method instead. The search method also allows you to get reduced fare (for babies, for example), which the fares method does not allow.

You must not try to guess the price of reduced fares based on the price of the standard adult fare, as the business rules for reduced fares might change over time. Using the search API is the only correct way to get the reduced fares.

Parameters

Name Type Description
origin_idoptional integer Filters the fares for journeys that have this specific origin.
destination_idoptional string Filters the fares for journeys that have this specific destination.
dateoptional string Filters the fares for journeys that depart at this date. Must be in the YYYY-mm-dd format. If start_date or end_date is specified, this parameter take precedence.
start_dateoptional string Filters the fares for journeys that depart at this date or later. Must be in the YYYY-mm-dd format.
end_dateoptional integer Filters the fares for journeys that depart at this date or earlier. Must be in the YYYY-mm-dd format.
currencies[]optional array Filters the fares with the given currencies. The syntax to send the ["EUR", "GBP"] array, for example, is currencies[]=EUR&currencies[]=GBP.
updated_afteroptional string Filters the fares that have been updated stricly after this time. Must be a UTC time in the YYYY-mm-ddTHH:MM:SS format. Use the maximum value of the updated_at property of the fares you already have in your cache as the value of this parameter, rather than a time based on your system’s clock.

Fare

Name Type Description
id integer The unique id of the fare.
updated_at string Time at which the fare was last updated.
origin_id integer Id of the origin stop of the journey.
destination_id string Id of the destination stop of the journey.
departure string Time at which the bus of the first leg of journey departs.
arrival string Time at which the bus of the last leg of the journey arrives.
available boolean If false, it means that the fare is not available for sale. You may either display the bus as full, or don’t show it at all.
price_cents integer The value of the price, in cents, to avoid floating point rounding errors.
price_currency string ISO 4217 currency code in which the price is expressed.
legs array Legs of the journey for which this fare applies.

Leg

Name Type Description
origin_id integer Id of the origin stop.
destination_id integer Id of the destination stop.
departure string Time at which the bus departs.
arrival string Time at which the bus arrives.
bus_number string Bus number.

Example

$ curl -H "Authorization: Token $API_KEY" \
    --compressed https://api.idbus.com/v1/fares?date=2015-05-12
{
  "fares": [
    {
      "id": 1,
      "udpated_at": "2015-05-08T16:45:00.715Z",
      "origin_id": 3,
      "destination_id": 5,
      "departure": "2015-05-12T16:45:00.000+02:00",
      "arrival": "2015-05-13T19:00:00.000+02:00",
      "price_cents": 2900,
      "price_currency": "EUR",
      "legs": [
        {
          "origin_id": 3,
          "destination_id": 4,
          "departure": "2015-05-12T16:45:00.000+02:00",
          "arrival": "2015-05-12T23:15:00.000+02:00",
          "bus_number": "2109"
        },
        {
          "origin_id": 4,
          "destination_id": 5,
          "departure": "2015-05-13T08:30:00.000+02:00",
          "arrival": "2015-05-13T19:00:00.000+02:00",
          "bus_number": "3501"
        }
      ]
    },
    ...
  ]
}
POST /search

The search method returns priced trips for a given origin, destination, date and set of passengers.

You should call this method dynamically if you have a search website and want to get the prices for each of your users’ requests.

Parameters

Name Type Description
origin_id integer Id of the origin stop.
destination_id integer Id of the destination stop.
date string Departure day. Must be in the YYYY-mm-dd format.
currencyoptional string Currency. Default is EUR, allowed currencies are EUR, GBP and CHF, but all fares might not be available in all the currencies.
passengers[]optional array Array of passengers. Default is one 35 years old adult with an id of 1.

Passenger parameter

Name Type Description
id integer or string Unique identifier of the passenger. Use it to match the passengers from the response with the ones in the request.
age integer Age, in years, of the passenger at the time of the journey.

Trip

Name Type Description
id string The unique id of the trip.
origin_id integer Id of the origin stop of the journey.
destination_id string Id of the destination stop of the journey.
departure string Time at which the bus of the first leg of journey departs.
arrival string Time at which the bus of the last leg of the journey arrives.
available boolean If false, it means that the fare is not available for sale. You may either display the bus as full, or don’t show it at all.
price_cents integer The value of the price, in cents, to avoid floating point rounding errors.
price_currency string ISO 4217 currency code in which the price is expressed. Currently, fares are either in euros (EUR), pounds (GBP) or Swiss franc (CHF).
legs array Legs of the journey for which this fare applies.
passengers array Passengers for which this fare applies.

Leg

Name Type Description
origin_id integer Id of the origin stop.
destination_id integer Id of the destination stop.
departure string Time at which the bus departs.
arrival string Time at which the bus arrives.
bus_number string Bus number.

Passenger

Name Type Description
id integer or string Unique identifier for the passenger, as it was provided in input.
price_cents integer The value of the price for this passenger, in cents. The sum of the prices of the passengers is equal to the price of the trip.
price_currency string ISO 4217 currency code in which the price is expressed.

Example

Search for Paris - Torino fares on August, 15th 2015 for 2 adults and a baby.

$ curl -H "Authorization: Token $API_KEY" \
    --header "Content-Type: application/json" \
    --compressed \
    --data @- \
    https://api.idbus.com/v1/search <<JSON
      {
        "origin_id": 1,
        "destination_id": 17,
        "date": "2015-08-15",
        "passengers": [
          { "id": 1, "age": 30 },
          { "id": 2, "age": 30 },
          { "id": 3, "age": 1 }
        ]
      }
JSON
{
  "trips": [
    {
      "id": "1071025594-1071025594-1071046610",
      "origin_id": 1,
      "destination_id": 17,
      "departure": "2015-08-15T16:45:00.000+02:00",
      "arrival": "2015-08-16T05:00:00.000+02:00",
      "available": true,
      "price_cents": 7250,
      "price_currency": "EUR",
      "legs": [
        {
          "origin_id": 1,
          "destination_id": 17,
          "departure": "2015-08-15T16:45:00.000+02:00",
          "arrival": "2015-08-16T05:00:00.000+02:00",
          "bus_number": "2109"
        }
      ],
      "passengers": [
        {
          "id": 1,
          "price_cents": 2900,
          "price_currency": "EUR"
        },
        {
          "id": 2,
          "price_cents": 2900,
          "price_currency": "EUR"
        },
        {
          "id": 3,
          "price_cents": 1450,
          "price_currency": "EUR"
        }
      ]
    }
  ]
}

Redirect to the OUIBUS website to book a fare

GET /fares/:outbound_fare_id/book
GET /fares/:outbound_fare_id/:inbound_fare_id/book
GET /search/:outbound_trip_id/book
GET /search/:outbound_trip_id/:inbound_trip_id/book

This describes links that end users should visit to be redirected to the OUIBUS website to book a specific fare. These links must not be used with an API key, they don’t return anything, they just set a Location HTTP header to a page on which end users will be redirected to.

Parameters

Name Type Description
:outbound_fare_id integer If using the first or second form, it is the unique identifier of the outbound fare of the one-way journey on which you want to end user to be redirected to.
:inbound_fare_id integer If using the second form, it is the unique identifier of the inbound fare of the round-trip journey on which you want to end user to be redirected to.
:outbound_trip_id integer If using the third or fourth form, it is the unique identifier of the outbound trip of the one-way journey on which you want to end user to be redirected to.
:inbound_trip_id integer If using the fourth form, it is the unique identifier of the inbound trip of the round-trip journey on which you want to end user to be redirected to.
affiliate_id integer Your affiliate id, which you can find on your account page.
error_url string A URL on which you want your user redirected to in case there is an error during the redirection.

Example

https://api.idbus.com/v1/fares/1/book?affiliate_id=5

If you use NetAffiliation with OUIBUS, you must pass the full URL in the redir parameter, url-encoded:

http://action.metaffiliation.com/trk.php?mclic=YOUR_MCLIC_ID&redir=https%3A%2F%2Fapi.idbus.com%2Fv1%2Ffares%2F1%2Fbook%3Faffiliate_id%3D5

Misc

GTFS file

The OUIBUS GTFS file which contains the full schedule is available for download without the need of an API key. It is updated several times a day. More info about GTFS can be found on the official GTFS website.

Revision History

August 18, 2015

August 10, 2015

July 21, 2015

June 15, 2015

June 10, 2015