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!