Make Your Own Co-WIN Vaccine Slot Notifier [Noobs Guide]

Co-WIN (website) is India's Vaccine registration portal. Users can find vaccine centers near them and book slots. But most of the time the slots are fully booked and it becomes really frustrating to keep refreshing the site the whole day and check when the next slots are made available.

I know there are already many telegram channels which sends slot notification but hey lets be honest... I really hate that. The channels keep sending adverts and slots info of other districts which I am least concerned with.

In this Instructable I will show you how you can make your own Co-WIN notifier using Python and run it on any android device.

So what exactly is this Slot Notifier?

Co-WIN Notifier is a Python program which runs on any Android device. This program checks for slot availability from the Co-WIN servers. When a slot is found, the program will vibrate the phone and play an alert tone. It will also pop a notification in the status bar of the phone.

Is it hard to make?

I have made this Instructable very simple. Any person with no programming knowledge can follow this Instructable and get the Slot notifier running in less than 30 minutes (even my 13 year old noob brother could!)

How my Instructable flows

• What is API and How it works
• Installing Python on your computer
• Installing some additional libraries
• Configuring the Slot Notifier Python code
• Running the program
• Configuring QPython Android app
• Getting the code ready for QPython
• Moving the files to Android
• Running the code in QPython

We will first try running the program on a computer and then move to android.

Step 1: Try Our Co-Win Notifier Windows 10 App

Before I begin with the Instructable I would like to show you guys the Co-Win Notifier Application which I made with my colleague. This is a full-fledged desktop application which checks for slots and when a slot is found the app gives a pop-up alert and also sends a notification on Telegram.

This application is Open-Sourced on GitHub https://github.com/ashvnv/co-win-notifier

Do try this app on your computer (System requirement: Windows 10 64bit) Download

In this Instructable we won't be making such complex application but a simple yet powerful tool which will do the work.

Lets get started!

Step 2: What Is API and How to Use It

Our first task is to get the slot information from Co-WIN servers. For that we are going to use the API provided in the Co-WIN site.

Before explaining API let me explain what are servers!

Servers are like normal computers which we use everyday. Only difference is that the main aim of a server is to respond to the any queries initiated by other computers. Example: Google servers. Try googling something and see the Address bar of your browser, you will most probably see https://www.google.com/ followed by some long texts with % - + and many symbols. Here www.google.com is the address of the google server and the texts following the address are the query terms. Google's servers processes this query and responds with the web-page which shows you the search results.

What is API?

API stands for Application Programming Interface. Imagine there is a server which maintains a database of movies, series, songs etc. Suppose I want some information from the server, say I want a list of series that I want to watch this weekend. Easiest way to get this information is by using API. API is an Interface between our computer and the server which helps getting information from the server easily. Usually this interface is created so that the servers can be protected from DDoS (know more) and other attacks which can make the server slow if not crash it completely. API also makes getting information from the server easier.

In this Instructable we will be using Co-WIN API for getting the slot information.

Lets make an API query

This is the API link taken from Co-WIN API documentation (read)

https://cdn-api.co-vin.in/api/v2/appointment/sessions/public/findByPin?pincode={PINCODE}&date={DATE}

Here replace {PINCODE} with your area Pincode and {DATE} with the date on which you want to check the slot availability.

TURN OFF VPN, PROXY OR ANY NETWORK APPLICATION WHICH CAN CHANGE YOUR IP LOCATION. DUE TO GEOFENCING, COWIN API CAN ONLY BE ACCESSED BY INDIAN IP ADDRESSES. SO IF YOU ARE USING A VPN CONFIGURED WITH OTHER COUNTRY, COWIN SERVERS WILL RETURN 403 ERROR FORBIDDEN ACCESS

Example:

https://cdn-api.co-vin.in/api/v2/appointment/sessions/public/findByPin?pincode=400703&date=12-6-2021

Copy the whole link and paste it in your browser's address bar and hit enter.

You should see a blank page with lots of weird texts. [Check the 2nd photo I attached with this step]

We just made a API query to cdn-api.co-vin.in (Co-WIN server) and the server responded with the slot information for the PINCODE and the DATE given with the link.

The server response is in JSON format (Java Script Object Notation). It is a data structure which helps to maintain and transfer the data in an efficient manner.

Lets make the response more readable

