COVID-19 Vaccines in India: How to Build an API-based Vaccine Locator with Postman

Photo by Hannah Busing on Unsplash

The Co-Win portal is a critical website for India at this time, allowing Indians to register and schedule vaccinations against COVID-19 (please note that the portal may lead to a 403 Forbidden error if you’re not in India), and it has published the Co-Win APIs. Since the population of India is so large and the situation is extremely tense right now, the available vaccination slots get booked in seconds. During the initial days of the vaccine, Postman Chief Software Architect Shamasis Bhattacharya and Postman Software Engineer Intern Himanshu Sharma used the Postman Collection Runner to receive alerts on the availability of vaccines in their respective areas—and they managed to get vaccinated. Though the portal’s traffic has increased considerably since, and getting a vaccine appointment has become more difficult, we still think that automating updates when a resource is available is especially useful during the pandemic. We hope you can apply this approach to other helpful APIs in addition to the Co-Win API used in this tutorial.

Getting started

COVID-19 Vaccine Locator India public workspace Overview page

Configure alerts

  • Co-Win 2-week Alert sends alerts for vaccines available in the next two weeks
  • Co-Win n-day Alert sends alerts for vaccines available in the next n days

In order to configure alerts, fork the collection and the Co-Win environment. Once forked, you need to run the collection at regular intervals in order to receive regular alerts. This can be done in three ways:

1. Configure alerts via the Postman Collection Runner

Running a collection via the Collection Runner

The only downside to this approach is that you will have to keep your machine running the entire time.

2. Configure alerts via Postman CLI: Newman

In order to use Newman, you need to first install it locally or on any other environment (you can try AWS ECS scheduled task, Google’s App Engine Cron Service). Once installed, to run the collection referencing the environment, either export the collection or find the collection URL. Using the URL directly is far more convenient because then you can modify the collection in Postman and without exporting expect to see that change reflected whenever Newman runs.

To find the URL for a collection/environment in your personal workspace, you will need the Postman API Key. The API token can be used to fetch a collection or environment using the Postman API by using these formats:

newman run "$collection_uuid?apikey=$apikey" --environment "$environment_uuid?apikey=$apikey"

Pro Tip: Set the environment variable values to the initial value you prefer. Newman only picks up the initial value defined in the environment, since the current value doesn’t get synced to the Postman server.

3. Configure alerts via monitors

Pro Tip: Set the environment variable values to the initial value you prefer. Monitors only pick up the initial value defined in the environment, since the current value doesn’t get synced to the Postman server.

Creating a Postman monitor

Receive Slack and Telegram alerts

How to set up a Slack webhook

How to set up a Telegram Bot{{telegram_token}}/getUpdates

Set the chat_id received to the environment variable telegram_chat_id.

How to test existing collection workflows

In order to test the collection, you need to do the following:

  • Switch the base_url to point to the mock_url in the environment
  • The pre-request script of both collections-Co-Win 2-week Alert as well as Co-Win n-day Alert-have request IDs listed
Pre-request script of collections to target the mock server

How does the pre-request script test for different scenarios?

What should you use to run the collection while testing?

How to contribute to this public workspace

  • Add collections alerting for different use cases
  • Add alerts for other products/platforms (Whatsapp, Messenger, etc.)
  • Separate out the testing via mock server logic from pre-request to a different collection to enable ease of use
  • Add more visualizations
  • Add comments wherever helpful

You can fork an existing collection and make changes to experiment with different options. Once complete, raise a pull request to the collection in the workspace. To contribute by adding a new collection to the COVID-19 Vaccine Locator India workspace, fork the CONTRIBUTIONS collection and raise a pull request against it.

It is a critical time to band together and apply all of our technical proficiency in order to discover new ways to fight the pandemic. We hope this approach inspires you to build automated solutions to ease the process when constantly waiting for resources-whether now or for future circumstances.

Originally published at on May 11, 2021.

Developer Advocate @Postman