BlaBlaCar Bus API FOR DEVELOPERS

Introduction

Overview

This document describes the official BlaBlaCar Bus API. We assume that you are already familiar with BlaBlaCar Bus 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 BlaBlaCar Bus 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 v3, and the endpoint is https://bus-api.blablacar.com. A request can be made with curl with the following command:

$ curl -H "Authorization: Token $API_KEY" \
    --compressed https://bus-api.blablacar.com/v3/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.

Request parameters

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

$ curl -H "Authorization: Token $API_KEY" \
    --compressed https://bus-api.blablacar.com/v3/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://bus-api.blablacar.com/v3/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://bus-api.blablacar.com/v3/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 /v1/stops

Returns the list of all current bus stops. New stops may be added at any time, so you should retrieve this list regularly (once a day at most, once a month at least).

Response

Response body is made of an array of Stop elements defined as below:

Name Type Description
id integer The unique id of the stop.
_carrier_id string [DEPRECATED] 3-letters code of the stop (internal reference)
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://bus-api.blablacar.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 /v2/stops

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

Response

Response body is made of an array of Stop elements defined as below:

Name Type Description
id integer The unique id of the stop.
_carrier_id string [DEPRECATED] 3-letters code of the stop (internal reference)
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://bus-api.blablacar.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 Blablabus Estació d'autobusos de Girona",
      "long_name_fr": "Arrêt Blablabus 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 Blablabus Gare Paris Bercy",
          "long_name_fr": "Arrêt Blablabus 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"
        },
        ...
      ]
    }
  ]
}

Stops v3

GET /v3/stops

== Stops v2

Fares v1

GET /v1/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 call this method regularly to update your cache (no more than every 2 hours).

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.

Request parameters

Name Type Description
origin_idoptional integer Filters the fares for journeys that have this specific origin.
destination_idoptional integer 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 string 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.

Response

Response body is made of an array of Fare elements defined as below:

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 integer 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 Array of Leg elements of the journey for which this fare applies.

Leg element

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.
one_luggage boolean [DEPRECATED] Indicate whether 1 or more luggage are permitted on the bus service.
service_name string [DEPRECATED] Name of bus legal entity.
service_type string [DEPRECATED] Transportation type, value is always BUS

Example

$ curl -H "Authorization: Token $API_KEY" \
    --compressed https://bus-api.blablacar.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"
        }
      ]
    },
    ...
  ]
}

Fares v2

GET /v2/fares

== Fares v1

Fares v3

GET /v3/fares

== Fares v2 == Fares v1

Search v1

POST /v1/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.

Request 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 Passenger element. Default is one 35 years old adult with an id of 1.
transfersoptional integer Number of allowed transfers for the travel. By default 0, returns only direct travels. If you want transfers, you must set this parameter to 1 at least.

Passenger element

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.

Response

Response body is made of an array of Trip elements defined as below:

Name Type Description
id string The unique id of the trip.
origin_id integer Id of the origin stop of the journey.
destination_id integer 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 Array of Leg elements of the journey for which this fare applies.
passengers array Array of Passenger elements for which this fare applies.

Leg element

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.
one_luggage boolean [DEPRECATED] Indicate whether 1 or more luggage are permitted on the bus service.
service_name string [DEPRECATED] Name of bus legal entity.
service_type string [DEPRECATED] Transportation type, value is always BUS

Passenger element

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.
fare_name string Name of the fare type, can be Adult, Child or Baby.
fare_description string Fare description.

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://bus-api.blablacar.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"
        }
      ]
    }
  ]
}

Search v2

POST /v2/search

== Search v1

Search v3

POST /v3/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.

Changelog

Promo prices support.

Request parameters

Same as previous versions

Response

Response body is made of an array of Trip elements defined as below:

Name Type Description
id string The unique id of the trip.
origin_id integer Id of the origin stop of the journey.
destination_id integer 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 and promo price is expressed. Currently, fares are either in euros (EUR), pounds (GBP) or Swiss franc (CHF).
price_promo_cents integer (new in v3) The value of the promo price, in cents, to avoid floating point rounding errors.
price_promo_currency string [DEPRECATED] ISO 4217 currency code in which the promo price is expressed. Currently, fares are either in euros (EUR), pounds (GBP) or Swiss franc (CHF).
is_promo boolean (new in v3) Is a promo price available.
is_refundable boolean (new in v3) Is the price refundable.
legs array Array of Leg elements of the journey for which this fare applies.
passengers array Array of Passenger elements for which this fare applies.

Leg element

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 element

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.
price_promo_currency string [DEPRECATED] ISO 4217 currency code in which the promo price is expressed. Currently, fares are either in euros (EUR), pounds (GBP) or Swiss franc (CHF).
is_promo boolean (new in v3) Is this price a promo price.
fare_name string Name of the fare type, can be Adult, Child or Baby.
fare_description string Fare description.

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://bus-api.blablacar.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_promo_cents": 6000,
      "is_promo": true,
      "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 BlaBlaCar website to book a fare

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

This describes links that end users should visit to be redirected to the BlaBlaCar Bus 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.
language string The language in which you want the user to view the BlaBlaCar Bus site. Possible values are en-GB, nl-NL, nl-BE, de-DE, es-ES, fr-FR, it-IT.

Example

https://bus-api.blablacar.com/v3/fares/1/book?affiliate_id=5

The language used for the redirection is that of the browser or via API it is necessary to specify Accept-Language (in request’s headers). Possible values are en-GB, nl-NL, nl-BE, de-DE, es-ES, fr-FR, it-IT.
If the language of your browser is spanish, you will be redirect to spanish sales channel es-ES.

Misc

Meta station mechanism

A BlaBlaCar Bus meta station (also called agglomeration) is a parent station, i.e. a set of several related children stations. Example: Paris City Centre - Bercy Seine and Paris - La Défense are children stations of the Paris - Tous les arrêts parent station.

A station is a meta station if the is_meta_gare parameter (boolean) is set to true in the GET /v2/stops or GET /v3/stops API call response. If so, related children stations will be listed in the stops array of this response.

To ease your integration and reduce useless traffic on the API, we recommend calling the GET /fares and POST /search endpoints based on meta stations rather than calling every children stations

Cache mechanism

The BlaBlaCar Bus API works with a cache mechanism to provide the best response time possible. The data is updated as below:

Stops

Stops are updated every hour. However as stops data do not change very often, we recommend to call the /stops method about twice per month (once per day at most, once per month at least)

Prices for the next 10 days (from Today to Today+10days)

Prices for the next 10 days are updated every 2 hours. Therefore, concerning the prices for the next 10 days, it is unecessary to refresh your cache more than every 2 hours.

Prices for the next 100 days (from Today+10days to Today+100days)

Prices for the next 100 days are updated every 24 hours. Therefore, concerning the prices for the next 100 days, it is unecessary to refresh your cache more than every 24 hours. Besides, the BlaBlaCar Bus API does not offer any price beyond 100 days in the future.

GTFS file

The BlaBlaCar Bus 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

June 20, 2021

October 20, 2020

September 16, 2019

September 21, 2017

August 18, 2015

August 10, 2015

July 21, 2015

June 15, 2015

June 10, 2015