Copy the whole JSON text and paste it in this website https://jsonparseronline.com/. We are parsing the JSON and making it more readable [Check the 3rd photo I attached with this step]. Now you can understand the JSON response much easily. All the slot information along with vaccine name, fee, address etc was sent back to us in JSON format when we made the API query. We are going to use this API in this Instructable and search for the slots!

Step 3: Installing Python on Your Computer

We are going to make the Slot notifier using Python. Python is a very high level language which makes it much more easier to use compared to Java, C++ etc.

As I said before we will first try the program in computer then move to Android phone.

Install Python in your computer (download).

• Windows users go for Windows Installer (64 bit)
• Mac users go for universal2 Installer
• Linux users type sudo apt-get install Python in your Terminal and you guys are good to go

Make sure your PATH is right. I have shown the installation procedure for Windows with photos in this step.

To confirm the installation:

For windows open Windows PowerShell (search in start menu) and type python You should see python version number and other details printed [Check the 4th photo I attached with this step]

Same goes for Mac and Linux users

Open the Terminal and type python. You should see the installed python3 version and other details

If you are stuck anywhere follow this article:

Windows (click-here)

Mac (click-here)

Linux (click-here)

That's it! You have installed Python successfully.

Step 4: Installing Some Additional Libraries

The code which we are going to use requires some additional libraries while executing (I have explained the use of each libraries in the code which you will download in the next step).

PIP is the package manager in Python. It makes library installation easier.

For windows users open Windows PowerShell

Mac and Linux users open Terminal

Type the following codes onto your Windows PowerShell or Terminal

• pip3 install pytz

Click enter and you should see installing progress bar. Once the package is installed you will get installation successful written. [Refer the photo I attached with this step]

Now you are ready to run the Slot Notifier on your computer.

Step 5: Configuring the Slot Notifier Python Code

Download the Co-WIN slot notifier python code [Attached with this step. filename:slot_notifier.py]

Look for IDLE in your start menu. IDLE is the Python editor which we will be using for modifying the code. Start IDLE and open the slot_notifier.py file. [Refer the 1st photo I attached with this step]

Comments in programming language

Comments are used in the programming language for making the code easier to understand

In python comments are made using #

So anything followed by # is interpreted as a comment.

eg: # hello hi how are you

The whole line above is a comment and does is not processed by the system while running the python code. In IDLE comments are marked in red colour.

Lets dig into the slot_notifier.py code

I have added a lot of comments in the code which will help you understand how the program is working..

Configuration section of the code: [Check the 2nd photo attached with this step]

#############################################################
# '400706' or '400703'

PINCODE = '400004'

# '12-6-2021' or 'NA'

DATE = 'NA'

# 'available_capacity_dose1' or 'available_capacity_dose2'

DOSE_OPTION = 'available_capacity_dose2'

# '18' or '45'

AGE = '45'

# 'Free' or 'Paid' or 'NA'

FEE = 'NA'

# Add the vaccine names you want to search or leave it []

VACCINE_OPTIONS = ['COVISHIELD', 'COVAXIN' , 'SPUTNIKV']

#VACCINE_OPTIONS = []

# Search interval. Can only make 100 queries to COWIN servers in 5 minutes (government restrictions) [3.1 seconds interval makes roughly 90 to 100 calls in 5 Minutes].

SER_INT = 3.1

##############################################################

This is the section where you can make changes and configure the code

Lines which start with # are comments and are ignored when the code is running.

PINCODE, DATE, DOSE_OPTION, AGE, FEE, VACCINE_OPTIONS, SER_INT are variables. Variables are used to store information.

You just have to make changes in this section and the code will run without additional configuration.

SET THE VARIABLES AS GIVEN BELOW. IN PYTHON EVERYTHING IS CASE-SENSITIVE SO 'COVISHIELD' IS NOT SAME AS 'Covishield'. MAKE SURE ALL THE VARIABLE VALUES ARE WRITTEN IN THIS FORMAT: 'value' eg. '400004'

[1] Setting the Pincode

PINCODE = 'pincode'

Eg.

• PINCODE = '400004'
• PINCODE = '400703'

[2] Setting the slot search date

DATE = 'date'

Eg.

DATE = '14-6-2021'

If you write it like this

DATE = 'NA'

The program will by default search the slots with Today's date. I would recommend leaving it like 'NA' as you don't have to set the date everyday and the program will automatically set the DATE to current date

[3] Setting the dose option

• For dose 1:

DOSE_OPTION = 'available_capacity_dose1'

• For dose 2:

