Get Bus Trips

This API Endpoint makes a POST request to the Travu API service in other to get a response of AVAILABLE BUS TRIPS from all our aggregated Bus operators based on the requested DEPARTURE STATE, DESTINATION STATE and DATE.

ENDPOINT URL

REQUEST TYPE: POST

LIVE URL: https://api.travu.africa/api/v1/check_trip

TEST URL: https://api.travu.africa/test/api/v1/check_trip

Remember to Pass your Authorization Token for this request to go through, read about Authorization here.

BODY PAYLOAD

The Body Payload format is as below;

{
    "departure_state": "Supported string e.g ABIA",
    "destination_state": "Supported string e.g LAGOS",
    "trip_date": "date(YYYY-MM-DD)e.g 2021-07-04",
    "sort": "(Optional) if you need to uniform response based on departure date, use 'date'"
}

Our Supported States Strings (UPPERCASE SENSITIVE) to be used for both departure_state and destination_state are;

ABIA, ADAMAWA, AKWA IBOM, ANAMBRA, BAUCHI, BAYELSA, BENUE, BORNO, CROSS RIVER, DELTA, EBONYI, EDO, EKITI, ENUGU, GOMBE, IMO, JIGAWA, KADUNA, KANO, KATSINA, KEBBI, KOGI, KWARA, LAGOS, NASARAWA, NIGER, OGUN, ONDO, OSUN, OYO, PLATEAU, RIVERS, SOKOTO, TARABA, YOBE, ZAMFARA, FCT (ABUJA), LOME, COTONOU, ACCRA.

Below is an actual request made and it's response.

Check Trip Request

POST https://api.travu.africa/api/v1/check_trip

This API Endpoint makes a POST request to the MytripAPI service in other to get a response of AVAILABLE BUS TRIPS from all our aggregated Bus operators based on the requested DEPARTURE STATE, DESTINATION STATE and DATE.

Request Body

Name	Type	Description
departure_state*	LAGOS	Departure State
destination_state*	IMO	Destination state
trip_date*	2023-04-01	Intending date of travel
sort	String	Sorting result by an order

200: OK Data Available

{
    "error": false,
    "message": "successful",
    "info": "Data Available",
    "data": [
        {
            "provider": {
                "name": "Chisco Transport",
                "short_name": "CTL",
                "logo": "https://travu.africa/providers/ctl.jpg"
            },
            "trip_id": 320982,
            "trip_no": 8,
            "trip_date": "2023-04-01",
            "departure_time": "01/04/2023 06:00",
            "origin_id": 71,
            "destination_id": 81,
            "narration": "EMPIRE (LAGOS) TO OWERRI(IMO) ",
            "fare": 18000,
            "total_seats": 7,
            "available_seats": [
                1,
                2,
                3,
                4,
                5,
                6,
                7
            ],
            "blocked_seats": [],
            "special_seats": [],
            "special_seats_fare": "",
            "order_id": 577,
            "departure_terminal": "EMPIRE (LAGOS)",
            "destination_terminal": "OWERRI(IMO) ",
            "vehicle": "1+2, Seater, AC, Non-Video",
            "boarding_at": "119",
            "departure_address": "3 Agege motor Road",
            "destination_address": "24 Egbu Road"
        },
        {
            "provider": {
                "name": "ABC Transport",
                "short_name": "ABC",
                "logo": "https://travu.africa/providers/abc.jpg"
            },
            "trip_id": 332649,
            "trip_no": 4,
            "trip_date": "2023-04-01",
            "departure_time": "01/04/2023 06:45",
            "origin_id": 24,
            "destination_id": 32,
            "narration": "LAGOS BOLADE OSHODI TO MBAISE",
            "fare": 15000,
            "total_seats": 14,
            "available_seats": [
                1,
                2,
                3,
                4,
                5,
                6,
                7,
                8,
                9,
                10,
                11,
                12,
                13,
                14
            ],
            "blocked_seats": [],
            "special_seats": [],
            "special_seats_fare": "",
            "order_id": 253,
            "departure_terminal": "LAGOS BOLADE OSHODI",
            "destination_terminal": "MBAISE",
            "vehicle": "2+2, Sprinter Service, AC, Non-Video",
            "boarding_at": "55",
            "departure_address": "129 Agege Motor Road",
            "destination_address": "Alpha Paradise Hotel By Ahiara Junc."
        },
        {
            "provider": {
                "name": "Chisco Transport",
                "short_name": "CTL",
                "logo": "https://travu.africa/providers/ctl.jpg"
            },
            "trip_id": 321280,
            "trip_no": 8,
            "trip_date": "2023-04-01",
            "departure_time": "01/04/2023 07:00",
            "origin_id": 63,
            "destination_id": 81,
            "narration": "ALABA (LAGOS)  TO OWERRI(IMO) ",
            "fare": 22000,
            "total_seats": 7,
            "available_seats": [
                1,
                2,
                3,
                4,
                5,
                6,
                7
            ],
            "blocked_seats": [],
            "special_seats": [],
            "special_seats_fare": "",
            "order_id": 908,
            "departure_terminal": "ALABA (LAGOS) ",
            "destination_terminal": "OWERRI(IMO) ",
            "vehicle": "1+2, Seater, AC, Non-Video",
            "boarding_at": "120",
            "departure_address": "26 Ojo-Igbede Road, By Chemist Bus/stop",
            "destination_address": "24 Egbu Road"
        }
    ]
}

