How To Build a U.S.S.D. Bus Booking System

Bus

Introduction

The project looks into how you can use Africa’s Talking U.S.S.D to create a Bus Booking System, this can be done when a travel company would like its customers to book their buses for travelling via U.S.S.D, therefore, providing convenience to its clientele.

This will allow transport companies to have an efficient way for allowing their clients to book trips; we could also modify the system to send SMS shortcodes to the clients informing them that the booking was successful as well as a reference code or receipt upon payment of the transport fees.  

Intended audience: Who the article is for

This article targets python/Django developers who would want to build a web-based bus booking system that allows clients to book trips in advance and extend this project to use Africa’s Talking SMS shortcodes to send reminders to clients regarding their upcoming trips.

Case Study: What the article is going to cover

The project will display two use cases: building a web-based Django fleet bus booking system and the second being; building an A.P.I that will interact with Africa’s Talking U.S.S.D. A.P.I.

The application is built using python programming language in Django Framework.

Requirements:

  1. Some knowledge of Python and Django
  2. A website domain name for your Django project
  3. Africa’s Talking U.S.S.D. A.P.I.

Acquiring a website domain name for your Django project

The reason we need a website domain for the Django project is because the U.S.S.D. A.P.I. requires us to set the URL of the Django web app that’s hosting the A.P.I to be used as a call back when a user initiates the U.S.S.D call.

Since the Django project will be developed and hosted on our local computer, it is only accessible via the URL http://127.0.0.1:8000, with this URL the Django project in your local computer cannot be accessed on the internet. So we need to find a way for our Django project A.P.I. to be accessible via the web. To do so we will use a free downloadable software called Ngrok. i.e. http://127.0.0.1:8000 is the same as http://localhost:8000

Ngrok is an application that creates a dummy http URL that we will use to map to http://127.0.0.1:8000 (where the Django project is running) e.g. Ngrok could create a dummy URL http://d9b253d6e13b.ngrok.io and map it to http://127.0.0.1:8000, so when any user online enters the dummy URL on their browser they will be able to view the Django project and it’s A.P.I. can be accessed via Africa’s Talking online U.S.S.D. A.P.I.

Steps:

  1. Download the ngrok software from their website here: https://dashboard.ngrok.com/get-started/setup, on this page. You will then be prompted to sign up to download the application, go ahead and do so.
  2. After signing up you will see the page below:
  1. Download and start/run the application
  2. After running the Ngrok application, you will see the terminal below:
  1. Go back to the Ngrok web page that is displayed above and navigate to the section labelled “Connect your account”
  2. Copy the ngrok code provided in the “Connect your account” section onto the Ngrok terminal; this is so that the dummy URL you will create does not expire after a short period, after which you will have to create another dummy U.R.L.
  3. Since we want to map the localhost port 8000 to a dummy URL, go back to the Ngrok terminal and type the command “ngrok http 8000”, this will open the ngrok shell below with the name of the newly created dummy http URL, e.g. http://d9b253d6e13b.ngrok.io that maps -> to the http://localhost:8000 port where your Django project will be running from
  1. You will need the generated dummy ngrok URL while creating Africa’s Talking U.S.S.D. A.P.I.

Creating Africa’s Talking U.S.S.D. A.P.I.

Steps:

  1. Navigate to this URL: https://account.africastalking.com/apps/sandbox/ussd/codes you will be required to sign in or sign up if you don’t have an account with Africa’s Talking
  2. While on that page click on the link labelled “create a channel” to create a USSD code
  3. You will be prompted with the pop up below:
  1. Enter a unique dummy channel e.g 12345
  2. Your U.S.S.D. Code is now e.g. *384*12345#
  3. In the callback URL paste the ngrok http URL you created above; after appending “/api/ussd_callback/” at the end of the URL e.g. http://d9b253d6e13b.ngrok.io/api/ussd_callback/ we will create this “/api/ussd_callback/” A.P.I later on in the Django project.
  4. Click on Create Channel

Getting started with the Web App

