Introduction

Welcome to the Kombo API documentation!

This API will allow you to :

retrieve static information (Cities, stations,...)
search for trips

Global approach

Some information is static and needs to be updated only daily. These are the Cities, the Railway Stations and the Companies.

Others evolving quickly, such as prices and schedules, must be updated with each request.

Once you have retrieved all static information, you will be able to launch searches. The logic is this:

1- Ask for trips for a given journey, date and number of passengers: GET /search

2- Retrieve results once they are available: GET /pollSearch until completed = true

Environment

For affiliation, you can run your tests directly with prod data. The root URL of the API is :

Environment	URL
Prod	https://turing.kombo.co

Authentication

> To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "token: MySecretToken"
> Make sure to replace `MySecretToken` with your API key.

Kombo uses API keys to allow access to the API.

The key has to be included in the header of all requests:

token: MySecretToken

You must replace MySecretToken with your personal API key.

Models

City

{
  "id": 7,
  "name": "Aix-en-Provence",
  "latitude": "43.531100",
  "longitude": "5.454020",
  "country": {
    "code": "FR"
  },
  "stations": [
    {
      "id": 7,
      "name": "Nice Côte d Azur International Airport",
      "latitude": "43.523201",
      "longitude": "5.445140",
      "transportType": ["train", "bus"],
      "cityId": 7
    },
    {
      "id": 286,
      "name": "124 avenue Henri Mouret",
      "latitude": "43.523201",
      "longitude": "5.437090",
      "transportType": ["train"],
      "cityId": 7
    },
    {
      "id": 701,
      "name": "2-4 Boulevard Victor Coq",
      "latitude": "43.523399",
      "longitude": "5.441470",
      "transportType": ["bus"],
      "cityId": 7
    },
    {
      "id": 2375,
      "name": "Avenue de l'Arc de Meyran",
      "latitude": "43.511002",
      "longitude": "5.447620",
      "transportType": ["bus"],
      "cityId": 7
    }
  ]
}

For all searches, the starting and arrival points are defined by City (GET /city). Each city may have several Station (GET /station).

Structure

attribute	kind	Optionnal	Description
id	int	No	Define the city with its unique number.
name	string	No	Popular name of the city in English
country	string(2)	No	Define the country of the city (FR, DE, IT,...) - ISO 3166
latitude	float	No	Latitude of the center of the city
longitude	float	No	Longitude of the center of the city
Station	Array	Yes	Contains all the stations of the city

Station

  {
    "id": 7,
    "name": "Gare d'Aix-en-Provence",
    "latitude": "43.523201",
    "longitude": "5.445140",
    "transportType": ["train", "bus", "flight"],
    "iataCode": "NCE",
    "cityId": 7
  }

Each Station is linked to a City by its cityId.

Structure

attribute	kind	Optionnal	Description
id	int	No	Define the station with its unique number.
name	string	No	Description of the station
latitude	float	No
longitude	float	No
transportType	TransportType[]	Yes	known transport mode
iataCode	string	Yes	International IATA code
cityId	int	No	Link the station with its city

Company

  {
    "id": 2,
    "name": "Flixbus",
    "iataCode": "FX",
    "transportType": "bus"
  }

Structure