DOSE_OPTION = 'available_capacity_dose2'

[4] setting the age

• For 18+

AGE = '18'

• For 45+

AGE = '45'

[5] Setting the Slot FEE option

• For searching only Free slots

FEE = 'Free'

• For searching only Paid slots

FEE = 'Paid'

• For searching both Free and Paid slots

FEE = 'NA'

[6] Setting the Vaccine option

• If you are looking for only COVISHIELD vaccine

VACCINE_OPTIONS = ['COVISHIELD']

• If you are looking for only COVAXIN vaccine

VACCINE_OPTIONS = ['COVAXIN']

• If you are looking for COVISHIELD or COVAXIN

VACCINE_OPTIONS = ['COVISHIELD', 'COVAXIN']

• If you are looking for COVAXIN or SPUTNIKV

VACCINE_OPTIONS = ['COVAXIN','SPUTNIKV']

• If you are not concerned with vaccines and any vaccine is fine with you

VACCINE_OPTIONS = []

[7] And finally Retry Interval

When the program does not find any slots, It will retry the search in some time interval. Now this is important to set. Government has restricted the number of times API queries can be made. In 5 minutes we can make maximum 100 queries. If that number exceeds, the servers will block your IP for 24 hours.

So SER_INT is the variable in our program which sets this time interval.

I have configured it to be 3.1 seconds. Now the program will make roughly 85 to 95 calls in 5 minutes which is fine. Don't make SER_INT value below 3.1 seconds as this may block your IP while the program is searching for slots.

Finally! You have configured the code!

Step 6: Running the Program

TURN OFF VPN, PROXY OR ANY NETWORK APPLICATION WHICH CAN CHANGE YOUR IP LOCATION. DUE TO GEOFENCING, COWIN API CAN ONLY BE ACCESSED BY INDIAN IP ADDRESSES. SO IF YOU ARE USING A VPN CONFIGURED WITH OTHER COUNTRY, COWIN SERVERS WILL RETURN 403 ERROR FORBIDDEN ACCESS

To run the program in IDLE go to Run option in the menu and click Run Module or press F5 key.

It will open a new window. This is called a console where you will see the outputs printed by the program.

To stop the program close the console window.

Now if you have configured the code properly you should not see any error or anything written in Red.

Follow the images given with this step.

IF YOU ARE GETTING MODULE NOT FOUND ERROR, INSTALL THAT MODULE USING PIP3 COMMAND LIKE WE DID BEFORE eg. pip3 install module_name

The server returned the slot information of different centers at the Pincode mentioned in the program in JSON format. The program is processing that information and checking whether all the parameters which were mentioned in the previous step (like age, fee, vaccine names) matches with the slot information (which includes slot fee, slot age etc) sent by the server. If it does, then the slot is found and you can see the slot information in the console window. [Check the last photo attached with this step]

If the parameters don't match then that slot information is skipped and the next slot information is checked. This goes on until all the slots sent by the server is checked. Then the program will wait for 3.1 seconds and then repeats the above step.

Console window output meaning:

----------------

No slots found!

----------------

• API responded with {} which means that no slot data is available for the given Pincode or Date. Try modifying these two parameters.

----------------

0 slots

----------------

• This means that the particular vaccine center does not have any slots.

----------------

5 slots

Could not pass Age filter

----------------

• This means this particular vaccine center has slots but for other age group (the code was configured with AGE = '18' but the center has slots for AGE = '45' only).

----------------
5 slots

Age filter passed

Could not pass Fee filter

----------------

• This center has slots for the particular AGE configured in the program but for different FEE option (the code was configured with FEE = 'Free' but the center only has FEE = 'Paid' slots).

----------------
5 slots

Age filter passed

Fee filter passed

Could not pass Vaccine filter

----------------

• This center has slots for the AGE and FEE configured in the program but not for the Vaccine options (the code was configured with VACCINE_OPTION = ['COVAXIN'] but the center only has 'COVISHIELD').

----------------
5 slots

Age filter passed

Fee filter passed

Vaccine filter passed

Slot found!

Slot info

----------------

• Here all the configuration given in the code matches with the slot details and the slot is found. The slot information is printed in the console window.

That's it! You have successfully tested the code. Now lets try running this code on Android!

Step 7: Configuring QPython Android App

QPython is an excellent Android application which can run Python programs!

We will be running the slot_notifier.py on Android.

Download the application QPython 3L from Play Store (click here)