401: Unauthorized

{
    "status": 401,
    "message": "Missing authorization key"
}

200: OK No Trips Found

{
    "error": true,
    "message": "FAILED: No trips found",
    "info": "No trips found",
    "data": []
}

Here is an Extra endpoint to help you with this, Get List of States

RESPONSE

The Response for this request should bring the TRIP DETAILS in the below format if the sort parameter is sent as empty or not included in the payload entirely.;

{
    "GUO": {
        "error": false,
        "message": "successful",
        "info": "Data Available",
        "data": [
            {
                "provider": {
                    "name": "GUO Transport",
                    "short_name": "GUO"
                },
                "boarding_at": "28",
                "trip_id": 96861,
                "trip_no": 450096861,
                "trip_date": "2021-07-10",
                "depature_time": "2018-04-24 08:04:00",
                "origin_id": "",
                "destination_id": 63,
                "narration": "UMUAHIA - LAGOS - AJAH",
                "fare": 6500,
                "total_seats": 15,
                "available_seats": [
                    1,
                    2,
                    3,
                    4,
                    5,
                    6,
                    7,
                    8,
                    9,
                    10,
                    11,
                    12,
                    13,
                    14,
                    15
                ],
                "blocked_seats": [
                    2,
                    3
                ],
                "special_seats": [],
                "special_seats_fare": "",
                "order_id": "eef50d24",
                "departure_terminal": "UMUAHIA",
                "destination_terminal": "LAGOS - AJAH",
                "vehicle": "Hiace - 1st Bus (15)"
            },
            {
                "provider": {
                    "name": "GUO Transport",
                    "short_name": "GUO"
                },
                "trip_id": 96861,
                "trip_no": 450096861,
                "trip_date": "2021-07-10",
                "depature_time": "2018-04-24 08:04:00",
                "origin_id": "",
                "destination_id": 63,
                "narration": "UMUAHIA - LAGOS - AJAH",
                "fare": 7000,
                "total_seats": 15,
                "available_seats": [
                    1,
                    2,
                    3,
                    4,
                    5,
                    6,
                    7,
                    8,
                    9,
                    10,
                    11,
                    12,
                    13,
                    14,
                    15
                ],
                "blocked_seats": [
                    2,
                    3
                ],
                "special_seats": [],
                "special_seats_fare": "",
                "order_id": "0e2c886c",
                "departure_terminal": "UMUAHIA",
                "destination_terminal": "LAGOS - AJAH",
                "vehicle": "Hiace - 1st Bus (15)"
            }
        ]
    },
    "ABC": {
        "error": true,
        "message": "failed",
        "info": "Terminals does not exist between states",
        "data": []
    }
}

ALSO: The Response for this request should bring the TRIP DETAILS in the below format if the sort parameter is sent as "date", this combines all results based on the departure time.

{
    "error": false,
    "message": "successful",
    "info": "Data Available",
    "data": [
        {
            "provider": {
                "name": "ABC Transport",
                "short_name": "ABC"
            },
            "trip_id": 26528,
            "trip_no": 4,
            "trip_date": "2022-01-09",
            "departure_time": "09/01/2022 06:00",
            "origin_id": 13,
            "destination_id": 25,
            "narration": "GWAGWALADA TO LAGOS JIBOWU",
            "fare": 14350,
            "total_seats": 14,
            "available_seats": [
                0,
                10,
                11,
                12,
                13,
                14
            ],
            "blocked_seats": [],
            "special_seats": [],
            "special_seats_fare": "",
            "order_id": 20,
            "departure_terminal": "GWAGWALADA",
            "destination_terminal": "LAGOS JIBOWU",
            "vehicle": "2+2, Sprinter Service, AC, Non-Video",
            "boarding_at": "10",
            "departure_address": "Ground Floor wing B Kaita Plaza, by Mtnoffice cls toJeparo Hotel",
            "destination_address": "22 IKORODU ROAD JIBOWU"
        },
        {
            "provider": {
                "name": "GUO Transport",
                "short_name": "GUO"
            },
            "trip_id": 482850,
            "trip_no": 30482850,
            "trip_date": "2022-01-09",
            "departure_time": "09/01/2022 20:01",
            "origin_id": "",
            "destination_id": 64,
            "narration": "UTAKO - LAGOS - COKER",
            "fare": 10500,
            "total_seats": 59,
            "available_seats": [
                10,
                11,
                12,
                13,
                14
            ],
            "blocked_seats": [],
            "special_seats": [],
            "special_seats_fare": "",
            "order_id": "de5426cf",
            "departure_terminal": "UTAKO",
            "destination_terminal": "LAGOS - COKER",
            "vehicle": "Luxury - 1st Bus (59)",
            "boarding_at": "",
            "departure_address": "Gouba Plaza, Plot171, Ekukinam Street, Utako District, Abuja.",
            "destination_address": "LAGOS - COKER Terminal"
        }
    ]
}

Always convert these response values (Strings and Integers) into Strings so as to always correspond as our responds might return those values in either form.

The above responses are an example of a situation where One operator has available trip (GUO in this case) and the other does not operate around that route.

Reference to Authentication for possible authentication errors that might occur during this request.

Seat Layout

The next thing you want to do is present the seat layouts to your users in our supported formats, this enables your users pick specific seats and positions from a bus.

Here is the documentation that helps you with this, Seat Layouts