How to Build a Simple ‘Indian Festival API’ with Python and a JSON Dataset
Introduction
As a developer working with the Indian market, I often need to plan features or campaigns around our incredibly diverse festival calendar. I recently needed a simple way to query festivals by region and date, but I was surprised by the lack of good options. Most free datasets were outdated or incomplete, and the big commercial APIs were expensive subscription services.
So, I decided to build my own solution.
In this tutorial, I’ll walk you through the simple, practical approach I took to create a queryable festival calendar using a JSON dataset and a bit of Python with the pandas library.
What We’ll Build
We’ll write a simple Python script that can:
Load a list of festivals from a local JSON file.
Filter those festivals based on a specific region (e.g., “Kerala”).
Print the results.
Prerequisites
All you’ll need is Python 3.8+ and the pandas library. You can install pandas by running:
Bash
pip install pandas
Step 1: The Data (Our JSON Snippet)
First, we need some data. For this tutorial, we’ll use a small sample. Create a file named my_festivals.json and paste this into it.
[
{
"festival": "Holi",
"date": "2025-03-14",
"region": ["All India"],
"is_holiday": true,
"category": "Hindu",
"notes": "Festival of colors; 15% retail spike (Amazon India 2024)."
},
{
"festival": "Vishu",
"date": "2025-04-14",
"region": ["Kerala"],
"is_holiday": true,
"category": "Cultural",
"notes": "Kerala New Year; gold, apparel e-commerce spikes."
},
{
"festival": "Onam",
"date": "2025-08-25",
"region": ["Kerala"],
"is_holiday": true,
"category": "Cultural",
"notes": "Harvest festival; regional retail, hospitality surge."
},
{
"festival": "Diwali",
"date": "2025-10-21",
"region": ["All India"],
"is_holiday": true,
"category": "Hindu",
"notes": "Festival of lights; 20% e-commerce surge."
},
{
"festival": "Durga Puja",
"date": "2025-09-28",
"region": ["West Bengal", "Assam", "Odisha"],
"is_holiday": true,
"category": "Hindu",
"notes": "Goddess worship; 15% apparel sales boost."
}
]
Step 2: The Python Script
Now, let’s write the Python code. Create a file named run_query.py in the same folder. This script is a simplified version of the one in my full toolkit.
import json
import pandas as pd
def load_festivals(file_path="my_festivals.json"):
"""Loads festival data from a JSON file."""
try:
with open(file_path, 'r') as f:
return json.load(f)
except FileNotFoundError:
print(f"Error: The file {file_path} was not found.")
return []
def query_festivals_by_region(region_name):
"""Filters festivals for a specific region."""
all_festivals = load_festivals()
if not all_festivals:
return
df = pd.DataFrame(all_festivals)
# Filter the DataFrame
# The 'apply' method checks if the region_name is in the list of regions for each festival
regional_festivals = df[df['region'].apply(lambda regions: region_name in regions)]
print(f"--- Festivals in {region_name} ---")
# Convert the filtered DataFrame to a nicely formatted JSON string for printing
print(regional_festivals.to_json(orient="records", indent=2))
# --- Main execution block ---
if __name__ == "__main__":
# Let's find all festivals celebrated in Kerala from our sample data
query_festivals_by_region("Kerala")
Step 3: Running the Script and Seeing the Result
Now, run the script from your terminal:
Bash
python run_query.py
--- Festivals in Kerala ---
[
{
"festival":"Vishu",
"date":"2025-04-14",
"region":["Kerala"],
"is_holiday":true,
"category":"Cultural",
"notes":"Kerala New Year; gold, apparel e-commerce spikes."
},
{
"festival":"Onam",
"date":"2025-08-25",
"region":["Kerala"],
"is_holiday":true,
"category":"Cultural",
"notes":"Harvest festival; regional retail, hospitality surge."
}
]
Success! We’ve just built a basic, functioning query tool for our festival data.
The Shortcut: The Complete Toolkit
This tutorial gives you the basic framework to build your own tool.
However, if you want to save yourself the 20+ hours it takes to collect, clean, and verify the data for all 100+ festivals, I’ve made the complete toolkit available on Gumroad.
The full version includes:
The complete dataset for 2025-26 with 100+ festivals.
Actionable e-commerce and business notes for every major festival .
The full Python script with advanced filtering (by date range) and CSV export functionality.
You can grab the full toolkit here: [ https://yashingawale.gumroad.com/l/indianfestivalapi/LAUNCH40 ]
Thanks for reading, and happy coding!