Before we could run the slot_notifier.py on QPython, we have to install some libraries as we did before for IDLE

Go to PIP Console in QPython (Refer the photo I attached with this step).

Type the following and press enter:

pip3 install pytz

That's it! Now we just need to make some changes in the slot_notifier.py before running it on Android.

Step 8: Getting the Code Ready for QPython

Now simply running the code on Android will be of no use. The code should be able to play some sound and vibrate the phone when a slot is found. To achieve this we will be using the QPython libraries in our code.

I have already added the QPython library codes in slot_notifier.py. They are commented in the program. To help find these commented lines easily I have added #$$$ at the end of each comment. There are total 7 lines which you will have to Uncomment (remove the #) [Refer the photos I attached with this step].

Lets go through them one by one:

from androidhelper import Android #$$$

droid = Android() #$$$

• This is for importing the QPython library into the program. Notice I have removed the comment from the start.

droid.notify(center['name'],'Slot found!') #$$$

• This line creates an Andoird status bar notification. The notification will have Title as Center name and subtitle as the text 'Slot Found!'

droid.mediaPlay(os.getcwd() + '/scripts3/sound.wav', play=True) #play sound.wav file on Android #$$$

• This line plays the Audio file sound.wav
• Download the sound.wav file I attached with this step. In the next step I will show you where the audio file and slot_notifier.py file goes in Android.

droid.makeToast('Slot found!') #$$$

• This line create a Toast Notification with text 'Slot Found!'.

droid.vibrate(1000) # vibrate for 1 second #$$$
time.sleep(1.5)# wait 1.5 second #$$$

• These two lines makes the phone vibrate

Notice each lines were followed by #$$$

This will help you find these lines easily.

You can download my un-commented code, I have added it with this step.

Once these 7 comments are removed, the code cannot be run on IDLE anymore as these 7 lines can only work on QPython. Try running this code on IDLE and it will throw an error.

Once you have made the changes save the file. Now lets move this file along with sound.wav to Android phone.

Step 9: Moving the Files to Android

Refer the first photo I attached with this step. Open the QPython app and go to Programs tab. This is where you will find your slot_notifier.py and sound.wav files once they are transferred to the Android phone.

Open your phones file manager. Go to Internal Storage and look for qpython folder.

If you cannot find the folder check the SD Card section.

Inside the qpython folder there should be a folder scripts3. This is the folder where slot_notifier.py and sound.wav file goes. [Refer the 2nd photo I attached with this step]

Transfer both the files (slot_notifier.py and sound.wav) into this folder.

Remember the file name slot_notifier.py and sound.wav should not be changed. Your code won't run.

TURN OFF VPN, PROXY OR ANY NETWORK APPLICATION WHICH CAN CHANGE YOUR IP LOCATION. DUE TO GEOFENCING, COWIN API CAN ONLY BE ACCESSED BY INDIAN IP ADDRESSES. SO IF YOU ARE USING A VPN CONFIGURED WITH OTHER COUNTRY, COWIN SERVERS WILL RETURN 403 ERROR FORBIDDEN ACCESS.

Once your files are in the proper folder, open QPython and go to Programs tab. Check whether your files are visible. [Refer the 3rd photo attached with this step]

You can click on the file and open it.

If you want to change the configuration like PINCODE or FEE option you can do it in QPython. Make sure you save the file after making the changes. [Refer the 3rd photo attached with this step]

Actually we could have had altogether skipped the IDLE configuration and ran the code on Android directly but I wanted you guys to learn how Python can be used in your computers. Also you may make mistakes while editing the code in QPython so trying the code on a computer and making sure everything works fine and then running it on Android helps prevents unwanted errors.

Step 10: Running the Code in QPython

That's it! Run the program and you should see the QPython console window output same as IDLE console. [Refer the 1st photo attached with this step]

IF YOU ARE GETTING MODULE NOT FOUND ERROR, INSTALL THAT MODULE USING PIP3 COMMAND LIKE WE DID BEFORE [Refer the 3rd photo attached with this step]

The program will keep querying the API every 3.1 seconds until a slot is found. The QPython console runs in background. There will be a notification in the status bar showing console running. You can use other apps or turn off the screen. When a slot is found, the program will play the alert tone (audio file), display a toast notification and show a slot found notification in the status bar.

To stop the console refer the 4th photo I attached with this step.

Hurray!!! You just made your own slot notifier!!!

Step 11: Lets Get Vaccinated!