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

Feature	Type	Description
month	Integer (1-12)	Gregorian month
day_of_week	Integer (0-6)	Day of week (Monday=0)
is_weekend	Binary (0/1)	Friday/Saturday (GCC weekend)
country_encoded	Integer	Label-encoded country
category_encoded	Integer	Label-encoded product category
temperature	Float	Temperature in Celsius
is_ramadan	Binary (0/1)	Whether it is Ramadan
ramadan_week	Integer (0-4)	Week of Ramadan (0 if not Ramadan)
is_eid_fitr	Binary (0/1)	Eid al-Fitr period
is_eid_adha	Binary (0/1)	Eid al-Adha period
is_shopping_festival	Binary (0/1)	Dubai Shopping Festival, Riyadh Season, Shop Qatar, etc.
is_white_friday	Binary (0/1)	White Friday / Black Friday sales
is_national_day	Binary (0/1)	Country national day events
is_back_to_school	Binary (0/1)	Back-to-school season
year	Integer	Year (2018-2025)

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

Metric	Value
R2 Score	0.992
RMSE	2.94
MAE	2.28

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

Feature Importance (Top 5)

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

Usage

python

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

GencoDiv/ramadan-demand-forecaster

GCC Retail Demand Forecasting Model v2