NAV Navbar
Logo
cURL

Introduction

alt text

You can use our API to access Distribusion content and book bus rides. We have put a lot of thought into making it as easy as possible to integrate with us. Have fun and share your feedback with us!

When integrating and testing our API, please use the following URL:

https://api-demo.distribusion.com/retailers/v4

Deprecated API

Retailer API v2

Getting Started

When performing a booking through Distribusion API, there are multiple steps that are required. This section is dedicated to describe the standard flow, necessary for:

alt text

Integration Workflow

  1. (1-4 weeks) Integrate our API, using this documentation. If you have any questions, do not hesitate to write us at partner@distribusion.com

  2. (Up to 1 week) In order to get access to our production environment, we will first test the integration logic (from search to booking, and if implemented, cancellations) and the data mapping logic (stations associations to cities and airports). For this, we will require access to your demo environment, with all the necessary information to perform bookings (test payment credentials, etc).

  3. (Up to 2 week after launch) Once this is validated, we will provide you the production API key for you to start mapping stations on the production environment. A few weeks after your launch, we will have our customer experience team going through your integration and provide a full report to improve data mapping and overall L/B ratio.

  4. Later on, our team will get in touch with you in order to support your processes related to L/B ratio optimisation and overall customer journey: from searching to booking and after sales services.

Station Coding

Distribusion aims to standardize the station codes across the bus industry, the same way IATA did in the flight industry. Our station codes are designed to represent specific locations using a set of 8 capital letters. The construction of such code follow a simple logic:

Example

GB(Great Britain) + LON(London) + VSA(Victoria station) = GBLONVSA

Importing Master Data

The first step in the booking process, is collecting the stations and marketing carriers available through our API. To do so, we provide the #stations and #marketing_carriers endpoints. To retrieve station codes, simply send a GET request to our #stations endpoint, which will send you a list of the stations, with station codes and additional information concerning the stations (address, coordinates, associated city, etc). The #marketing_carriers endpoint provides you with additional information related to a specific marketing carrier; such as logos, contact details, cancellation policy, as well as the terms and conditions.

Currently our content can be fetch in English, French, Italian, Spanish, Dutch, Swedish, Bulgarian and German, with the following locale values: en, fr, it, es, nl, sv, bg and de.

Map Stations to Cities and Areas

{
    "id": "ESBCNBFT",
    "type": "stations",
    "attributes": {
        "code": "ESBCNBFT",
        "name": "Barcelona Airport T1",
        "description": "The stop is located in front of Terminal 1. ",
        "street_and_number": null,
        "zip_code": null,
        "longitude": 2.084151,
        "latitude": 41.298291,
        "time_zone": "Europe/Madrid"
    },
    "relationships": {
        "city": {
            "data": {
                "id": "ESBCN",
                "type": "cities"
            }
        },
        "area": {
            "data": {
                "id": "ESBCNBA",
                "type": "areas"
            }
        }
    }
},
{
    "id": "ESBCNBFU",
    "type": "stations",
    "attributes": {
        "code": "ESBCNBFU",
        "name": "Barcelona Airport T2",
        "description": "The stop is located in front of Terminal 2. ",
        "street_and_number": "El Prat de Llobregat, Barcelona",
        "zip_code": "08820",
        "longitude": 2.083273,
        "latitude": 41.297614,
        "time_zone": "Europe/Madrid"
    },
    "relationships": {
        "city": {
            "data": {
                "id": "ESBCN",
                "type": "cities"
            }
        },
        "area": {
            "data": {
                "id": "ESBCNBA",
                "type": "areas"
            }
        }
    }
}

Our API maps stations to cities, allowing you to easily groupe stations together when they belong to the same city. This is to facilite city to city search. We also recently introduced the notion of areas. An area is smaller than a city, represent multiple stations, and can only be attached to one city.

In the example bellow, Barcelona Airport is mapped with “Barcelona Airport T1” and “Barcelona Airport T2” stations, while the area and the stations are all mapped to Barcelona city. Bellow is an extract of our #stations endpoint response:

Code description:

For example, while searching from Barcelona Airport to Barcelona City, you could perform the following request:

https://api-demo.distribusion.com/retailers/v4/connections/find?departure_stations[]=ESBCNBFT&departure_stations[]=ESBCNBFU&arrival_stations[]=ESBCNNOR&arrival_stations[]=ESBCNZOB&arrival_stations[]=ESBCNEDA&arrival_stations[]=ESBCNPCA&arrival_stations[]=ESBCNSUR&arrival_stations[]=ESBCNPES&arrival_stations[]=ESBCNGVU&arrival_stations[]=ESBCNPDU&arrival_stations[]=ESBCNBFT&arrival_stations[]=ESBCNBFU&departure_date=2019-03-29&pax=1&currency=EUR&locale=en

Find Connections

After retrieving station codes, you can now start searching for connections by sending us GET requests to connections#find. We do not provide pairs of stations in order to allow our engine to learn from the consumers demand. By doing so, if a specific ride is highly requested but currently unavailable, you can be assured that it will be soon delivered through our API.

Passenger types

We also thrive to standardise passenger (ticket) types across multiple carriers. While booking through Distribusion API, you can choose the use the specific passenger types of the operator, or use Distribusion own standardise definition of an infant, child and adult.

Fare Classes

Operators are often providing different service class and features to their consumers. You will find the possibility to select each fare based on the operator offer. Fares classes are covering a large amount of features, such as 1st/2nd class, extra leg seats, drinks, cancellation policies, validity period, etc.

Confirm Price and Availability

As connections#find provides the cheapest adult price, it is some time necessary to confirm the price of specific passenger types by calling connections#vacancy. This call is also recommended prior to performing a booking, in order to ensure the prices and availability are still up to date.

Create an Order or a Booking

After gathering information on a specific connection and the passenger information, you can now send a booking request towards Distribusion’s API on bookings#create. You can also perform an order, and later retrieve it status by calling our orders#create endpoint. The main difference between a booking and an order is the workflow. A booking is synchronous, while an order is asynchronous. In case any information is missing, the API will recognise it and inform you accordingly.

Note: we currently support EUR, USD, GBP SEK, MYR, PLN and CHF currencies. More can be enabled on demand.

Manage your Bookings

Once you start making bookings, you will certainly want to monitor them and sometime, if need be, cancel them. For this, we created a new feature, allowing you to retrieve a full list of your bookings: bookings#index. Once you have this list, you can call bookings#show for more details on a specific booking, or call cancellations#conditions and cancellations#create to cancel a booking.

Postman

Here’s a collection of sample queries in Postman that’ll help you get up to speed with our API faster.

Run in Postman

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl  'https://api.distribusion.com/retailers/v4/#' \
      --header 'Accept: application/vnd.api+json' \
      --header 'Api-Key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI'

Make sure to replace H4gtqUn04qDh7mmZpFJYmmcW7JVw7hMIaCUcdWhZ’ with your API key.

Distribusion uses API keys to allow access to the API content and perform bookings. You can register a new Distribusion API key by contacting us at partner@distribusion.com.

Distribusion expects for the API key to be included in all API requests to the server in a header that looks like the following:

Api-Key:AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI

Connections

Find

curl -g -X GET \
  'https://api-demo.distribusion.com/retailers/v4/connections/find?departure_stations[]=GBXVHPET&arrival_stations[]=GBCBGCAM&arrival_stations[]=GBCBGCCE&arrival_stations[]=GBCBGCMA&arrival_stations[]=GBCBGCPR&arrival_stations[]=GBCBGTPR&arrival_stations[]=GBCBGTRU&departure_date=2019-12-15&pax=1&locale=en&currency=EUR' \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json'