Creating a Django Project

  1. From your terminal, navigate to the folder/location your project is to reside.
  2. We will create a Django project called “djangobusbookingsystem”, type the command: django-admin startproject djangobusbookingsystem
  3. From the terminal, navigate into the created project folder, where you will create and activate your project’s virtual environment by typing in the terminal the command “python –m venv venv”
  4. In windows, type “venv\Scripts\activate” in the terminal.
  5. In Mac/Linux, type ”source venv/bin/activate” in the terminal.
  6. After your virtual environment has been activated, run the code below in the terminal to install the following python packages:
    • “pip install requests” : python package used in managing HTTP requests
    • “pip install djangorestframework”: python package used in creating REST A.P.I.s
    • “pip install django” : python package to be used in building the web app
    • “pip install django-crispy-forms”  : to be used in rendering bootstrap styles in HTML templates
  7. Create your first Django app by typing in the terminal the command: “python manage.py startapp fleet”
  8. Create an SQLite database that will be used by the project by typing in the terminal the command: “python manage.py makemigrations”
  9. Apply database changes by typing in the terminal the command: “python manage.py migrate”
  10. Start your server by typing on the terminal the command: “python manage.py runserver”
  11. If the server starts successfully there should be a webpage up and running on the location: http://127.0.0.1:8000
  12. While in the terminal, type Ctrl+C to stop the server
  13. Everything from now on will be performed inside this python activated environment.

We are stopping the server so that we can create the database tables first and then apply the changes before restarting the server

Creating Project CSS File

  1. Open the Django project folder your code editor
  2. Open the “fleet” app folder
  3. In the “fleet” app folder, create a folder labelled “static”
  4. Inside the created “static” folder, create another folder labelled “fleet”
  5. Inside the “fleet” folder just created inside the “static” folder, create a css file labelled “main.css”
  6. Copy the code below into the “main.css” file

Configure Django Project Settings

  1. Open your Django project folder: “djangobusbookingsystem”
  2. Locate a folder with a similar name to your Django project folder, this folder is in the same directory as your “fleet” app folder
  3. Inside this folder is a python file labelled “settings.py”
  4. Open the “settings.py” file and locate the python variable ALLOWED_HOSTS, which is a python list located close to the start of the file
  5. Inside the ALLOWED_HOSTS, enter the ngrok URL created as well as the localhost URL, this is a security measure by Django to ensure that the web app can only be accessed via the set URLs. Below is an example of how to do so:
  1. Inside the “settings.py” file, locate the variable INSTALLED_APPS
  2. The variable installed_apps is a list where you will register the apps we just created
  3. Insert the code below inside the list:
  1. We also need to register the Django crispy form python package that we will use to beautify our HTML pages, inside the INSTALLED_APPS python list paste the code below:
  1. We also need to register the Django rest framework app that we will use to manage and create the project A.P.I.s, inside the INSTALLED_APPS python list, paste the code below:
  1. We also need to inform crispy to use bootstrap 4 in its rendering of HTML elements, to do this paste the code below at the end/bottom of the settings.py file:
  1. Data is sent from Africa’s Talking U.S.S.D. A.P.I. to our Django project A.P.I. in the form “Content-Type: application/x-www-form-urlencoded”. We have to inform our Django A.P.I. to expect data to be sent to it in this format as the default format Django rest framework A.P.I. expects data in JSON format.
  2. Data should also be sent back from our Django A.P.I. to Africa’s Talking USSD A.P.I. in a string format or as a plain text. Django rest framework A.P.I. sends data out in JSON format by default, we have to inform or configure our A.P.I. to send data in plain text and not JSON format.
  3. To perform the above actions paste the code below at the bottom or end of the settings.py file:

Creating Database Tables

  1. Open your Django project folder in your code editor
  2. We now create the database tables related to the “fleets” app we created, which are:

Destinations Table Logic

This table will hold the destinations offered by the fleet details and will inherit from the built-in Django “models.Model” class that is used to convert a python class to a database table. It will have the following fields:

name –This column will hold the name of the destination

