ramadan-demand-forecaster

GCC Retail Demand Forecasting Model v2

Built by OCG Dubai — Agentic Commerce APIs for the GCC

An XGBoost Regressor model for predicting retail demand across 6 GCC countries and 12 product categories. Uses Gregorian calendar with regional event flags — no Hijri calendar dependency. Part of OCG Dubai's Agentic Commerce APIs.

Model Description

This model predicts the demand_index (0-100) for retail products in GCC countries (UAE, KSA, Qatar, Kuwait, Bahrain, Oman) across 12 realistic product categories based on actual e-commerce revenue data. It captures seasonal patterns including Ramadan, Eid, shopping festivals (DSF, Riyadh Season, White Friday), and country-specific events.

Features Used

Product Categories

12 categories based on real GCC e-commerce revenue shares:

• fashion_apparel (25-38% of revenue)
• electronics_media (19-34%)
• groceries_fmcg (15-30%)
• beauty_cosmetics (5-10%)
• home_furniture (3-8%)
• luxury_goods
• jewelry_watches
• health_wellness
• food_dining
• sports_outdoor
• toys_kids
• travel_entertainment

Model Performance

Trained on 168,307 samples, tested on 42,077 samples.

Feature Importance (Top 5)

1. category_encoded (80.1%) — Product category is the dominant predictor
2. is_shopping_festival (4.8%) — DSF, Riyadh Season, etc.
3. is_eid_fitr (3.3%) — Eid al-Fitr celebrations
4. is_white_friday (2.5%) — White Friday sales events
5. ramadan_week (2.2%) — Week within Ramadan

Usage

import joblib
import numpy as np

# Load model and encoders
model = joblib.load("model.joblib")
encoders = joblib.load("encoders.joblib")
country_encoder = encoders['country_encoder']
category_encoder = encoders['category_encoder']

# Prepare features
country_encoded = country_encoder.transform(["UAE"])[0]
category_encoded = category_encoder.transform(["fashion_apparel"])[0]

# Feature order: month, day_of_week, is_weekend, country_encoded, category_encoded,
#                temperature, is_ramadan, ramadan_week, is_eid_fitr, is_eid_adha,
#                is_shopping_festival, is_white_friday, is_national_day, is_back_to_school, year

features = np.array([[
    1,      # month (January)
    4,      # day_of_week (Friday)
    1,      # is_weekend
    country_encoded,
    category_encoded,
    22.0,   # temperature
    0,      # is_ramadan
    0,      # ramadan_week
    0,      # is_eid_fitr
    0,      # is_eid_adha
    1,      # is_shopping_festival (DSF in January)
    0,      # is_white_friday
    0,      # is_national_day
    0,      # is_back_to_school
    2025    # year
]])

prediction = model.predict(features)
print(f"Predicted demand index: {prediction[0]:.2f}")

Training Data

210,384 records across 6 GCC countries, 12 product categories, 2018-2025. Based on actual GCC retail market research:

• UAE: $114B market — tourism & luxury driven
• KSA: $161B market — largest by volume, Vision 2030 growth
• Qatar: $19.5B — high per-capita spend
• Kuwait: $22.6B — strong grocery/FMCG
• Bahrain: $8.5B — regional hub
• Oman: $12.0B — emerging e-commerce

Country-specific events: Dubai Shopping Festival, Riyadh Season, Shop Qatar, Hala February, Bahrain F1, Khareef Festival.

Dataset: GencoDiv/gcc-ramadan-retail-patterns

Limitations

• Trained on synthetic data — fine-tune on real retail data before production use
• Predictions are most accurate within the feature ranges seen during training
• Country and category must be from the predefined lists

Files

• model.joblib — Trained XGBoost model (sklearn-compatible)
• model.json — XGBoost model in JSON format
• encoders.joblib — Label encoders for country and category
• config.json — Model configuration and metadata
• feature_importances.json — Feature importance scores

About OCG Dubai

OCG Dubai builds Agentic Commerce APIs for the GCC market — demand forecasting, halal compliance, smart baskets, and dynamic pricing calibrated for regional consumer behavior.

• Website: ocg-dubai.ae

License

MIT License