The above command returns JSON structured like this:

 {
    "meta": {
        "locale": "en",
        "currency": "EUR"
    },
    "jsonapi": {
        "version": "1.0"
    },
    "included": [
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T02:25-2019-12-15T03:15-0"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T02:25-2019-12-15T03:15-0",
            "attributes": {
                "index": 0,
                "departure_time": "2019-12-15T02:25",
                "arrival_time": "2019-12-15T03:15"
            }
        },
        {
            "type": "marketing_carriers",
            "relationships": {
                "passenger_types": {
                    "data": [
                        {
                            "type": "passenger_types",
                            "id": "PNOS"
                        }
                    ]
                },
                "fare_classes": {
                    "data": [
                        {
                            "type": "fare_classes",
                            "id": "FARE-1"
                        },
                        {
                            "type": "fare_classes",
                            "id": "FARE-2"
                        },
                        {
                            "type": "fare_classes",
                            "id": "FARE-3"
                        }
                    ]
                },
                "extra_types": {
                    "data": []
                }
            },
            "id": "NEXP",
            "attributes": {
                "trade_name": "National Express",
                "legal_name": "National Express Limited",
                "code": "NEXP",
                "booking_fee": 100
            }
        },
        {
            "type": "operating_carriers",
            "id": "NEXP",
            "attributes": {
                "trade_name": "National Express",
                "legal_name": "National Express Limited",
                "code": "NEXP"
            }
        },
        {
            "type": "passenger_types",
            "id": "PNOS",
            "attributes": {
                "name": "Adult",
                "min_age": 0,
                "max_age": 99,
                "description": "",
                "code": "PNOS"
            }
        },
        {
            "type": "stations",
            "relationships": {
                "city": {
                    "data": {
                        "type": "cities",
                        "id": "GBXVH"
                    }
                },
                "area": {
                    "data": null
                }
            },
            "id": "GBXVHPET",
            "attributes": {
                "zip_code": "PE1 1NL",
                "time_zone": "Europe/London",
                "street_and_number": "Westgate",
                "name": "Peterborough",
                "longitude": -0.24632,
                "latitude": 52.57511,
                "description": "The bus stop is located near Peterborough Station.",
                "code": "GBXVHPET"
            }
        },
        {
            "type": "cities",
            "id": "GBXVH",
            "attributes": {
                "name": "Peterborough",
                "code": "GBXVH"
            }
        },
        {
            "type": "stations",
            "relationships": {
                "city": {
                    "data": {
                        "type": "cities",
                        "id": "GBCBG"
                    }
                },
                "area": {
                    "data": null
                }
            },
            "id": "GBCBGCCE",
            "attributes": {
                "zip_code": "CB1 1JE",
                "time_zone": "Europe/London",
                "street_and_number": "Parkside 32",
                "name": "Cambridge City Centre",
                "longitude": 0.12938269999995,
                "latitude": 52.2032877,
                "description": "The bus stop is located in front of Parkers Piece park. For National Express passengers, from 18/03/2019 - 22/03/2019 from 9pm - 6am the stop will be East Rd, Fire Station; 05/05/2019, the bus will stop at Trumpington Park & Ride, Hauxton Rd.",
                "code": "GBCBGCCE"
            }
        },
        {
            "type": "cities",
            "id": "GBCBG",
            "attributes": {
                "name": "Cambridge",
                "code": "GBCBG"
            }
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T02:25-2019-12-15T03:15-0"
        },
        {
            "type": "vehicle_types",
            "id": "BUS",
            "attributes": {
                "code": "BUS"
            }
        },
        {
            "type": "fare_classes",
            "relationships": {
                "fare_features": {
                    "data": [
                        {
                            "type": "fare_features",
                            "id": "ACON"
                        },
                        {
                            "type": "fare_features",
                            "id": "TOIL"
                        },
                        {
                            "type": "fare_features",
                            "id": "ALRO"
                        },
                        {
                            "type": "fare_features",
                            "id": "NREF"
                        },
                        {
                            "type": "fare_features",
                            "id": "AMEN"
                        },
                        {
                            "type": "fare_features",
                            "id": "WIFI"
                        },
                        {
                            "type": "fare_features",
                            "id": "MSYS"
                        },
                        {
                            "type": "fare_features",
                            "id": "UCHA"
                        },
                        {
                            "type": "fare_features",
                            "id": "AAFO"
                        },
                        {
                            "type": "fare_features",
                            "id": "BLUG"
                        },
                        {
                            "type": "fare_features",
                            "id": "AAFR"
                        }
                    ]
                }
            },
            "id": "FARE-1",
            "attributes": {
                "name": "Standard",
                "journey_type": "single",
                "iata_category": null,
                "code": "FARE-1"
            }
        },
        {
            "type": "fare_features",
            "id": "ACON",
            "attributes": {
                "name": "Air Conditioning",
                "description": "The bus has a cooling ventilation.",
                "code": "ACON"
            }
        },
        {
            "type": "fare_features",
            "id": "TOIL",
            "attributes": {
                "name": "Toilet",
                "description": "A toilet is available on board.",
                "code": "TOIL"
            }
        },
        {
            "type": "fare_features",
            "id": "ALRO",
            "attributes": {
                "name": "Additional Leg Room",
                "description": "The seat has additional leg space.",
                "code": "ALRO"
            }
        },
        {
            "type": "fare_features",
            "id": "NREF",
            "attributes": {
                "name": "Non-refundable ",
                "description": "The ticket cannot be refunded.",
                "code": "NREF"
            }
        },
        {
            "type": "fare_features",
            "id": "AMEN",
            "attributes": {
                "name": "Amendable",
                "description": "The ticket is amendable. Please contact the carrier for further steps. A £5 amendment fee is applicable. ",
                "code": "AMEN"
            }
        },
        {
            "type": "fare_features",
            "id": "WIFI",
            "attributes": {
                "name": "Wifi",
                "description": "Free wifi is available on board.",
                "code": "WIFI"
            }
        },
        {
            "type": "fare_features",
            "id": "MSYS",
            "attributes": {
                "name": "Media System",
                "description": "Free-of-charge infotainment system VUER. Travellers can download the VUER app, which allows them to stream films and TV shows on their own phone or tablet.",
                "code": "MSYS"
            }
        },
        {
            "type": "fare_features",
            "id": "UCHA",
            "attributes": {
                "name": "USB charger",
                "description": "USB plug is available at each seat. ",
                "code": "UCHA"
            }
        },
        {
            "type": "fare_features",
            "id": "AAFO",
            "attributes": {
                "name": "Accessible area for bicycles",
                "description": "Bicycles are allowed on board as long as they are designed to fold in half by means of a special link in the main frame and are carried in a proper protective carrying case. A passenger has to pay an extra fee for a bike.",
                "code": "AAFO"
            }
        },
        {
            "type": "fare_features",
            "id": "BLUG",
            "attributes": {
                "name": "Bulky Luggage",
                "description": "Folding pushchairs/buggies will be carried free of charge in the hold, in addition to the standard luggage allowance. Except this National Express will accept bulky luggage for an extra charge.",
                "code": "BLUG"
            }
        },
        {
            "type": "fare_features",
            "id": "AAFR",
            "attributes": {
                "name": "Accessible area for wheelchairs",
                "description": "Fully collapsible wheelchairs and fully collapsible pushchairs may be stowed free of charge. Passenger have to contact bus operator 36 hours before the departure.",
                "code": "AAFR"
            }
        },
        {
            "type": "fare_classes",
            "relationships": {
                "fare_features": {
                    "data": [
                        {
                            "type": "fare_features",
                            "id": "ACON"
                        },
                        {
                            "type": "fare_features",
                            "id": "TOIL"
                        },
                        {
                            "type": "fare_features",
                            "id": "ALRO"
                        },
                        {
                            "type": "fare_features",
                            "id": "NAME"
                        },
                        {
                            "type": "fare_features",
                            "id": "NREF"
                        },
                        {
                            "type": "fare_features",
                            "id": "WIFI"
                        },
                        {
                            "type": "fare_features",
                            "id": "MSYS"
                        },
                        {
                            "type": "fare_features",
                            "id": "UCHA"
                        },
                        {
                            "type": "fare_features",
                            "id": "AAFO"
                        },
                        {
                            "type": "fare_features",
                            "id": "BLUG"
                        },
                        {
                            "type": "fare_features",
                            "id": "AAFR"
                        }
                    ]
                }
            },
            "id": "FARE-2",
            "attributes": {
                "name": "Restricted",
                "journey_type": "single",
                "iata_category": null,
                "code": "FARE-2"
            }
        },
        {
            "type": "fare_features",
            "id": "NAME",
            "attributes": {
                "name": "Non-amendable",
                "description": "The ticket is not amendable.",
                "code": "NAME"
            }
        },
        {
            "type": "fare_classes",
            "relationships": {
                "fare_features": {
                    "data": [
                        {
                            "type": "fare_features",
                            "id": "ACON"
                        },
                        {
                            "type": "fare_features",
                            "id": "TOIL"
                        },
                        {
                            "type": "fare_features",
                            "id": "ALRO"
                        },
                        {
                            "type": "fare_features",
                            "id": "REFU"
                        },
                        {
                            "type": "fare_features",
                            "id": "AMEN"
                        },
                        {
                            "type": "fare_features",
                            "id": "WIFI"
                        },
                        {
                            "type": "fare_features",
                            "id": "MSYS"
                        },
                        {
                            "type": "fare_features",
                            "id": "UCHA"
                        },
                        {
                            "type": "fare_features",
                            "id": "AAFO"
                        },
                        {
                            "type": "fare_features",
                            "id": "BLUG"
                        },
                        {
                            "type": "fare_features",
                            "id": "AAFR"
                        }
                    ]
                }
            },
            "id": "FARE-3",
            "attributes": {
                "name": "Fully Flexible",
                "journey_type": "single",
                "iata_category": null,
                "code": "FARE-3"
            }
        },
        {
            "type": "fare_features",
            "id": "REFU",
            "attributes": {
                "name": "Refundable",
                "description": "The ticket is refundable and can be cancelled no less than 72 hours in advance of travel. Please contact the carrier for further steps. ",
                "code": "REFU"
            }
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15-0"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15-0",
            "attributes": {
                "index": 0,
                "departure_time": "2019-12-15T07:15",
                "arrival_time": "2019-12-15T08:25"
            }
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15-1"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGTPR"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15-1",
            "attributes": {
                "index": 1,
                "departure_time": "2019-12-15T09:05",
                "arrival_time": "2019-12-15T09:15"
            }
        },
        {
            "type": "stations",
            "relationships": {
                "city": {
                    "data": {
                        "type": "cities",
                        "id": "GBCBG"
                    }
                },
                "area": {
                    "data": null
                }
            },
            "id": "GBCBGTPR",
            "attributes": {
                "zip_code": "CB2 9FT",
                "time_zone": "Europe/London",
                "street_and_number": "Hauxton Rd",
                "name": "Cambridge Trumpington P+R",
                "longitude": 0.10806,
                "latitude": 52.16772,
                "description": "The bus stop is inside Trumpington Park & Ride. From 43 Hauxton Rd, follow the sign \"park & ride\" to reach the parking lot. There is bus lane and bus sign.",
                "code": "GBCBGTPR"
            }
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15-0"
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15-1"
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:15-2019-12-15T08:25-0"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:15-2019-12-15T08:25-0",
            "attributes": {
                "index": 0,
                "departure_time": "2019-12-15T07:15",
                "arrival_time": "2019-12-15T08:25"
            }
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:15-2019-12-15T08:25-0"
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T20:30-2019-12-15T21:20-0"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T20:30-2019-12-15T21:20-0",
            "attributes": {
                "index": 0,
                "departure_time": "2019-12-15T20:30",
                "arrival_time": "2019-12-15T21:20"
            }
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T20:30-2019-12-15T21:20-0"
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:00-2019-12-15T08:10-0"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:00-2019-12-15T08:10-0",
            "attributes": {
                "index": 0,
                "departure_time": "2019-12-15T07:00",
                "arrival_time": "2019-12-15T08:10"
            }
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:00-2019-12-15T08:10-0"
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T09:20-2019-12-15T10:15-0"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T09:20-2019-12-15T10:15-0",
            "attributes": {
                "index": 0,
                "departure_time": "2019-12-15T09:20",
                "arrival_time": "2019-12-15T10:15"
            }
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-12-15T09:20-2019-12-15T10:15-0"
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30-0"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30-0",
            "attributes": {
                "index": 0,
                "departure_time": "2019-12-15T09:20",
                "arrival_time": "2019-12-15T10:15"
            }
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30-1"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGTPR"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30-1",
            "attributes": {
                "index": 1,
                "departure_time": "2019-12-15T11:20",
                "arrival_time": "2019-12-15T11:30"
            }
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30-0"
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30-1"
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20-0"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20-0",
            "attributes": {
                "index": 0,
                "departure_time": "2019-12-15T02:25",
                "arrival_time": "2019-12-15T03:15"
            }
        },
        {
            "type": "segments",
            "relationships": {
                "vehicle": {
                    "data": {
                        "type": "vehicles",
                        "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20-1"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "type": "operating_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGTPR"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20-1",
            "attributes": {
                "index": 1,
                "departure_time": "2019-12-15T04:05",
                "arrival_time": "2019-12-15T04:20"
            }
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20-0"
        },
        {
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "type": "vehicle_types",
                        "id": "BUS"
                    }
                }
            },
            "id": "BUS-NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20-1"
        }
    ],
    "data": [
        {
            "type": "connections",
            "relationships": {
                "segments": {
                    "data": [
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T02:25-2019-12-15T03:15-0"
                        }
                    ]
                },
                "marketing_carrier": {
                    "data": {
                        "type": "marketing_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T02:25-2019-12-15T03:15",
            "attributes": {
                "duration": 3000,
                "departure_time": "2019-12-15T02:25",
                "cheapest_total_adult_price": 998,
                "booked_out": false,
                "arrival_time": "2019-12-15T03:15"
            }
        },
        {
            "type": "connections",
            "relationships": {
                "segments": {
                    "data": [
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15-0"
                        },
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15-1"
                        }
                    ]
                },
                "marketing_carrier": {
                    "data": {
                        "type": "marketing_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGTPR"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15",
            "attributes": {
                "duration": 7200,
                "departure_time": "2019-12-15T07:15",
                "cheapest_total_adult_price": 1206,
                "booked_out": false,
                "arrival_time": "2019-12-15T09:15"
            }
        },
        {
            "type": "connections",
            "relationships": {
                "segments": {
                    "data": [
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:15-2019-12-15T08:25-0"
                        }
                    ]
                },
                "marketing_carrier": {
                    "data": {
                        "type": "marketing_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:15-2019-12-15T08:25",
            "attributes": {
                "duration": 4200,
                "departure_time": "2019-12-15T07:15",
                "cheapest_total_adult_price": 987,
                "booked_out": false,
                "arrival_time": "2019-12-15T08:25"
            }
        },
        {
            "type": "connections",
            "relationships": {
                "segments": {
                    "data": [
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T20:30-2019-12-15T21:20-0"
                        }
                    ]
                },
                "marketing_carrier": {
                    "data": {
                        "type": "marketing_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T20:30-2019-12-15T21:20",
            "attributes": {
                "duration": 3000,
                "departure_time": "2019-12-15T20:30",
                "cheapest_total_adult_price": 987,
                "booked_out": false,
                "arrival_time": "2019-12-15T21:20"
            }
        },
        {
            "type": "connections",
            "relationships": {
                "segments": {
                    "data": [
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:00-2019-12-15T08:10-0"
                        }
                    ]
                },
                "marketing_carrier": {
                    "data": {
                        "type": "marketing_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T07:00-2019-12-15T08:10",
            "attributes": {
                "duration": 4200,
                "departure_time": "2019-12-15T07:00",
                "cheapest_total_adult_price": 987,
                "booked_out": false,
                "arrival_time": "2019-12-15T08:10"
            }
        },
        {
            "type": "connections",
            "relationships": {
                "segments": {
                    "data": [
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T09:20-2019-12-15T10:15-0"
                        }
                    ]
                },
                "marketing_carrier": {
                    "data": {
                        "type": "marketing_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGCCE"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-12-15T09:20-2019-12-15T10:15",
            "attributes": {
                "duration": 3300,
                "departure_time": "2019-12-15T09:20",
                "cheapest_total_adult_price": 998,
                "booked_out": false,
                "arrival_time": "2019-12-15T10:15"
            }
        },
        {
            "type": "connections",
            "relationships": {
                "segments": {
                    "data": [
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30-0"
                        },
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30-1"
                        }
                    ]
                },
                "marketing_carrier": {
                    "data": {
                        "type": "marketing_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGTPR"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T09:20-2019-12-15T11:30",
            "attributes": {
                "duration": 7800,
                "departure_time": "2019-12-15T09:20",
                "cheapest_total_adult_price": 1217,
                "booked_out": false,
                "arrival_time": "2019-12-15T11:30"
            }
        },
        {
            "type": "connections",
            "relationships": {
                "segments": {
                    "data": [
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20-0"
                        },
                        {
                            "type": "segments",
                            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20-1"
                        }
                    ]
                },
                "marketing_carrier": {
                    "data": {
                        "type": "marketing_carriers",
                        "id": "NEXP"
                    }
                },
                "departure_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBXVHPET"
                    }
                },
                "arrival_station": {
                    "data": {
                        "type": "stations",
                        "id": "GBCBGTPR"
                    }
                }
            },
            "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T02:25-2019-12-15T04:20",
            "attributes": {
                "duration": 6900,
                "departure_time": "2019-12-15T02:25",
                "cheapest_total_adult_price": 1217,
                "booked_out": false,
                "arrival_time": "2019-12-15T04:20"
            }
        }
    ]
 }

The endpoint searches for and delivers all the connections matching your query. The delivered set of objects will have all the necessary data for displaying on the search results page.

On our side we parallelize the outbound requests to the operating carrier integration systems to include as many connections as we’re able to get from marketing carriers (excluding those which couldn’t respond in time).

You can also add two optional parameters in the header:

HTTP Request

GET https://api.distribusion.com/retailers/v4/connections/find

Query Parameters

Parameter Mandatory Description
departure_stations[] true 8- or 9-letter alphanumeric uppercase code, available codes can be obtained from GET /stations.
arrival_stations[] true 8- or 9-letter alphanumeric uppercase code, available codes can be obtained from GET /stations.
departure_date true Departure date in ISO 8601 format.
pax true Number of passengers - Integer in a range of 1..9.
locale true 2-letter alphanumeric lowercase code, according to ISO 639-1 standard .
currency true 3-letter alphanumeric uppercase code, according to ISO 4217 standard.
departure_start_time false String, HH:MM:SS, defaults to 00:00:00
departure_end_time false String, HH:MM:SS, defaults to 23:59:59

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.002 Departure stations are invalid or missing
400.101.003 Arrival stations are invalid or missing
400.101.014 Locale is invalid or missing
400.101.015 Currency is invalid or missing
400.200.001 API key is invalid or missing
400.501.000 Not implemented at Distribusion on connections#find
400.800.000 Not Found
500.100.000 Service Unavailable
600.000.000 Marketing Carrier remote system unavailable
600.100.000 Marketing Carrier remote system time-out
600.400.000 Marketing Carrier remote request invalid
600.900.000 Response received from a remote server technically cannot be processed
600.901.000 Response from remote server logically cannot be processed (is invalid)

Vacancy

curl -g -X GET \
  'https://api-demo.distribusion.com/retailers/v4/connections/vacancy?marketing_carrier=NEXP&departure_station=GBXVHPET&arrival_station=GBCBGTPR&departure_time=2019-12-15T07:15&arrival_time=2019-12-15T09:15&currency=EUR&passengers[][pax]=2&passengers[][type]=PNOS&fare_class=FARE-1' \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json'

The above command returns JSON structured like this:

{
    "data": {
        "id": "NEXP-GBXVHPET-GBCBGTPR-2019-12-15T07:15-2019-12-15T09:15",
        "type": "vacancies",
        "attributes": {
            "vacant": true,
            "total_price": 2303
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "currency": "EUR"
    }
}

This endpoint checks the availability and prices for the specific number and type of passengers for the selected trip. The trip is defined as a ride from one station to another at a particular day and time.

In parallel, we send the outbound requests to the operating carrier integration systems to retrieve the latest prices and vacant seats information.

HTTP Request

GET api.distribusion.com/retailers/v4/connections/vacancy

URL Parameters

Parameter Mandatory Description
marketing_carrier true 4-letter alphanumeric uppercase code.
departure_station true 8 or 9-letter alphanumeric uppercase code.
arrival_station true 8 or 9-letter alphanumeric uppercase code.
departure_time true Departure time in ISO 8601 format without timezone yyyy-mm-ddThh:mm.
arrival_time true Arrival time in ISO 8601 format without timezone yyyy-mm-ddThh:mm.
currency true 3-letter alphanumeric uppercase code, according to ISO 4217 standard.
discount_code false Code consisting of minimum 3 alphanumeric characters.
fare_class false Code consisting of 6-7 alphanumerical characters.
passengers true Array
_pax true Number of passengers for a specific passenger type
_type true Passenger type. 4-letter alphanumeric uppercase code, available codes can be obtained from GET /marketing_carriers.
extras false Array
_quantity true Integer in a range of 1..999.
_type true Extra type. 4-letter alphanumeric uppercase code, available codes can be obtained from GET /marketing_carriers.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.004 Departure station is invalid or missing
400.101.005 Arrival station is invalid or missing
400.101.009 PAX is invalid or missing
400.101.014 Locale is invalid or missing
400.101.015 Currency is invalid or missing
400.101.044 Departure date is in the past
400.101.049 Departure time must be before arrival time
400.101.052 Discount code is invalid or missing
400.102.040 Unknown marketing carrier
400.200.001 API key is invalid or missing
400.501.002 Not implemented at Distribusion on connections#vacancy
400.800.000 Not Found
400.800.040 Marketing carrier not found
429.000.000 Too Many Requests
500.100.000 Service Unavailable
600.000.000 Marketing Carrier remote system unavailable
600.100.000 Marketing Carrier remote system time-out
600.400.000 Marketing Carrier remote request invalid
600.500.000 Marketing Carrier remote connection unknown error
600.600.000 Marketing Carrier remote vacancy unknown error
600.900.000 Response received from a remote server technically cannot be processed
600.901.000 Response from remote server logically cannot be processed (is invalid)
600.703.026 Booking price unknown

Bookings

Create Orders

curl -X POST \
  https://api-demo.distribusion.com/retailers/v4/orders/create \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' \
  -d '{
       "marketing_carrier": "NEXP",
       "departure_station": "GBXVHPET",
       "arrival_station": "GBCBGCCE",
       "departure_time": "2019-08-15T09:15",
       "arrival_time": "2019-08-15T10:15",
       "retailer_partner_number": "{number}",
       "title": "mr",
       "first_name": "Balibalo",
       "last_name": "Bateau",  
       "email": "quentin@mail.com",
       "phone": "4915237601929",
       "city": "Berlin",
       "zip_code": "10123",
       "street_and_number": "Berlinstr. 23",
       "execute_payment": false,
       "payment_method": "demand_note",
       "total_price": 2020,
       "pax": 2,
       "terms_accepted": true,
       "locale": "en",
       "currency": "EUR",
       "send_customer_email": false,
       "fare_class": "FARE-1",
       "passengers":[
          { 
            "first_name": "Charlotte",
            "last_name": "Bateau",
            "type": "PADV"
          },
          { 
            "first_name": "Paul",
            "last_name": "Bateau",
            "type": "PADV"
          }
        ]
    }'

The above command returns JSON structured like this:

{
    "data": {
        "id": "NEXP-43927b28-ed74-4cf1-b454-b7b687a2db95",
        "type": "orders",
        "attributes": {
            "state": "created",
            "created_at": "2019-03-18T16:07"
        }
    },
    "jsonapi": {
        "version": "1.0"
    }
}

Use this endpoint to conduct an order. Orders created in this way are not a booking per se, but a confirmation that your booking have been successfully taken in account by our platform. In order to retrieve the status of your booking, please call orders/{:id}.

The endpoint currently supports one-way bookings only. It will also send out booking e-mails to customers. E-Mails are blocked on demo, so feel free to conduct tests bookings on our demo server (api-demo.distribusion.com).

Note: we currently support EUR, USD, GBP and CHF currencies.

HTTP Request

POST https://api.distribusion.com/retailers/v4/orders/create

Query Parameters

Parameter Mandatory Description
marketing_carrier true 4-letter alphanumeric uppercase code.
departure_station true 8- or 9-letter alphanumeric uppercase code.
arrival_station true 8- or 9-letter alphanumeric uppercase code.
departure_time true Departure time in ISO 8601 format without timezone yyyy-mm-ddThh:mm.
arrival_time true departure time in ISO 8601 format without timezone yyyy-mm-ddThh:mm.
retailer_partner_number true 5 - 12 digits number of retailer partner.
title true Allowed values: “mr” or “mrs”.
first_name true First name of the customer, 1-50-letter alphanumeric string.
last_name true Last name of the customer, 1-50-letter alphanumeric string.
email true Email address of the customer.
phone true Phone number of the customer, 8-20-number string.
city true 1-50-letter alphanumeric string.
zip_code true 2-10-letter alphanumeric string.
street_and_number true 1-99-letter alphanumeric string.
execute_payment true Can be true or false. Flag signalling whether the payment transaction should be executed.
payment_method true Allowed value: demand_note, credit_card, sepa_direct_debit, paypal.
payment_token false Unique identifier supplied by the payment service provider.
payer_id false Unique identifier supplied by Paypal.
total_price true Total price of the requested passenger types and extras with added bus marketing carrier booking fee in fractional currency unit (if there is one, in cent) in requested currency. Minimum value - 0, maximum value - 9999900. Provided on successful vacancy request.
pax true Number of passengers. Integer in a range of 1..9.
discount_code false Code consisting of minimum 3 alphanumeric characters.
flight_number false Required by marketing carriers in some cases. 3-9-letter alphanumeric uppercase code.
terms_accepted true Flag signalling whether Terms & Conditions of the marketing carrier have been accepted. Can be true or false.
locale true 2-letter alphanumeric lowercase code, according to ISO 639-1 standard.
currency true 3-letter alphanumeric uppercase code, according to ISO 4217 standard.
send_customer_email true Flag for sending out (or preventing) of the customer confirmation email from Distribusion. Can be true or false.
fare_class false Code consisting of 6-7 alphanumerical characters.
passengers true Array
fist_name true First name of the passenger, 1-50-letter alphanumeric string.
last_name true Last name of the customer, 1-50-letter alphanumeric string.
type true Passenger type. 4-letter alphanumeric uppercase code, available codes can be obtained from GET /marketing_carriers.
extras false Array
quantity true Integer in a range of 1..999.
type true Extra type. 4-letter alphanumeric uppercase code, available codes can be obtained from GET /marketing_carriers.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.004 Departure station is invalid or missing
400.101.005 Arrival station is invalid or missing
400.101.007 Departure time is invalid or missing
400.101.008 Arrival time is invalid or missing
400.101.009 PAX is invalid or missing
400.101.010 Retailer partner number is invalid or missing
400.101.011 Payment method is invalid or missing
400.101.012 Payment token is invalid or missing
400.101.013 Payer ID is invalid or missing
400.101.014 Locale is invalid or missing
400.101.015 Currency is invalid or missing
400.101.018 Title is invalid or missing
400.101.019 First name is invalid or missing
400.101.020 Last name is invalid or missing
400.101.021 Email is invalid or missing
400.101.022 Phone is invalid or missing
400.101.023 City is invalid or missing
400.101.024 Zip code is invalid or missing
400.101.025 Street and number is invalid or missing
400.101.026 Total price is invalid or missing
400.101.027 Customer currency is invalid or missing
400.101.029 Send customer email is invalid or missing
400.101.030 Passenger first name is invalid or missing
400.101.031 Passenger last name is invalid or missing
400.101.032 Passenger type is invalid or missing
400.101.033 Passenger type pax is invalid or missing
400.101.034 Passenger type code is missing or invalid
400.101.035 Terms accepted is invalid or missing
400.101.036 Flight number is invalid or missing
400.101.037 Extra type is invalid or missing
400.101.038 Extra quantity is invalid or missing
400.101.040 Marketing carrier is invalid or missing
400.101.042 Execute payment is invalid or missing
400.101.044 Departure date is in the past
400.101.049 Departure time must be before arrival time
400.101.050 Extras are invalid or missing
400.101.051 Passengers are invalid or missing
400.101.052 Discount code is invalid or missing
400.102.040 Unknown marketing carrier
400.200.001 API key is invalid or missing
400.501.003 Not implemented at Distribusion on bookings#create
400.800.000 Not Found
400.800.040 Marketing carrier not found
500.000.000 Internal Server Error
500.100.000 Service Unavailable
500.500.017 Unique distribusion booking number cannot be generated
500.500.041 Unique booking id cannot be generated
500.501.000 Booking not vacant
500.502.026 Booking price increased
500.502.026 Booking price decreased
600.000.000 Marketing Carrier remote system unavailable
600.100.000 Marketing Carrier remote system time-out
600.400.000 Marketing Carrier remote request invalid
600.500.000 Marketing Carrier remote connection unknown error
600.600.000 Marketing Carrier remote vacancy unknown error
600.700.000 Marketing Carrier remote booking failed error (general)
600.701.000 Marketing Carrier remote booking capacity error
600.702.000 Marketing Carrier remote booking price change error
600.703.000 Marketing Carrier remote booking tariff unavailable error
600.705.000 Marketing Carrier remote booking vacancy unknown error
600.900.000 Response received from a remote server technically cannot be processed
600.901.000 Response from remote server logically cannot be processed (is invalid)
600.703.026 Booking price unknown

Orders Status

curl -X GET \
  https://api-demo.distribusion.com/retailers/v4/orders/NEXP-43927b28-ed74-4cf1-b454-b7b687a2db95 \

The above command returns JSON structured like this:

{
    "data": {
        "id": "NEXP-43927b28-ed74-4cf1-b454-b7b687a2db95",
        "type": "orders",
        "attributes": {
            "state": "executed",
            "executed_at": "2019-03-18T16:07"
        },
        "relationships": {
            "booking": {
                "data": {
                    "id": "Ip0LPaBCZLWzHFq3ln-qkg",
                    "type": "bookings"
                }
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "locale": "en",
        "currency": "EUR"
    },
    "included": [
        {
            "id": "Ip0LPaBCZLWzHFq3ln-qkg",
            "type": "bookings",
            "attributes": {
                "departure_time": "2019-08-15T09:15",
                "arrival_time": "2019-08-15T10:15",
                "duration": 3600,
                "total_price": 2020,
                "pax": 2,
                "flight_number": null,
                "distribusion_booking_number": "KKAEMD",
                "marketing_carrier_booking_number": "P3BA7826",
                "connection_reference": null,
                "created_at": "2019-03-18T16:07"
            },
            "relationships": {
                "fare_class": {
                    "data": {
                        "id": "FARE-1",
                        "type": "fare_classes"
                    }
                },
                "segments": {
                    "data": [
                        {
                            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
                            "type": "segments"
                        }
                    ]
                },
                "passengers": {
                    "data": [
                        {
                            "id": "PADV-BATEAU-CHARLOTTE-1-0",
                            "type": "passengers"
                        },
                        {
                            "id": "PADV-BATEAU-PAUL-2-0",
                            "type": "passengers"
                        }
                    ]
                }
            }
        },
        {
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
            "type": "segments",
            "attributes": {
                "departure_time": "2019-08-15T09:15",
                "arrival_time": "2019-08-15T10:15",
                "index": 0
            },
            "relationships": {
                "segment_passengers": {
                    "data": [
                        {
                            "id": "PADV-BATEAU-CHARLOTTE-1-0",
                            "type": "segment_passengers"
                        },
                        {
                            "id": "PADV-BATEAU-PAUL-2-0",
                            "type": "segment_passengers"
                        },
                        {
                            "id": "PADX-BATEAU-BILOU-2-1",
                            "type": "segment_passengers"
                        }
                    ]
                }
            }
        },
        {
            "id": "PADV-BATEAU-CHARLOTTE-1-0",
            "type": "segment_passengers",
            "attributes": {
                "seat_number": null
            },
            "relationships": {
                "passenger": {
                    "data": {
                        "id": "PADV-BATEAU-CHARLOTTE-1",
                        "type": "passengers"
                    }
                }
            }
        },
        {
            "id": "PADV-BATEAU-PAUL-2-0",
            "type": "segment_passengers",
            "attributes": {
                "seat_number": null
            },
            "relationships": {
                "passenger": {
                    "data": {
                        "id": "PADV-BATEAU-PAUL-2",
                        "type": "passengers"
                    }
                }
            }
        },
        {
            "id": "PADV-BATEAU-CHARLOTTE-1-0",
            "type": "passengers",
            "attributes": {
                "first_name": "Charlotte",
                "last_name": "Bateau",
                "serial_code": null,
                "type": "PADV"
            }
        },
        {
            "id": "PADV-BATEAU-PAUL-2-0",
            "type": "passengers",
            "attributes": {
                "first_name": "Paul",
                "last_name": "Bateau",
                "serial_code": null,
                "type": "PADV"
            }
        },
        {
            "id": "FARE-1",
            "type": "fare_classes",
            "attributes": {
                "code": "FARE-1",
                "name": "Standard",
                "iata_category": null
            },
            "relationships": {
                "fare_features": {
                    "data": [{
              "id": "not amendable",
              "type": "fare_features"
            },
            {
              "id": "not cancellable",
              "type": "fare_features"
            }]
                }
            }
        }
    ]
}

Use this endpoint to retrieve the status of your order. The state can have one of three values:

Once your order have been executed, you will also obtain a booking ID. This booking ID can be used to call our bookings#show in order to get detailed information about the booking and bookings/{:id}/tickets to retrieve the ticket in PDF or HTML format.

HTTP Request

POST https://api.distribusion.com/retailers/v4/orders/:id

Query Parameters

Parameter Mandatory Description
OrderId true 41-letter alphanumeric code.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.004 Departure station is invalid or missing
400.101.005 Arrival station is invalid or missing
400.101.007 Departure time is invalid or missing
400.101.008 Arrival time is invalid or missing
400.101.009 PAX is invalid or missing
400.101.010 Retailer partner number is invalid or missing
400.101.011 Payment method is invalid or missing
400.101.012 Payment token is invalid or missing
400.101.013 Payer ID is invalid or missing
400.101.014 Locale is invalid or missing
400.101.015 Currency is invalid or missing
400.101.018 Title is invalid or missing
400.101.019 First name is invalid or missing
400.101.020 Last name is invalid or missing
400.101.021 Email is invalid or missing
400.101.022 Phone is invalid or missing
400.101.023 City is invalid or missing
400.101.024 Zip code is invalid or missing
400.101.025 Street and number is invalid or missing
400.101.026 Total price is invalid or missing
400.101.027 Customer currency is invalid or missing
400.101.029 Send customer email is invalid or missing
400.101.030 Passenger first name is invalid or missing
400.101.031 Passenger last name is invalid or missing
400.101.032 Passenger type is invalid or missing
400.101.033 Passenger type pax is invalid or missing
400.101.034 Passenger type code is missing or invalid
400.101.035 Terms accepted is invalid or missing
400.101.036 Flight number is invalid or missing
400.101.037 Extra type is invalid or missing
400.101.038 Extra quantity is invalid or missing
400.101.040 Marketing carrier is invalid or missing
400.101.041 ID is invalid or missing
400.101.042 Execute payment is invalid or missing
400.101.044 Departure date is in the past
400.101.049 Departure time must be before arrival time
400.101.050 Extras are invalid or missing
400.101.051 Passengers are invalid or missing
400.101.052 Discount code is invalid or missing
400.102.040 Unknown marketing carrier
400.200.001 API key is invalid or missing
400.501.003 Not implemented at Distribusion on bookings#create
400.800.000 Not Found
400.800.040 Marketing carrier not found
500.000.000 Internal Server Error
500.100.000 Service Unavailable
500.500.017 Unique distribusion booking number cannot be generated
500.500.041 Unique booking id cannot be generated
500.501.000 Booking not vacant
500.502.026 Booking price increased
500.502.026 Booking price decreased
600.000.000 Marketing Carrier remote system unavailable
600.100.000 Marketing Carrier remote system time-out
600.400.000 Marketing Carrier remote request invalid
600.500.000 Marketing Carrier remote connection unknown error
600.600.000 Marketing Carrier remote vacancy unknown error
600.700.000 Marketing Carrier remote booking failed error (general)
600.701.000 Marketing Carrier remote booking capacity error
600.702.000 Marketing Carrier remote booking price change error
600.703.000 Marketing Carrier remote booking tariff unavailable error
600.705.000 Marketing Carrier remote booking vacancy unknown error
600.900.000 Response received from a remote server technically cannot be processed
600.901.000 Response from remote server logically cannot be processed (is invalid)
600.703.026 Booking price unknown

Create

curl -X POST \
  https://api-demo.distribusion.com/retailers/v4/bookings/create \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' \
  -d '{
       "marketing_carrier": "NEXP",
       "departure_station": "GBXVHPET",
       "arrival_station": "GBCBGCCE",
       "departure_time": "2019-08-15T09:15",
       "arrival_time": "2019-08-15T10:15",
       "retailer_partner_number": "{number}",
       "title": "mr",
       "first_name": "Balibalo",
       "last_name": "Bateau",  
       "email": "quentin@mail.com",
       "phone": "4915237601929",
       "city": "Berlin",
       "zip_code": "10123",
       "street_and_number": "Berlinstr. 23",
       "execute_payment": false,
       "payment_method": "demand_note",
       "total_price": 2020,
       "pax": 2,
       "terms_accepted": true,
       "locale": "en",
       "currency": "EUR",
       "send_customer_email": false,
       "fare_class": "FARE-1",
       "passengers":[
          { 
            "first_name": "Charlotte",
            "last_name": "Bateau",
            "type": "PADV"
          },
          { 
            "first_name": "Paul",
            "last_name": "Bateau",
            "type": "PADV"
          }
        ]
    }'

The above command returns JSON structured like this:

{
    "data": {
        "id": "gznKjrRA2x9LhxYCdwt4pw",
        "type": "bookings",
        "attributes": {
            "departure_time": "2019-08-15T09:15",
            "arrival_time": "2019-08-15T10:15",
            "duration": 3600,
            "title": "mr",
            "first_name": "Balibalo",
            "last_name": "Bateau",
            "email": "quentin@mail.com",
            "phone": "4915237601929",
            "city": "Berlin",
            "zip_code": "10123",
            "street_and_number": "Berlinstr. 23",
            "execute_payment": false,
            "payment_method": "demand_note",
            "payment_token": null,
            "payer_id": null,
            "total_price": 2020,
            "pax": 2,
            "flight_number": null,
            "distribusion_booking_number": "FPH5XC",
            "marketing_carrier_booking_number": "P3BA7827",
            "terms_accepted": true,
            "send_customer_email": false,
            "send_marketing_emails": null,
            "retailer_partner_number": "{number}",
            "connection_reference": null,
            "created_at": "2019-03-18T16:09"
        },
        "relationships": {
            "departure_station": {
                "data": {
                    "id": "GBXVHPET",
                    "type": "stations"
                }
            },
            "arrival_station": {
                "data": {
                    "id": "GBCBGCCE",
                    "type": "stations"
                }
            },
            "marketing_carrier": {
                "data": {
                    "id": "NEXP",
                    "type": "marketing_carriers"
                }
            },
            "cancellation": {
                "data": null
            },
            "fare_class": {
                "data": {
                    "id": "FARE-1",
                    "type": "fare_classes"
                }
            },
            "segments": {
                "data": [
                    {
                        "id": "NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
                        "type": "segments"
                    }
                ]
            },
            "passengers": {
                "data": [
                    {
                        "id": "PADV-BATEAU-CHARLOTTE-1",
                        "type": "passengers"
                    },
                    {
                        "id": "PADV-BATEAU-PAUL-2",
                        "type": "passengers"
                    },
                    {
                        "id": "PADX-BATEAU-BILOU-2",
                        "type": "passengers"
                    }
                ]
            },
            "extras": {
                "data": []
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "locale": "en",
        "currency": "EUR"
    },
    "included": [
        {
            "id": "GBXVHPET",
            "type": "stations",
            "attributes": {
                "station_type": "bus_station",
                "code": "GBXVHPET",
                "name": "Peterborough",
                "description": "The bus stop is located near Peterborough Station.",
                "street_and_number": "Westgate",
                "zip_code": "PE1 1NL",
                "longitude": -0.24632,
                "latitude": 52.57511,
                "time_zone": "Europe/London"
            },
            "relationships": {
                "city": {
                    "data": {
                        "id": "GBXVH",
                        "type": "cities"
                    }
                },
                "area": {
                    "data": null
                }
            }
        },
        {
            "id": "GBXVH",
            "type": "cities",
            "attributes": {
                "code": "GBXVH",
                "name": "Peterborough"
            }
        },
        {
            "id": "GBCBGCCE",
            "type": "stations",
            "attributes": {
                "station_type": "bus_station",
                "code": "GBCBGCCE",
                "name": "Cambridge City Centre",
                "description": "The bus stop is located in front of Parkers Piece park. For National Express passengers, from 18/03/2019 - 22/03/2019 from 9pm - 6am the stop will be East Rd, Fire Station; 05/05/2019, the bus will stop at Trumpington Park & Ride, Hauxton Rd.",
                "street_and_number": "Parkside 32",
                "zip_code": "CB1 1JE",
                "longitude": 0.12938269999995,
                "latitude": 52.2032877,
                "time_zone": "Europe/London"
            },
            "relationships": {
                "city": {
                    "data": {
                        "id": "GBCBG",
                        "type": "cities"
                    }
                },
                "area": {
                    "data": null
                }
            }
        },
        {
            "id": "GBCBG",
            "type": "cities",
            "attributes": {
                "code": "GBCBG",
                "name": "Cambridge"
            }
        },
        {
            "id": "NEXP",
            "type": "marketing_carriers",
            "attributes": {
                "code": "NEXP",
                "trade_name": "National Express",
                "legal_name": "National Express Limited",
                "address": "Birmingham Coach Station, Mill Lane, Birmingham B5 6DD, United Kingdom",
                "phone": "+44 (0)3717 818181",
                "fax": "",
                "customer_service_phone": "+44 (0)3717 818181",
                "email": "customerrelations@nationalexpress.com",
                "commercial_register": "",
                "commercial_register_number": "0023767",
                "vat_no": "GB487038714",
                "authorised_representative": "Tom Stables",
                "white_label_logo": "data:image/png;base64",
                "white_label_colour_code": "",
                "terms": "Issued subject to National Express Conditions of Carriage, which can be viewed at \r\n<a href=\"https://www.nationalexpress.com/en/help/conditions-of-carriage\" target=\"blank\">https://www.nationalexpress.com/en/help/conditions-of-carriage</a>",
                "flight_number_required": false,
                "booking_fee": 117,
                "cancellation_fee": 0,
                "cancellation_cutoff": null
            }
        },
        {
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
            "type": "segments",
            "attributes": {
                "departure_time": "2019-08-15T09:15",
                "arrival_time": "2019-08-15T10:15",
                "index": 0
            },
            "relationships": {
                "departure_station": {
                    "data": {
                        "id": "GBXVHPET",
                        "type": "stations"
                    }
                },
                "arrival_station": {
                    "data": {
                        "id": "GBCBGCCE",
                        "type": "stations"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "id": "NEXP",
                        "type": "operating_carriers"
                    }
                },
                "vehicle": {
                    "data": {
                        "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
                        "type": "vehicles"
                    }
                },
                "vehicle": {
                    "data": {
                        "id": "BUS-ISIL-FRLILBDT-FRLYSPER-2019-01-15T17:00-2019-01-16T05:40-1",
                        "type": "vehicles"
                    }
                },
                "segment_passengers": {
                    "data": [
                        {
                            "id": "PADV-BATEAU-CHARLOTTE-1-0",
                            "type": "segment_passengers"
                        },
                        {
                            "id": "PADV-BATEAU-PAUL-2-0",
                            "type": "segment_passengers"
                        },
                        {
                            "id": "PADX-BATEAU-BILOU-2-1",
                            "type": "segment_passengers"
                        }
                    ]
                }
            }
        },
        {
            "id": "NEXP",
            "type": "operating_carriers",
            "attributes": {
                "code": "NEXP",
                "trade_name": "National Express",
                "legal_name": "National Express Limited"
            }
        },
        {
            "id": "PADV-BATEAU-CHARLOTTE-1-0",
            "type": "segment_passengers",
            "attributes": {
                "seat_number": null
            },
            "relationships": {
                "passenger": {
                    "data": {
                        "id": "PADV-BATEAU-CHARLOTTE-1",
                        "type": "passengers"
                    }
                }
            }
        },
        {
            "id": "PADV-BATEAU-PAUL-2-0",
            "type": "segment_passengers",
            "attributes": {
                "seat_number": null
            },
            "relationships": {
                "passenger": {
                    "data": {
                        "id": "PADV-BATEAU-PAUL-2",
                        "type": "passengers"
                    }
                }
            }
        },
        {
            "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "id": "BUS",
                        "type": "vehicle_types"
                    }
                }
            }
        },
        {
            "id": "BUS",
            "type": "vehicle_types",
            "attributes": {
                "code": "BUS",
                "name": "Bus",
                "description": "Long vehicle which is usually transporting a group of people (ca. 45) on streets."
            }
        },
        {
            "id": "PADV-BATEAU-CHARLOTTE-1",
            "type": "passengers",
            "attributes": {
                "first_name": "Charlotte",
                "last_name": "Bateau",
                "serial_code": null,
                "type": "PADV"
            }
        },
        {
            "id": "PADV-BATEAU-PAUL-2",
            "type": "passengers",
            "attributes": {
                "first_name": "Paul",
                "last_name": "Bateau",
                "serial_code": null,
                "type": "PADV"
            }
        },
        {
            "id": "FARE-1",
            "type": "fare_classes",
            "attributes": {
                "code": "FARE-1",
                "name": "Standard",
                "iata_category": null
            },
            "relationships": {
                "fare_features": {
                    "data": [{
               "id": "amendable",
               "type": "fare_features"
            },
            {
               "id": "not cancellable",
               "type": "fare_features"
            }]
                }
            }
        }
    ]
}

Use this endpoint to conduct bookings. Bookings created in this way are the basis for invoicing. The endpoint currently supports one-way bookings only. It will also send out booking e-mails to customers. E-Mails are blocked on demo, so feel free to conduct tests bookings on our demo server (api-demo.distribusion.com).

Note: we currently support EUR, USD, GBP and CHF currencies.

HTTP Request

POST https://api.distribusion.com/retailers/v4/bookings/create

Query Parameters

Parameter Mandatory Description
marketing_carrier true 4-letter alphanumeric uppercase code.
departure_station true 8- or 9-letter alphanumeric uppercase code.
arrival_station true 8- or 9-letter alphanumeric uppercase code.
departure_time true Departure time in ISO 8601 format without timezone yyyy-mm-ddThh:mm.
arrival_time true departure time in ISO 8601 format without timezone yyyy-mm-ddThh:mm.
retailer_partner_number true 5 - 12 digits number of retailer partner.
title true Allowed values: “mr” or “mrs”.
first_name true First name of the customer, 1-50-letter alphanumeric string.
last_name true Last name of the customer, 1-50-letter alphanumeric string.
email true Email address of the customer.
phone true Phone number of the customer, 8-20-number string.
city true 1-50-letter alphanumeric string.
zip_code true 2-10-letter alphanumeric string.
street_and_number true 1-99-letter alphanumeric string.
execute_payment true Can be true or false. Flag signalling whether the payment transaction should be executed.
payment_method true Allowed value: demand_note, credit_card, sepa_direct_debit, paypal.
payment_token false Unique identifier supplied by the payment service provider.
payer_id false Unique identifier supplied by Paypal.
total_price true Total price of the requested passenger types and extras with added bus marketing carrier booking fee in fractional currency unit (if there is one, in cent) in requested currency. Minimum value - 0, maximum value - 9999900. Provided on successful vacancy request.
pax true Number of passengers. Integer in a range of 1..9.
discount_code false Code consisting of minimum 3 alphanumeric characters.
flight_number false Required by marketing carriers in some cases. 3-9-letter alphanumeric uppercase code.
terms_accepted true Flag signalling whether Terms & Conditions of the marketing carrier have been accepted. Can be true or false.
locale true 2-letter alphanumeric lowercase code, according to ISO 639-1 standard.
currency true 3-letter alphanumeric uppercase code, according to ISO 4217 standard.
send_customer_email true Flag for sending out (or preventing) of the customer confirmation email from Distribusion. Can be true or false.
fare_class false Code consisting of 6-7 alphanumerical characters.
passengers true Array
fist_name true First name of the passenger, 1-50-letter alphanumeric string.
last_name true Last name of the customer, 1-50-letter alphanumeric string.
type true Passenger type. 4-letter alphanumeric uppercase code, available codes can be obtained from GET /marketing_carriers.
extras false Array
quantity true Integer in a range of 1..999.
type true Extra type. 4-letter alphanumeric uppercase code, available codes can be obtained from GET /marketing_carriers.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.004 Departure station is invalid or missing
400.101.005 Arrival station is invalid or missing
400.101.007 Departure time is invalid or missing
400.101.008 Arrival time is invalid or missing
400.101.009 PAX is invalid or missing
400.101.010 Retailer partner number is invalid or missing
400.101.011 Payment method is invalid or missing
400.101.012 Payment token is invalid or missing
400.101.013 Payer ID is invalid or missing
400.101.014 Locale is invalid or missing
400.101.015 Currency is invalid or missing
400.101.018 Title is invalid or missing
400.101.019 First name is invalid or missing
400.101.020 Last name is invalid or missing
400.101.021 Email is invalid or missing
400.101.022 Phone is invalid or missing
400.101.023 City is invalid or missing
400.101.024 Zip code is invalid or missing
400.101.025 Street and number is invalid or missing
400.101.026 Total price is invalid or missing
400.101.027 Customer currency is invalid or missing
400.101.029 Send customer email is invalid or missing
400.101.030 Passenger first name is invalid or missing
400.101.031 Passenger last name is invalid or missing
400.101.032 Passenger type is invalid or missing
400.101.033 Passenger type pax is invalid or missing
400.101.034 Passenger type code is missing or invalid
400.101.035 Terms accepted is invalid or missing
400.101.036 Flight number is invalid or missing
400.101.037 Extra type is invalid or missing
400.101.038 Extra quantity is invalid or missing
400.101.040 Marketing carrier is invalid or missing
400.101.042 Execute payment is invalid or missing
400.101.044 Departure date is in the past
400.101.049 Departure time must be before arrival time
400.101.050 Extras are invalid or missing
400.101.051 Passengers are invalid or missing
400.101.052 Discount code is invalid or missing
400.102.040 Unknown marketing carrier
400.200.001 API key is invalid or missing
400.501.003 Not implemented at Distribusion on bookings#create
400.800.000 Not Found
400.800.040 Marketing carrier not found
500.000.000 Internal Server Error
500.100.000 Service Unavailable
500.500.017 Unique distribusion booking number cannot be generated
500.500.041 Unique booking id cannot be generated
500.501.000 Booking not vacant
500.502.026 Booking price increased
500.502.026 Booking price decreased
600.000.000 Marketing Carrier remote system unavailable
600.100.000 Marketing Carrier remote system time-out
600.400.000 Marketing Carrier remote request invalid
600.500.000 Marketing Carrier remote connection unknown error
600.600.000 Marketing Carrier remote vacancy unknown error
600.700.000 Marketing Carrier remote booking failed error (general)
600.701.000 Marketing Carrier remote booking capacity error
600.702.000 Marketing Carrier remote booking price change error
600.703.000 Marketing Carrier remote booking tariff unavailable error
600.705.000 Marketing Carrier remote booking vacancy unknown error
600.900.000 Response received from a remote server technically cannot be processed
600.901.000 Response from remote server logically cannot be processed (is invalid)
600.703.026 Booking price unknown

Redirect for Affiliates

https://bustickets-demo.distribusion.com/redirect?marketing_carrier_code=NEXP&departure_station_code=GBXVHPET&arrival_station_code=GBCBGCCE&departure_time=2019-12-15T02:25&arrival_time=2019-12-15T03:15&currency=EUR&retailer_partner_number={number}&locale=en&pax=1

Affiliates that do not use our bookings#create endpoint, can redirect their customers to our booking page after searching connections on connections#find. The locale will be taken from the setting of the browser, which the customer is using. Alternatively, you can overwrite this functionality by sending your own locale (the order of priority is: locale parameter in URL, then cached locale in browser, and finally the browser locale). The currency can be set within the redirect link.

We currently supports 7 currencies:

You can now retrieve a list of all your booking by calling the bookings#index.

GET https://bustickets.distribusion.com/redirect

URL Parameters

Parameter Mandatory Description
marketing_carrier_code true 4-letter alphanumeric uppercase code.
departure_station_code true 8- or 9-letter alphanumeric uppercase code.
arrival_station_code true 8- or 9-letter alphanumeric uppercase code.
departure_time true Departure time in ISO 8601 format without timezone yyyy-mm-ddThh:mm.
arrival_time true departure time in ISO 8601 format without timezone yyyy-mm-ddThh:mm.
retailer_partner_number true 6 digits number of retailer partner.
currency true 3-letter alphanumeric uppercase code, according to ISO 4217 standard.
locale false 2-letter alphanumeric lowercase code, according to ISO 639-1 standard.
pax false Number of passengers - Integer in a range of 1..9.

Errors

Error Code Meaning
500.000.000 Internal Server Error
500.100.000 Service Unavailable

Index

curl -X GET \
  https://api-demo.distribusion.com/retailers/v4/bookings?created_at=2018-10-01 \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' 

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "qxYan0wvPw4Xh9bUOwd6fg",
      "type": "bookings",
      "attributes": {
        "departure_time": "2018-10-10T14:00",
        "last_name": "Smith",
        "total_price": 15000,
        "pax": 2,
        "distribusion_booking_number": "ZN8FX2",
        "created_at": "2018-10-01T15:31"
      },
      "relationships": {
        "departure_station": {
          "data": {
            "id": "DEBERCBS",
            "type": "stations"
          }
        },
        "arrival_station": {
          "data": {
            "id": "UAIEVZOB",
            "type": "stations"
          }
        },
        "marketing_carrier": {
          "data": {
            "id": "AKKM",
            "type": "marketing_carriers"
          }
        },
        "cancellation": {
          "data": {
            "id": "7Zr0AWGXiL-pCAb14d-9tA",
            "type": "cancellations"
          }
        }
      }
    }
  ],

  -------

  "included": [
    {
      "id": "AKKM",
      "type": "marketing_carriers",
      "attributes": {
        "trade_name": "AS Karpaten & Krim Tours (Schevschenko)"
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "locale": "en",
    "currency": "EUR"
  }
}

You can now retrieve a list of all your booking by calling the bookings#index. Alternatively, you can filter your booking list for a specific day by using the parameter bellow:

URL Parameters

Parameter Mandatory Description
created_at false Departure date in ISO 8601 format.

HTTP Request

GET api.distribusion.com/retailers/v4/bookings

Errors

Error Code Meaning
400.200.001 API key is invalid or missing
500.000.000 Internal Server Error
500.100.000 Service Unavailable

Show

curl -X GET \
  https://api-demo.distribusion.com/retailers/v4/bookings/gznKjrRA2x9LhxYCdwt4pw \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' 

The above command returns JSON structured like this:

{
    "data": {
        "id": "gznKjrRA2x9LhxYCdwt4pw",
        "type": "bookings",
        "attributes": {
            "departure_time": "2019-08-15T09:15",
            "arrival_time": "2019-08-15T10:15",
            "duration": 3600,
            "title": "mr",
            "first_name": "Balibalo",
            "last_name": "Bateau",
            "email": "quentin@mail.com",
            "phone": "4915237601929",
            "city": "Berlin",
            "zip_code": "10123",
            "street_and_number": "Berlinstr. 23",
            "execute_payment": false,
            "payment_method": "demand_note",
            "payment_token": null,
            "payer_id": null,
            "total_price": 2020,
            "pax": 2,
            "flight_number": null,
            "distribusion_booking_number": "FPH5XC",
            "marketing_carrier_booking_number": "P3BA7827",
            "terms_accepted": true,
            "send_customer_email": false,
            "send_marketing_emails": null,
            "retailer_partner_number": "{number}",
            "connection_reference": null,
            "created_at": "2019-03-18T16:09"
        },
        "relationships": {
            "departure_station": {
                "data": {
                    "id": "GBXVHPET",
                    "type": "stations"
                }
            },
            "arrival_station": {
                "data": {
                    "id": "GBCBGCCE",
                    "type": "stations"
                }
            },
            "marketing_carrier": {
                "data": {
                    "id": "NEXP",
                    "type": "marketing_carriers"
                }
            },
            "cancellation": {
                "data": null
            },
            "fare_class": {
                "data": {
                    "id": "FARE-1",
                    "type": "fare_classes"
                }
            },
            "segments": {
                "data": [
                    {
                        "id": "NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
                        "type": "segments"
                    }
                ]
            },
            "passengers": {
                "data": [
                    {
                        "id": "PADV-BATEAU-CHARLOTTE-1",
                        "type": "passengers"
                    },
                    {
                        "id": "PADV-BATEAU-PAUL-2",
                        "type": "passengers"
                    },
                    {
                        "id": "PADX-BATEAU-BILOU-2",
                        "type": "passengers"
                    }
                ]
            },
            "extras": {
                "data": []
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "locale": "en",
        "currency": "EUR"
    },
    "included": [
        {
            "id": "GBXVHPET",
            "type": "stations",
            "attributes": {
                "station_type": "bus_station",
                "code": "GBXVHPET",
                "name": "Peterborough",
                "description": "The bus stop is located near Peterborough Station.",
                "street_and_number": "Westgate",
                "zip_code": "PE1 1NL",
                "longitude": -0.24632,
                "latitude": 52.57511,
                "time_zone": "Europe/London"
            },
            "relationships": {
                "city": {
                    "data": {
                        "id": "GBXVH",
                        "type": "cities"
                    }
                },
                "area": {
                    "data": null
                }
            }
        },
        {
            "id": "GBXVH",
            "type": "cities",
            "attributes": {
                "code": "GBXVH",
                "name": "Peterborough"
            }
        },
        {
            "id": "GBCBGCCE",
            "type": "stations",
            "attributes": {
                "station_type": "bus_station",
                "code": "GBCBGCCE",
                "name": "Cambridge City Centre",
                "description": "The bus stop is located in front of Parkers Piece park. For National Express passengers, from 18/03/2019 - 22/03/2019 from 9pm - 6am the stop will be East Rd, Fire Station; 05/05/2019, the bus will stop at Trumpington Park & Ride, Hauxton Rd.",
                "street_and_number": "Parkside 32",
                "zip_code": "CB1 1JE",
                "longitude": 0.12938269999995,
                "latitude": 52.2032877,
                "time_zone": "Europe/London"
            },
            "relationships": {
                "city": {
                    "data": {
                        "id": "GBCBG",
                        "type": "cities"
                    }
                },
                "area": {
                    "data": null
                }
            }
        },
        {
            "id": "GBCBG",
            "type": "cities",
            "attributes": {
                "code": "GBCBG",
                "name": "Cambridge"
            }
        },
        {
            "id": "NEXP",
            "type": "marketing_carriers",
            "attributes": {
                "code": "NEXP",
                "trade_name": "National Express",
                "legal_name": "National Express Limited",
                "address": "Birmingham Coach Station, Mill Lane, Birmingham B5 6DD, United Kingdom",
                "phone": "+44 (0)3717 818181",
                "fax": "",
                "customer_service_phone": "+44 (0)3717 818181",
                "email": "customerrelations@nationalexpress.com",
                "commercial_register": "",
                "commercial_register_number": "0023767",
                "vat_no": "GB487038714",
                "authorised_representative": "Tom Stables",
                "white_label_logo": "data:image/png;base64",
                "white_label_colour_code": "",
                "terms": "Issued subject to National Express Conditions of Carriage, which can be viewed at \r\n<a href=\"https://www.nationalexpress.com/en/help/conditions-of-carriage\" target=\"blank\">https://www.nationalexpress.com/en/help/conditions-of-carriage</a>",
                "flight_number_required": false,
                "booking_fee": 117,
                "cancellation_fee": 0,
                "cancellation_cutoff": null
            }
        },
        {
            "id": "NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
            "type": "segments",
            "attributes": {
                "departure_time": "2019-08-15T09:15",
                "arrival_time": "2019-08-15T10:15",
                "index": 0
            },
            "relationships": {
                "departure_station": {
                    "data": {
                        "id": "GBXVHPET",
                        "type": "stations"
                    }
                },
                "arrival_station": {
                    "data": {
                        "id": "GBCBGCCE",
                        "type": "stations"
                    }
                },
                "operating_carrier": {
                    "data": {
                        "id": "NEXP",
                        "type": "operating_carriers"
                    }
                },
                "vehicle": {
                    "data": {
                        "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
                        "type": "vehicles"
                    }
                },
                "vehicle": {
                    "data": {
                        "id": "BUS-ISIL-FRLILBDT-FRLYSPER-2019-01-15T17:00-2019-01-16T05:40-1",
                        "type": "vehicles"
                    }
                },
                "segment_passengers": {
                    "data": [
                        {
                            "id": "PADV-BATEAU-CHARLOTTE-1-0",
                            "type": "segment_passengers"
                        },
                        {
                            "id": "PADV-BATEAU-PAUL-2-0",
                            "type": "segment_passengers"
                        },
                        {
                            "id": "PADX-BATEAU-BILOU-2-1",
                            "type": "segment_passengers"
                        }
                    ]
                }
            }
        },
        {
            "id": "NEXP",
            "type": "operating_carriers",
            "attributes": {
                "code": "NEXP",
                "trade_name": "National Express",
                "legal_name": "National Express Limited"
            }
        },
        {
            "id": "PADV-BATEAU-CHARLOTTE-1-0",
            "type": "segment_passengers",
            "attributes": {
                "seat_number": null
            },
            "relationships": {
                "passenger": {
                    "data": {
                        "id": "PADV-BATEAU-CHARLOTTE-1",
                        "type": "passengers"
                    }
                }
            }
        },
        {
            "id": "PADV-BATEAU-PAUL-2-0",
            "type": "segment_passengers",
            "attributes": {
                "seat_number": null
            },
            "relationships": {
                "passenger": {
                    "data": {
                        "id": "PADV-BATEAU-PAUL-2",
                        "type": "passengers"
                    }
                }
            }
        },
        {
            "id": "BUS-NEXP-GBXVHPET-GBCBGCCE-2019-08-15T09:15-2019-08-15T10:15-0",
            "type": "vehicles",
            "relationships": {
                "vehicle_type": {
                    "data": {
                        "id": "BUS",
                        "type": "vehicle_types"
                    }
                }
            }
        },
        {
            "id": "BUS",
            "type": "vehicle_types",
            "attributes": {
                "code": "BUS",
                "name": "Bus",
                "description": "Long vehicle which is usually transporting a group of people (ca. 45) on streets."
            }
        },
        {
            "id": "PADV-BATEAU-CHARLOTTE-1",
            "type": "passengers",
            "attributes": {
                "first_name": "Charlotte",
                "last_name": "Bateau",
                "serial_code": null,
                "type": "PADV"
            }
        },
        {
            "id": "PADV-BATEAU-PAUL-2",
            "type": "passengers",
            "attributes": {
                "first_name": "Paul",
                "last_name": "Bateau",
                "serial_code": null,
                "type": "PADV"
            }
        },
        {
            "id": "FARE-1",
            "type": "fare_classes",
            "attributes": {
                "code": "FARE-1",
                "name": "Standard",
                "iata_category": null
            },
            "relationships": {
                "fare_features": {
                    "data": [{
               "id": "amendable",
               "type": "fare_features"
            },
            {
               "id": "not cancellable",
               "type": "fare_features"
            }]
                }
            }
        }
    ]
}

To review data of a booking at a later stage without saving all information into your system, you can use our bookings#show endpoint to retrieve it and show its data.

HTTP Request

GET api.distribusion.com/retailers/v4/bookings/

URL Parameters

Parameter Mandatory Description
booking true 22-letter alphanumeric lowercase code, provided on successful booking.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.041 Booking is invalid or missing
400.200.001 API key is invalid or missing
400.800.000 Not Found
500.000.000 Internal Server Error
500.100.000 Service Unavailable
400.501.005 Not implemented at Distribusion on bookings#show
400.800.041 Booking not found

Tickets

curl -X GET \
  https://api-demo.distribusion.com/retailers/v4/bookings/9KRtPqq5YM5dKl9D6A_igA/tickets \
  -H 'Api-Key: H4gtqUn04qDh7mmZpFJYmmcW7JVw7hMIaCUcdWhZ' \
  -H 'Content-Type: application/json'

This endpoint is dedicated to retailers sending their own confirmation email. If you have set send_customer_email to true, you do not need this endpoint.

The ticket either has one page containing the information of all the passengers, or it consists of one page per passenger (in PDF format). You can also retrieve your ticket in HTML, or in mobile format by adding the type parameter.

Note: Not all carriers support mobile tickets. To know if a specific marketing carrier supports mobile ticket, call marketing_carriers#show and look for has_mobile_tickets parameter.

alt text

HTTP Request

GET api.distribusion.com/retailers/v4/bookings/{id}/tickets

URL Parameters

Parameter Mandatory Description
type false Allowed value: html, pkpass

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.041 Booking is invalid or missing
400.200.001 API key is invalid or missing
400.800.000 Not Found
500.000.000 Internal Server Error
500.100.000 Service Unavailable
400.501.006 Not implemented at Distribusion on bookings#ticket
400.800.041 Booking not found

Cancellations

Conditions

curl -X GET \
  'https://api-demo.distribusion.com/retailers/v4/cancellations/conditions?booking=ZpXv69xrzHzk8Nb-YHGllA' \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' 

The above command returns JSON structured like this:

{
  "data": {
    "id": "ZpXv69xrzHzk8Nb-YHGllA",
    "type": "cancellation_conditions",
    "attributes": {
      "allowed": true,
      "fee": 1500,
      "cutoff": "2018-03-28T12:00"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "currency": "EUR"
  }
}

This endpoint enable users to retrieve detailed information about the cancellation of a specific booking. Note that not all marketing carriers offer cancellations and that in some case, the cancellation fee do not reflect the flexibility of the terms and conditions due to technical reasons. The current workflow only allow a full (or partial) refund of the booking, no options for vouchers are currently available.

HTTP Request

GET api.distribusion.com/retailers/v4/cancellations/conditions

URL Parameters

Parameter Mandatory Description
booking true 22-letter alphanumeric lowercase code, provided on successful booking.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.200.001 API key is invalid or missing
400.800.041 Booking not found
400.500.041 Cancellation is not allowed
400.501.007 Not implemented at Distribusion on cancellations#conditions
500.000.000 Internal Server Error
500.100.000 Service Unavailable

Create

curl -X POST \
  https://api-demo.distribusion.com/retailers/v4/cancellations/create \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' \
  -d '{ "booking": "ZpXv69xrzHzk8Nb-YHGllA" }'

The above command returns JSON structured like this:

{
  "data": {
    "id": "6JXfs7hJpMe3FsF-JfudLA",
    "type": "cancellations",
    "attributes": {
      "total_price": 2000,
      "fee": 1500,
      "total_refund": 500,
      "created_at": "2017-05-23T16:21"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "currency": "EUR"
  }
}

This endpoint enables users to perform the cancellation of a specific booking.

Note: The cancellation example is not linked to the previous booking example, as it is not cancellable.

HTTP Request

POST api.distribusion.com/retailers/v4/cancellations/create

URL Parameters

Parameter Mandatory Description
booking true 22-letter alphanumeric lowercase code, provided on successful booking.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.200.001 API key is invalid or missing
400.502.041 Booking already cancelled
400.800.041 Booking not found
400.800.042 Webhook not defined
500.000.000 Internal Server Error
500.100.000 Service Unavailable
500.600.041 Unique cancellation id cannot be generated

Webhook

Distribusion offer the possibility for retailer to get informed about cancellations happening outside their own environment (on marketing carrier or Distribusion’s side). To enable this functionality, please contact your integration manager.

Marketing Carriers

Index

curl -X GET \
  https://api-demo.distribusion.com/retailers/v4/marketing_carriers \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' 

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "EONL",
      "type": "marketing_carriers",
      "attributes": {
        "code": "EONL",
        "trade_name": "Eurobus Online"
      }
    },
    {
      "id": "ESBU",
      "type": "marketing_carriers",
      "attributes": {
        "code": "ESBU",
        "trade_name": "Eskana Bus"
      }
    },
    {
      "id": "AKKM",
      "type": "marketing_carriers",
      "attributes": {
        "code": "AKKM",
        "trade_name": "AS Karpaten & Krim Tours (Schevschenko)"
      }
    },
    {
      "id": "BLIE",
      "type": "marketing_carriers",
      "attributes": {
        "code": "BLIE",
        "trade_name": "Blue Line"
      }
    }
  ],

  -------
  "jsonapi": {
    "version": "1.0"
  }
}

This endpoint provides a list of marketing carriers with their trade name and code.

HTTP Request

GET api.distribusion.com/retailers/v4/marketing_carriers

Errors

Error Code Meaning
500.000.000 Internal Server Error
500.100.000 Service Unavailable

Show

curl -X GET \
  'https://api-demo.distribusion.com/retailers/v4/marketing_carriers/SIBU?locale=en&currency=EUR' \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' 

The above command returns JSON structured like this:

{
    "data": {
        "id": "NEXP",
        "type": "marketing_carriers",
        "attributes": {
            "code": "NEXP",
            "trade_name": "National Express",
            "legal_name": "National Express Limited",
            "address": "Birmingham Coach Station, Mill Lane, Birmingham B5 6DD, United Kingdom",
            "phone": "+44 (0)3717 818181",
            "fax": "",
            "customer_service_phone": "+44 (0)3717 818181",
            "email": "customerrelations@nationalexpress.com",
            "commercial_register": "",
            "commercial_register_number": "0023767",
            "vat_no": "GB487038714",
            "authorised_representative": "Tom Stables",
            "white_label_logo": "data:image/png;base64",
            "white_label_colour_code": "",
            "terms": "Issued subject to National Express Conditions of Carriage, which can be viewed at \r\n<a href=\"https://www.nationalexpress.com/en/help/conditions-of-carriage\" target=\"blank\">https://www.nationalexpress.com/en/help/conditions-of-carriage</a>",
            "flight_number_required": false,
            "has_mobile_tickets": false,
            "tickets_validity_in_hours": null,
            "tickets_validity_info": "In case of traveling from/to an airport this ticket is valid for 12 hours after the departure time stated above.",
            "booking_fee": 116,
            "cancellation_fee": 0,
            "cancellation_cutoff": null
        },
        "relationships": {
            "default_passenger_type": {
                "data": {
                    "id": "PADV",
                    "type": "passenger_types"
                }
            },
            "passenger_types": {
                "data": [
                    {
                        "id": "PADV",
                        "type": "passenger_types"
                    }
                ]
            },
            "extra_types": {
                "data": []
            },
            "vehicle_types": {
                "data": [
                    {
                        "id": "BUS",
                        "type": "vehicle_types"
                    }
                ]
            },
            "fare_classes": {
                "data": [
                    {
                        "id": "FARE-1",
                        "type": "fare_classes"
                    },
                    {
                        "id": "FARE-2",
                        "type": "fare_classes"
                    },
                    {
                        "id": "FARE-3",
                        "type": "fare_classes"
                    }
                ]
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "locale": "it",
        "currency": "EUR"
    },
    "included": [
        {
            "id": "PADV",
            "type": "passenger_types",
            "attributes": {
                "code": "PADV",
                "name": "Adulti",
                "description": ""
            }
        },
        {
            "id": "BUS",
            "type": "vehicle_types",
            "attributes": {
                "code": "BUS",
                "name": "Bus",
                "description": "Long vehicle which is usually transporting a group of people (ca. 45) on streets."
            }
        },
        {
            "id": "FARE-1",
            "type": "fare_classes",
            "attributes": {
                "code": "FARE-1",
                "name": "Standard",
                "iata_category": null
            },
            "relationships": {
                "fare_features": {
                    "data": [{
               "id": "amendable",
               "type": "fare_features"
            },
            {
               "id": "not cancellable",
               "type": "fare_features"
            }]
                }
            }
        },
        {
            "id": "FARE-2",
            "type": "fare_classes",
            "attributes": {
                "code": "FARE-2",
                "name": "Restricted",
                "iata_category": null
            },
            "relationships": {
                "fare_features": {
                    "data": [{
              "id": "not amendable",
              "type": "fare_features"
            },
            {
              "id": "not cancellable",
              "type": "fare_features"
            }]
                }
            }
        },
        {
            "id": "FARE-3",
            "type": "fare_classes",
            "attributes": {
                "code": "FARE-3",
                "name": "Fully Flexible",
                "iata_category": null
            },
            "relationships": {
                "fare_features": {
                    "data": [{
              "id": "amendable",
              "type": "fare_features"
            },
            {
              "id": "cancellable",
              "type": "fare_features"
            }]
                }
            }
        },
        {
          "id": "amendable",
          "type": "fare_features",
          "attributes": {
            "code": "amendable",
            "name": "Amendable",
            "description": "You can make changes to your booking for an additional fee (starting from £5) by contacting National Express customer service."
          }
        },
        {
          "id": "not cancellable",
          "type": "fare_features",
          "attributes": {
            "code": "not cancellable",
            "name": "Not Cancellable",
            "description": "No refund or cancellation possible."
          }
        },
        {
          "id": "cancellable",
          "type": "fare_features",
          "attributes": {
            "code": "cancellable",
            "name": "Cancellable",
            "description": "Cancellable up to 72h before the departure of your trip."
          }
        }
    ] 
}

This endpoint enable users to retrieve detailed information about marketing carriers, such as passenger types, fare classes, cancellations conditions, terms & conditions, etc.

HTTP Request

GET api.distribusion.com/retailers/v4/marketing_carriers/{code}

URL Parameters

Parameter Mandatory Description
locale true 2-letter alphanumeric lowercase code, according to ISO 639-1 standard.
currency true 3-letter alphanumeric uppercase code, according to ISO 4217 standard.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.014 Locale is invalid or missing
400.101.015 Currency is invalid or missing
400.101.040 Marketing carrier is invalid or missing
400.501.004 Not implemented at Distribusion on bookings#form_schema
400.800.000 Not Found
400.800.040 Marketing carrier not found
500.000.000 Internal Server Error
500.100.000 Service Unavailable

Stations

curl -X GET \
  https://api-demo.distribusion.com/retailers/v4/marketing_carriers/SIBU/stations \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' 

The above command returns JSON structured like this:

{
    "data": [
        {
            "id": "ITROMCGI",
            "type": "stations"
        },
        {
            "id": "ITROMVMA",
            "type": "stations"
        },
        {
            "id": "ITZRRPGA",
            "type": "stations"
        },
        {
            "id": "ITROMVCE",
            "type": "stations"
        },
        {
            "id": "ITROMRCF",
            "type": "stations"
        },
        {
            "id": "ITROMRVA",
            "type": "stations"
        },
        {
            "id": "ITROMRFB",
            "type": "stations"
        }
    ],
    "jsonapi": {
        "version": "1.0"
    }
}

This endpoint provides a list of stations attached to a specific marketing carrier. This can help you map stations based on the marketing carrier you wish to display in your application.

HTTP Request

GET api.distribusion.com/retailers/v4/marketing_carriers/{code}/stations

Errors

Error Code Meaning
500.000.000 Internal Server Error
500.100.000 Service Unavailable

Stations

curl -X GET \
  'https://api-demo.distribusion.com/retailers/v4/stations?locale=en' \
  -H 'api-key: AIzaSyBGEpZdxbufTSpcIxWXoRjSdKu6ZctiuyI' \
  -H 'content-type: application/json' 

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "DEEIBUFE",
      "type": "stations",
      "attributes": {
        "code": "DEEIBUFE",
        "name": "Eisenach Uferstraße",
        "description": "Bus station is located at the intersection of Schillerstrasse and Gabelsberger Strasse, roughly 100 metres north-west of the Deutsche Bahn train station",
        "street_and_number": "Uferstraße 40",
        "zip_code": "99817",
        "longitude": 10.327165,
        "latitude": 50.978095,
        "time_zone": "Europe/Berlin"
      },
      "relationships": {
        "city": {
          "data": {
            "id": "DEEIB",
            "type": "cities"
          }
        }
      }
    },
    {
      "id": "DEBHEZOB",
      "type": "stations",
      "attributes": {
        "code": "DEBHEZOB",
        "name": "Bad Hersfeld ZOB",
        "description": "Bus station is located on the courtyard south-west of the Deutsche Bahn train station.",
        "street_and_number": "Bahnhofstraße 20",
        "zip_code": "36251",
        "longitude": 9.715529,
        "latitude": 50.868954,
        "time_zone": "Europe/Berlin"
      },
      "relationships": {
        "city": {
          "data": {
            "id": "DEBHE",
            "type": "cities"
          }
        }
      }
    },
    {
      "id": "DEBERBZO",
      "type": "stations",
      "attributes": {
        "code": "DEBERBZO",
        "name": "Berlin Bhf Zoo",
        "description": "The bus stop for Berlin Zoo Train Station is located right at Berlin's Zoological Gardens, at Hardenbergplatz 11, and is the departure point for numerous intercity buses. The stop is thus located slightly beyond the stops serviced by the Berlin Transit Corporation, which are nevertheless also accessible when exiting the station towards Hardenbergplatz. The proximity to the Zoo Train Station, as well as to S-Bahn lines (S5, S7, S75), U-Bahn lines (U2, U9), and regional trains is a major plus for all travellers hoping to reach other areas of Berlin.",
        "street_and_number": "Hardenbergplatz 15",
        "zip_code": "10623",
        "longitude": 13.33371,
        "latitude": 52.508425,
        "time_zone": "Europe/Berlin"
      },
      "relationships": {
        "city": {
          "data": {
            "id": "DEBER",
            "type": "cities"
          }
        }
      }
    }
      .....
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "locale": "en"
  }
}

This endpoint enable users to retrieve detailed information about stations, such as name, id, GPS location, address and description.

HTTP Request

GET api.distribusion.com/retailers/v4/stations

URL Parameters

Parameter Mandatory Description
locale true 2-letter alphanumeric lowercase code, according to ISO 639-1 standard.

Errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.014 Locale is invalid or missing
500.000.000 Internal Server Error
500.100.000 Service Unavailable

Errors

We have developed a set of error codes, destined to provide you with helpful information when integrating Distribusion API. We categorised them into three main types:

Client errors

Error Code Meaning
400.000.000 The provided json is invalid
400.100.000 Request invalid
400.101.002 Departure stations are invalid or missing
400.101.003 Arrival stations are invalid or missing
400.101.004 Departure station is invalid or missing
400.101.005 Arrival station is invalid or missing
400.101.006 Departure date is invalid or missing
400.101.007 Departure time is invalid or missing
400.101.008 Arrival time is invalid or missing
400.101.009 PAX is invalid or missing
400.101.010 Retailer partner number is invalid or missing
400.101.011 Payment method is invalid or missing
400.101.012 Payment token is invalid or missing
400.101.013 Payer ID is invalid or missing
400.101.014 Locale is invalid or missing
400.101.015 Currency is invalid or missing
400.101.016 Operating carrier is invalid or missing
400.101.017 Distribusion booking number is invalid or missing
400.101.018 Title is invalid or missing
400.101.019 First name is invalid or missing
400.101.020 Last name is invalid or missing
400.101.021 Email is invalid or missing
400.101.022 Phone is invalid or missing
400.101.023 City is invalid or missing
400.101.024 Zip code is invalid or missing
400.101.025 Street and number is invalid or missing
400.101.026 Total price is invalid or missing
400.101.027 Customer currency is invalid or missing
400.101.029 Send customer email is invalid or missing
400.101.030 Passenger first name is invalid or missing
400.101.031 Passenger last name is invalid or missing
400.101.032 Passenger type is invalid or missing
400.101.033 Passenger type pax is invalid or missing
400.101.034 Passenger type code is missing or invalid
400.101.035 Terms accepted is invalid or missing
400.101.036 Flight number is invalid or missing
400.101.037 Extra type is invalid or missing
400.101.038 Extra quantity is invalid or missing
400.101.039 Marketing carrier booking number is invalid or missing
400.101.040 Marketing carrier is invalid or missing
400.101.041 Booking is invalid or missing
400.101.042 Execute payment is invalid or missing
400.101.044 Departure date is in the past
400.101.049 Departure time must be before arrival time
400.101.050 Extras are invalid or missing
400.101.051 Passengers are invalid or missing
400.101.052 Discount code is invalid or missing
400.101.053 Bus Number is missing or invalid
400.102.040 Unknown marketing carrier
400.200.001 API key is invalid or missing
400.500.041 Cancellation is not allowed
400.502.041 Booking already cancelled
400.800.000 Not Found
400.800.040 Marketing carrier not found
400.800.041 Booking not found
429.000.000 Too Many Requests
Error Code Meaning
400.501.000 Not implemented at Distribusion on connections#find
400.501.001 Not implemented on connections#redirect_to_checkout
400.501.002 Not implemented at Distribusion on connections#vacancy
400.501.003 Not implemented at Distribusion on bookings#create
400.501.004 Not implemented at Distribusion on bookings#form_schema
400.501.005 Not implemented at Distribusion on bookings#show
400.501.006 Not implemented at Distribusion on bookings#tickets
400.501.007 Not implemented at Distribusion on cancellations#conditions
400.501.008 Not implemented at Distribusion on cancellations#create
400.501.009 Not implemented at Distribusion on marketing_carriers#index
400.501.010 Not implemented at Distribusion on marketing_carriers#show
400.501.011 Not implemented at Distribusion on stations#index

Server errors

Error Code Meaning
500.000.000 Internal Server Error
500.100.000 Service Unavailable
500.500.017 Unique distribusion booking number cannot be generated
500.500.041 Unique booking id cannot be generated
500.501.000 Booking not vacant
500.502.026 Booking price increased
500.502.026 Booking price decreased
500.600.041 Unique cancellation id cannot be generated

Remote server errors

Error Code Meaning
600.000.000 Marketing Carrier remote system unavailable
600.100.000 Marketing Carrier remote system time-out
600.400.000 Marketing Carrier remote request invalid
600.500.000 Marketing Carrier remote connection unknown error
600.600.000 Marketing Carrier remote vacancy unknown error
600.700.000 Marketing Carrier remote booking failed error (general)
600.701.000 Marketing Carrier remote booking capacity error
600.702.000 Marketing Carrier remote booking price change error
600.703.000 Marketing Carrier remote booking tariff unavailable error
600.704.000 Marketing Carrier remote booking already cancelled error
600.705.000 Marketing Carrier remote booking vacancy unknown error
600.900.000 Response received from a remote server technically cannot be processed
600.901.000 Response from remote server logically cannot be processed (is invalid)
600.703.026 Booking price unknown

Dictionary

Booking Fee: A fee that is charged by a marketing carrier to the customer in the booking process. It is added on top of all ticket and extra prices and is independent of the amount of passengers (eg. National Express adds a pound on every booking made), not to confuse with Distribusion transaction fee.

Carrier: A Distribusion defined term to identify a Distribusion coded transporation companies.The Carrier can take up two roles within a trip: Marketing Carrier or Operating Carrier. Both is identified with the same code.

Commission: Form of payment to a retailer, we have 3 different commission types (OTAs, STAs, Affiliate). All of them are defined as net percentage of gross ticket value.

Credit Note: All commissions which retailers receive from Distribusion each month. provided in a PDF format.

Demand Note: OTAs and STAs are collecting the ticket revenues of consumers booking trips. A Demand Note is a consolidates statement of these ticket revenue of retailers provided as PDF. It also includes revenues from cancellations.

IATA: International Air Transport Association (IATA), IATA supports airline activity and helps formulate industry policy and standards.

IATA Code: 3-letter Codes for airports, started by IATA organization 70 years ago to standardize and harmonize locale of airports for the entire industry.

Marketing Carriers: Carrier which is defining the fare rules towards the customer and legally liable for the success of a booked trip (mostly also responsible for customer service). Marketing Carriers are also branding the ticket and using white label products in their solutions.

OTA: Short for: Online Travel Agency - website selling (not just showing) travel products to end consumers or business customers. Usually conduct payments and customer service to a certain degree. Distribusion supports OTA to perform “full booking integration” via the API.

Operating Carriers: Operating carriers are the entity actually driving the bus.

PAX: Abbreviation of “Persons approximately”, used in tourism for the number of passengers.

STA: Short for Stationary Travel Agencies.

Travel Agency: Online or Offline agency which sells tourism and mobility related products online (OTA) and Offline (STA).

Vacancy: Activity to derive prices for a selected connections or to verify availability, based on a selected amount of pax (including the specific types, such as child, adult, etc.)