__str__ –This is a method in the class “Destinations” class we will create responsible for returning the string representation of objects or table records created in the Destinations table. The string representation method we will return is the name of the destination

Routes Table Logic

This table will hold the routes that head to each destination and will inherit from the built-in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

destination –This column will create a relationship with the destination table on the specific service route that heads there

start – This column will hold the name of where the route will start from e.g. Nakuru

__str__ –This is a method in the class “Routes” class we will create responsible for returning the string representation of objects or table records created in the “Routes” table. The string representation method we will return is the name of where the route starts and ends e.g. Nakuru to Nairobi.

Routes Travel Dates Table Logic

This table will hold the dates when each route is travelled to a specific destination and will inherit from the built in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

route –The route and to a specific destination

travel_date – The date the route will be travelled

__str__ – This is a method in the class “RoutesTravelDates” class we will create responsible for returning the string representation of objects or table records created in the “RoutesTravelDates” table. The string representation method we will return is the full route, where it starts to where it ends and when it will be travelled.

Bookings Table Logic

This table will hold the bookings made, the route that was booked and the phone number of the client and will inherit from the built in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

route_date – The date the route will be travelled

phone_number – The phone number of the client booking the bus route

__str__ – This is a method in the class “Bookings” class we will create responsible for returning the string representation of objects or table records created in the “Bookings” table. The string representation method will return is the phone number and the bus route booked.

To create the above “fleet” tables in your project folder, navigate into the “fleet” folder and open a file labelled “models.py” and paste the code below:

Apply Database Changes

  1. In your terminal, ensure you have activated your project’s virtual environment
  2. While in your projects activated virtual environment in your terminal
  3. Create database changes to be made by typing in the terminal the command: python manage.py makemigrations
  4. Apply database changes by typing in the terminal the command: python manage.py migrate

Creating your business logic for Fleet App

We will now create the business logic in the “views.py” file located in the “fleet” app folder. Below is how to do so:

  1. Open the “fleet” app folder
  2. Locate a python file labeled “views.py”
  3. Paste the code below

Views Code Logic

We start by importing the following methods:

  • Reverse – This method is used to return the URL representation of the python URL pattern pathname
  • Render – This method is used to return an HTML page to the user
  • CreateView – This is a Django built-in class that can be used to create a database table entry by associating it with another class
  • UpdateView– This is a Django built-in class that can be used to update a database table entry by associating it with another class
  • ListView – This is a Django built-in class that can be used to return a list of records from a specified database table, hence converting the class inheriting from this class to a list view to be used on an HTML page
  • DeleteView – This is a Django built-in class that can be used to delete a database record entry by associating it with another class, via inheriting from this class
  • Destinations, Routes, RoutesTravelDates and Bookings – The four fleet database tables or models we created

We now build the views/functions or methods below:

  • Home – This is a method or function view that accepts a web request and returns back the index HTML page render
  • Destinations Create View – This is a class-based view or a class that inherits its functionalities from django’s built-in “CreateView” class. In this class we have to specify the model or database table the class will work with which is the “Destinations”, the fields it’s to work with which is the ‘name’, the template that will render the data/form.

The class will also override its superclass method “get_context_data”, what this method does, is that, it allows us to get access to the data that will be passed to the template before it’s sent to the template for rendering, the data is passed as a context object. After getting access to the context we add a new object variable with a value in it and return the context back.

We also override a superclass method called “get_success_url” that will be used to return the URL page a user is to be redirected to after they successfully create a destination in the database.

  • Destinations List View – This is a class-based view or a class that inherits its functionalities from another class view, in this case django’s built in “ListView” class. In this class we have to specify the model or database table the class will work with which is the “Destinations” and the template that will render the data.

The class will also override its superclass method “get_context_data”, so as to allow us to get access to the data that will be passed to the template.

  • Destinations Delete View – This is a class-based view or a class that inherits its functionalities from another class view, in this case, django’s built in “DeleteView” class. In this class, we have to specify the model or database table the class will work with which is the “Destinations”, set a success URL, that is the URL a user is redirected to after successful data deletion and the template will render the data.