attribute	kind	Optionnal	Description
id	int	No	The unique identifier of the company
name	string	No	Commercial name of the operator
iataCode	string	Yes	International IATA code
transportType	string	No	values:[bus', 'train', 'carpooling','flight','ferry']

Trip

  {
    "tripId": "1m9900bb6i0qbp1io0qbp4zo8b08015o",
    "price": 1500,
    "segments":
      [
        [
          {
            "departureStationId": 28845,
            "arrivalStationId": 11,
            "departureTime": "2020-06-10T06:52",
            "arrivalTime": "2020-06-10T08:07",
            "companyId": 14490
            "transportNumber": "AF 7710"
            "fareCategory": "WCH"
          }
        ],
      ],
  }

Trips represent the available routes from one city to another. On the other hand, the departure and arrival points are stations Station.

The departure and arrival times are always given in local time.

Trips have a unique 'tripId' which will be used for redirecting the user to Kombo website.

In the given example, the SNCF train leaves from Station 28845, Gare du Nord, belonging to the City 1, Paris. The arrival is at Station 11, Gare Lille-Europe, belonging to the City 11, Lille.

The price is always given for all passengers and not per person.

Structure

attribute	kind	Optionnal	Description
tripId	string(200)	No	The unique identifier of the trip
price	int	No	Price in cents & Euro for all the passengers
segments	segment[]	No	list of all segment of the trip (up to 4)

Segment

attribute	kind	Optionnal	Description
departureStationId	int	No	The id of the departure station
arrivalStationId	int	No	The id of the arrival station
departureTime	string(16)	No	Departure time in local time
arrivalTime	string(16)	No	Arrival time in local time
companyId	int	No	Id of the company providing the trip
transportNumber	string	Yes	train, flight, bus number
fareCategory	string	Yes

City

get All

curl "https://turing.kombo.co/city"
  -H "token: MySecretToken"

[
   {
      "id":1,
      "name":"Paris",
      "latitude":"48.856600",
      "longitude":"2.351830",
      "country":{
         "code":"FR"
      },
      "stations":[
         {
            "id":1,
            "name":"Bercy",
            "latitude":"48.838402",
            "longitude":"2.382410",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":51,
            "name":"La Défense",
            "latitude":"48.891499",
            "longitude":"2.242440",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":91,
            "name":"Porte Maillot",
            "latitude":"48.880798",
            "longitude":"2.283040",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":347,
            "name":"Charenton",
            "latitude":"48.812000",
            "longitude":"2.398700",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":348,
            "name":"Gare routière de Gallieni",
            "latitude":"48.865101",
            "longitude":"2.415110",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":414,
            "name":"Porte d'Orléans",
            "latitude":"48.821098",
            "longitude":"2.325470",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":520,
            "name":"Massy-Palaiseau - Gare TGV",
            "latitude":"48.726101",
            "longitude":"2.257140",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":667,
            "name":"Saint-Denis Université",
            "latitude":"48.946499",
            "longitude":"2.364420",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":799,
            "name":"Ibis Clichy Batignolles",
            "latitude":"48.891899",
            "longitude":"2.316460",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":805,
            "name":"Stade de France",
            "latitude":"48.924500",
            "longitude":"2.360170",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":813,
            "name":"Bibliothèque Sainte Geneviève",
            "latitude":"48.847198",
            "longitude":"2.345990",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":814,
            "name":"Métro Château Landon",
            "latitude":"48.878502",
            "longitude":"2.362070",
            "cityId":1
         },
         {
            "id":819,
            "name":"Place de la Concorde",
            "latitude":"48.865799",
            "longitude":"2.321420",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":866,
            "name":"Gare Montparnasse",
            "latitude":"48.839298",
            "longitude":"2.320580",
            "transportType":["train"],
            "cityId":1
         },
         {
            "id":867,
            "name":"Aéroport Charles de Gaulle",
            "latitude":"48.851101",
            "longitude":"2.301180",
            "transportType":["flight"],
            "iataCode":"CDG",
            "cityId":1
         }
      ]
   }
]

GET /city

Use to retrieve all the cities in the database.

get by id

curl "https://turing.kombo.co/city/15"
  -H "token: MySecretToken"

{
   "id":15,
   "name":"Marseille",
   "latitude":"43.296300",
   "longitude":"5.369890",
   "country":{
      "code":"FR"
   },
   "stations":[
      {
         "id":15,
         "name":"Gare Marseille Saint-Charles",
         "latitude":"43.303600",
         "longitude":"5.380000",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":580,
         "name":"Aéroport Marignane",
         "latitude":"43.443802",
         "longitude":"5.212500",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":737,
         "name":"Port",
         "latitude":"43.299198",
         "longitude":"5.363610",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":6551,
         "name":"Boulevard Garibaldi",
         "latitude":"43.297001",
         "longitude":"5.381070",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":31880,
         "name":"Marseille Blancarde",
         "latitude":"43.296101",
         "longitude":"5.406390",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":31899,
         "name":"Saint-Louis-Les-Aygalades",
         "latitude":"43.345600",
         "longitude":"5.365280",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":31900,
         "name":"Le Canet",
         "latitude":"43.333599",
         "longitude":"5.383330",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":31901,
         "name":"St Barthelemy",
         "latitude":"43.323299",
         "longitude":"5.392220",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":31908,
         "name":"Ste Marthe En Provence",
         "latitude":"43.339199",
         "longitude":"5.390560",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":35450,
         "name":"Gare SNCF SEON ST HENRY",
         "latitude":"43.362400",
         "longitude":"5.339960",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":35451,
         "name":"Gare SNCF LA POMME",
         "latitude":"43.290501",
         "longitude":"5.441320",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":35504,
         "name":"Gare SNCF ARENC-EUROMEDITERRANEE",
         "latitude":"43.313202",
         "longitude":"5.367620",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":35513,
         "name":"Gare SNCF PICON BUSSERINE.",
         "latitude":"43.331001",
         "longitude":"5.392750",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":35514,
         "name":"Gare SNCF SAINT ANTOINE",
         "latitude":"43.369598",
         "longitude":"5.357810",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":35515,
         "name":"Gare SNCF ST JOSEPH LE-CASTELLAS",
         "latitude":"43.351898",
         "longitude":"5.377070",
         "transportType":["train"],
         "cityId":15
      },
      {
         "id":35523,
         "name":"Gare SNCF LA BARASSE",
         "latitude":"43.285801",
         "longitude":"5.484510",
         "transportType":["train"],
         "cityId":15
      }
   ]
}

GET /city/{id}

Use to retrieve one City by its id.

parameter	kind	Example	Description
id	int	1

Station

get All

curl "https://turing.kombo.co/station"
  -H "token: MySecretToken"

    [
    {
    "id": 1,
    "name": "Bercy",
    "latitude": "48.838402",
    "longitude": "2.382410",
    "transportType": ["train"],
    "cityId": 1
    },
    {
    "id": 2,
    "name": "CDG Terminal 3",
    "latitude": "49.009899",
    "longitude": "2.559320",
    "transportType": ["train"],
    "cityId": 533
    },
    {
    "id": 3,
    "name": "Central station",
    "latitude": "41.978600",
    "longitude": "2.817060",
    "transportType": ["train"],
    "cityId": 3
    },
    ]

GET /station

Use to retrieve all the stations in the database.

get by id

curl "https://turing.kombo.co/station/1"
  -H "token: MySecretToken"

  {
    "id": 1,
    "name": "Bercy",
    "latitude": "48.838402",
    "longitude": "2.382410",
    "transportType": ["train","bus"],
    "cityId": 1
  }

GET /station/{id}

Use to retrieve one station by its id.

parameter	kind	Example	Description
id	int	1

Company

get All

curl "https://turing.kombo.co/company"
  -H "token: MySecretToken"

[
   {
      "id":2,
      "name":"Flixbus",
      "transportType":"bus"
   },
   {
      "id":3,
      "name":"Air France",
      "transportType":"flight"
      "iataCode":"AF"
   },
   {
      "id":5,
      "name":"Alsa",
      "transportType":"bus"
   },
   {
      "id":6,
      "name":"Isilines",
      "transportType":"bus"
   },
   {
      "id":7,
      "name":"Eurolines",
      "transportType":"bus"
   }
]

GET /company

Use to retrieve all the companies in the database.

get by id

curl "https://turing.kombo.co/company/2"
  -H "token: MySecretToken"

{
   "id":2,
   "name":"Flixbus",
   "transportType":"bus"
}

GET /company/{id}

Use to retrieve one Company by its id.

parameter	kind	Example	Description
id	int	1

Search

Request a search

curl "https://turing.kombo.co/search/1/11/2020-06-10/1"
  -H "token: MySecretToken"

{
  "key": "07823762-5b81-4721-81f7-a4ed4e30740b"
}

GET /search/{departureCityId}/{arrivalCityId}/{date}/{passengers}

Request for a search from a City to another one for a given date with a specific number of passenger.

As we are querying all operator's systems, results will not be immediate. This is why you will receive a key as a response. You will then use it to call the endpoint /pollSearch to retrieve progressively the results.

parameter	kind	Example	Description
departure_city_id	int	1	Departure city ID of the trip
arrival_city_id	int	11	Arrival city ID of the trip
date	string(10)	2020-10-29	Date at the format YYYY-MM-DD
passengers	int	1	Number of passenger

Collect trips

curl "https://turing.kombo.co/pollSearch/07823762-5b81-4721-81f7-a4ed4e30740b"
  -H "token: MySecretToken"

{
   "trips":[
      {
         "tripId":"100100baw50qbp2l00qbpdgo020100eg",
         "price":520,
         "segments":[
            [
               {
                  "departureStationId":1,
                  "arrivalStationId":11,
                  "departureTime":"2020-06-10T07:15",
                  "arrivalTime":"2020-06-10T11:10",
                  "companyId":14117
               }
            ]
         ]
      }
   ],
   "completed":true,
   "dependencies":{
      "stations":{
         "1":{
            "id":1,
            "name":"Bercy",
            "latitude":"48.838402",
            "longitude":"2.382410",
            "cityId":1
         },
         "11":{
            "id":11,
            "name":"Gare Lille-Europe",
            "latitude":"50.638500",
            "longitude":"3.077060",
            "cityId":11
         }
      },
      "cities":{
         "1":{
            "id":1,
            "name":"Paris",
            "latitude":"48.856600",
            "longitude":"2.351830",
            "country":{
               "code":"FR"
            }
         },
         "11":{
            "id":11,
            "name":"Lille",
            "latitude":"50.637200",
            "longitude":"3.063330",
            "country":{
               "code":"FR"
            }
         }
      },
      "companies":{
         "14117":{
            "id":14117,
            "name":"BlaBlaBus",
            "transportType":"bus"
         }
      }
   }
}

GET /pollSearch/{key}

Retrieve the results of your search after having called /search endpoint.

The response contains a property completed, meaning that you should call this endpoint with the associated key until this property take the value true. Beware that everytime you query this endpoint and retrieve results, the result list is then cleared - meaning that next calls to pollSearch will not contain them anymore. In other words, you will never poll twice the same trip.

We advise you to call this endpoint every 500ms.

The response always contains all the associated static data dependencies : cities, stations and companies.

parameter	kind	Example	Description
key	string	07823762-5b81-4721-81f7-a4ed4e30740b	RFC4122 UUIDs

Redirection

redirect the user to Kombo

"https://www.kombo.co/affilate/1111/fr/2/100100baw50qbp2l00qbpdgo020100eg"

www.kombo.co/affilate/{affilateId}/{locale}/{passengers}/{tripId}

Url to which the user should be redirected in order to complete its booking. No POST method needed, the URL will lead the customer to a page with the trip already put in cart. A cookie with the source of traffic will also be set.

parameter	kind	Example	Description
affilateId	int	1234	your affiliate number - linked to your token
locale	string(2)	fr	ISO 3166 - language website destination
passengers	int	1	Number of passengers
tripId	string(200)	100100baw50qbp2l00qbpdgo020100eg	The unique identifier of the trip

Errors

Here are the HTTP code you can meet :

Error Code	Meaning
200	OK -- When everything goes well.
400	Bad Request -- Error during process.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified URL could not be found.
422	Bad Request -- Your request sucks.
500	Internal Server Error -- Oops, we had a problem. No one's perfect. We will have a look asap.