The class will also override its superclass method “get_context_data”, to allow us to get access to the data that will be passed to the template.

  • Destinations Update View – This is a class-based view or a class that inherits its functionalities from another class view, in this case, django’s built-in “UpdateView” class. In this class, we have to specify the model or database table the class will work with which is the “Destinations”, the fields it’s to work with, which is the ‘name’ field, the template that will render the data/form.

The class will also override its superclass method “get_context_data”, to allow us to get access to the data that will be passed to the template. The above views will also be replicated in the creation of the Routes, Routes Travel Dates and Bookings views.

Creating the Django Project A.P.I.

This is the A.P.I. that will interact with Africa’s Talking U.S.S.D. A.P.I.

Steps:

  1. Inside your Django project folder: “djangobusbookingsystem”
  2. Create a folder called “api” which will be in the same directory as your “fleet” app folder
  3. Inside this ”api” folder create the following files:
    • __init__.py –  an empty python file to inform Django that “api” folder is a python package
    • renders.py – a python file that will be used to inform Django rest framework how to render or send data back to Africa’s Talking U.S.S.D. A.P.I below is the code to paste inside this file:
    • urls.py – a python file that will be used to map the Django project A.P.I. inside the views.py file to a URL that will be accessed by the Africa’s Talking U.S.S.D. A.P.I. below is the code to paste inside this file:
    • views.py – a python file that will hold the A.P.I. method that is responsible for sending back data below is the code to paste inside this file:

Creating “Fleet” HTML Templates

  1. On these HTML templates are where the different users’ data will be displayed
  2. We will start by creating HTML templates related to the “fleet” app we created, which are:
    • index.html – The default home page for the web app with brief instructions on how the web app works
    • base.html – This is the page that will be inherited/extended by all other HTML template pages
    • confirm_delete.html – This is the page to be used for asking a user to confirm that they want to delete a specific data record
    • bookings_detail.html – This page will be used to display the details of the travel bookings made
    • bookings_list.html – This page will be used to display a list of bookings made
    • routes_detail.html – This page will be used to display the details of specific routes that lead to a set destination
    • routes_list.html – This page will be used to display a list of the routes
    • route_dates_detail.html – This page will be used to display the details of the dates travelled by bus on a specific route
    • route_dates_list.html – This page will be used to display a list of dates set aside for travel on a route
  3. To create the above “fleet” HTML templates do the following:
    • In your project folder navigate into the “fleet” folder
    • Create a folder labelled “templates”
    • Inside the “templates” folder create another folder and label it “fleet”
    • Inside the “fleet” folder you have just created inside the “templates” folder
    • Create the following blank HTML pages; index.html, base.html, confirm_delete.html, bookings_detail.html, bookings_list.html, destination_list.html, destinations_detail.html, route_dates_detail.html, route_dates_list.html, routes_list.html and routes_detail.html.

Below is a screenshot of the “fleet” directory tree:

  1. Below are the HTML codes to be placed on each HTML page:

Creating the “Fleet” App URLs

These are the URLs that will be used by the user to navigate the “fleet” web app. They are usually placed in a file called “urls.py”. Do the following to create/edit this file:

  1. Open the “fleet” app folder
  2. Locate/create a python file labeled “urls.py”
  3. Paste the code below

Configure Project URLs

This is where the URLs that point to each Django app and A.P.I. are placed so that they are accessible from a browser. They are usually placed in a file called “urls.py”. Do the following to create/edit this file:

  1. Open your Django project folder: “djangobusbookingsystem”
  2. Locate a folder with a similar name to your Django project folder, this folder is in the same directory as your “fleet” app folder
  3. Open the “djangobusbookingsystem” folder that is inside Django project folder
  4. Locate/create a python file labeled “urls.py”
  5. Paste the code below

Project Tree

Below is a screenshot of how your project tree should look like, assuming the name of your Django project is “djangobusbookingsystem”:

Run the server

  1. cd/navigate into the “djangobusbookingsystem” Django project via the terminal
  2. Activate the virtual environment by typing the command: “venv\Scripts\activate”
  3. Start the server by typing the command: python manage.py runserver
  4. If there’s nothing wrong, the server should be up on http:127.0.0.1:8000

Testing the System

  1. Once the server is up
  2. Go to the web page address e.g. http://127.0.0.1:8000 or to the ngrok URL you had created
  3. Follow the instructions on the home page on how to test the system

NB: If you had quit or closed the ngrok terminal, after creating the URL, restarting the ngrok app terminal will lead to the creation of a new ngrok URL. You will need to update Africa’s Talking U.S.S.D. A.P.I. call back with this new URL and you will also need to update the python variable ALLOWED_HOSTS inside the settings.py file located inside the folder labeled “djangobusbookingsystem”

Conclusion

You should now have a basic understanding of how Africa’s Talking U.S.S.D. A.P.I. works and how to implement them it python, while working in Django.

Further improvements could be done on the project such as, allowing clients to be notified regarding a successful booking via short code with a reference number.

Finally, you can find the code snippets in this @repo.

Quick Guide

If you just want to clone the project and get it up running, below is how to do so in minutes:

  1. Clone it:
    • git clone https://bitbucket.org/dans0l/djangobusbookingsystem.git
  2. Cd into it:
    • cd djangobusbookingsystem
  3. Create a venv:
    • python3 -m venv venv
  4. Activate venv:
    • Mac/Linux: source venv/bin/activate
    • Windows: venv\Scripts\activate
  5. Install the requirements:
    • pip install -r requirements.txt
  6. Create DB
    • python manage.py makemigrations
  7. Apply DB Changes:
    • python manage.py migrate
  8. Create a Ngrok URL:
    • Download the ngrok software from their website here: https://dashboard.ngrok.com/get-started/setup, on this page they you will be prompted to sign up to download the application, go ahead and do so.
    • Download and start/run the application
    • After running the Ngrok application you will see the ngrok terminal window
    • Go back to the Ngrok web page where you downloaded the application (the link is displayed above) and navigate to the section labeled “Connect your account”
    • Copy the ngrok code provided in the “Connect your account” section onto the Ngrok terminal
    • Inside the Ngrok terminal, type the command “ngrok http 8000”
    • A ngrok shell window will be displayed, with the name of the newly created ngrok http URL e.g. http://d9b253d6e13b.ngrok.io
    • Do not close or quit this ngrok shell
  9. Configure your Africa’s Talking U.S.S.D. A.P.I.:
    • Navigate to this URL: https://account.africastalking.com/apps/sandbox/ussd/codes you will be required to sign in or sign up if you don’t have an account with Africa’s Talking
    • While on that page click on the link labeled “create a channel” to create a USSD code
    • Enter a unique dummy channel e.g. 12345
    • Your U.S.S.D. Code is now e.g. *384*12345#
    • In the callback URL paste the ngrok http URL you created above, after appending “/api/ussd_callback/” at the end of the URL e.g. http://d9b253d6e13b.ngrok.io/api/ussd_callback/ this “/api/ussd_callback/” A.P.I. has already been created in the Django project.
    • Click on Create Channel
  10. Configure the Django Project to use the created ngrok url:
    • Open your Django project folder: “djangobusbookingsystem”
    • Locate a folder with a similar name to your Django project folder, this folder is in the same directory as your “users” app folder
    • Inside this folder is a python file labeled “settings.py”
    • Open the “settings.py” file and locate the python variable ALLOWED_HOSTS, which is a python list located close to the start of the file
    • Inside the ALLOWED_HOSTS list enter the ngrok URL you created as well as the localhost URL, it should resemble something like this: ALLOWED_HOSTS = [‘127.0.0.1′,’d9b253d6e13b.ngrok.io’]
  11. Run the server:
    • python manage.py runserver
  12. Navigate to the site: http://127.0.0.1:8000
  13. Follow the instructions on the home page to start using the site

Please let me know how your experience was, Thank you.

1 Shares:
You May Also Like