README
¶
NAQA API | نقاء API
نظرة عامة | Overview
نقاء API هي خدمة RESTful مصممة لتوفير بيانات عن عملية تطهير الأسهم السعودية. توفر الخدمة معلومات دقيقة عن نسب التطهير للأسهم في السوق السعودي وتصنيفها الشرعي.
المميزات الرئيسية | Key Features
- 🧮 حساب مبلغ التطهير للأسهم | Stock Purification Amount Calculator
- 🔍 البحث في الأسهم حسب القطاع والتصنيف الشرعي | Search Stocks by Sector and Shariah Classification
- 📊 معلومات محدثة عن الأسهم النقية والمختلطة | Updated Pure and Mixed Stocks Information
- 🌐 دعم كامل للغة العربية | Full Arabic Language Support
- 🔄 واجهة برمجة تطبيقات RESTful سهلة الاستخدام | Easy-to-use RESTful API
المتطلبات | Requirements
- Go 1.23.4 أو أحدث | or higher
- Git
- MongoDB
تثبيت المشروع | Project Setup
git clone https://github.com/anqorithm/naqa-api
cd naqa-api
go mod download
المتغيرات البيئية | Environment Variables
MONGO_URI=
MONGO_DATABASE=
PORT=
التصنيف الشرعي | Shariah Classification
- نقية | Pure: أسهم متوافقة تماماً مع الشريعة | Fully Shariah Compliant Stocks
- مختلطة | Mixed: أسهم تحتاج إلى تطهير | Stocks Requiring Purification
- غير متوافقة | Non-Compliant: أسهم غير متوافقة مع الشريعة | Non-Shariah Compliant Stocks
السنوات المدعومة | Supported Years
السنوات المتوفرة | Available Years: 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023
Overview
NAQA API is a RESTful service designed to provide data about the purification process of Saudi stocks. The service offers accurate information about stock purification rates in the Saudi market and their Shariah classification.
Key Features
- 🧮 Calculate stock purification amounts
- 🔍 Search stocks by sector and Shariah classification
- 📊 Updated information about pure and mixed stocks
- 🌐 Full Arabic language support
- 🔄 Easy-to-use RESTful API
Deployed on GCP
Prerequisites
- Go 1.23.4 or higher
- Git
- MongoDB
Version Information
- Version: 1.9.1
- Environment: Development
- Base API Path:
/api/v1
Quick Start
- Clone the repository:
git clone https://github.com/anqorithm/naqa-api
cd naqa-api
- Install dependencies:
go mod download
- Set up environment variables:
cp .env.example .env
# Edit .env with your configurations
Installation
- Clone the project.
- Install Go dependencies:
go mod download
Environment
Set the following environment variables or edit the .env file:
- MONGO_URI
- MONGO_DATABASE
- PORT
Usage
- Run the server:
make dev - Access the API at:
http://localhost:3000/api/v1
Environment Variables
Before running the application, make sure to set up your environment variables:
# Copy the example env file
cp .env.example .env
# Fill in your environment variables in .env file:
API_VERSION # API version
ENVIRONMENT # development, production, etc.
PORT # Server port
APP_NAME # Application name
APP_DESCRIPTION # Application description
MONGO_URI # MongoDB connection URI
MONGO_DATABASE # MongoDB database name
Running the Application
Local Development
go run cmd/api/main.go
Server will start at http://localhost:3000
Docker Setup
Using Docker Compose (Recommended)
# Start services
docker-compose up -d
# Stop services
docker-compose down
Manual Docker Build
# Build image
docker build -t naqa-api .
# Run container
docker run -d -p 3000:3000 naqa-api
API Endpoints
Base URL
http://localhost:3000/api/v1
Available Endpoints
## Environment Variables
@baseUrl = http://localhost:3000
@contentType = application/json
### Health Check
GET {{baseUrl}}/api/health
Content-Type: {{contentType}}
### Metrics Dashboard
GET {{baseUrl}}/metrics
Content-Type: {{contentType}}
### Root Endpoint
GET {{baseUrl}}/
Content-Type: {{contentType}}
### Get Stocks by Year
GET {{baseUrl}}/api/v1/stocks/year/2023
Content-Type: {{contentType}}
### Search Stocks with Parameters
GET {{baseUrl}}/api/v1/stocks/year/2023/search?name=aramco§or=energy&sharia_opinion=نقية
Content-Type: {{contentType}}
### Calculate Purification Amount
POST {{baseUrl}}/api/v1/stocks/calculate-purification
Content-Type: {{contentType}}
Search Examples
Search by Name
GET {{baseUrl}}/api/v1/stocks/year/2023/search?name=%D8%A3%D8%B1%D8%A7%D9%85%D9%83%D9%88
Content-Type: {{contentType}}
Search by Code
GET {{baseUrl}}/api/v1/stocks/year/2023/search?code=2222
Content-Type: {{contentType}}
Search by Sector
GET {{baseUrl}}/api/v1/stocks/year/2023/search?sector=%D8%A7%D9%84%D8%B7%D8%A7%D9%82%D8%A9
Content-Type: {{contentType}}
Search by Sharia Opinion
GET {{baseUrl}}/api/v1/stocks/year/2023/search?sharia_opinion=%D9%86%D9%82%D9%8A%D8%A9
Content-Type: {{contentType}}
Combined Search
GET {{baseUrl}}/api/v1/stocks/year/2023/search?sector=%D8%A7%D9%84%D8%B7%D8%A7%D9%82%D8%A9&sharia_opinion=%D9%86%D9%82%D9%8A%D8%A9
Content-Type: {{contentType}}
مصدر البيانات | Data Source
هذه الخدمة مبنية على قوائم التطهير المنشورة للعامة من قبل فضيلة الشيخ الدكتور محمد بن سعود العصيمي (المشرف العام على موقع المقاصد). تم جمع وتنظيم البيانات من:
- حاسبة التطهير - موقع المقاصد
- قوائم التحليل المالي للشركات المنشورة للعامة
- حسابات نسب التطهير المعتمدة من قبل الشيخ د. محمد العصيمي
Important Note: All purification rates and Shariah classifications are based on the publicly available lists and calculations approved by Sheikh Dr. Mohammed Al-Osaimi, the General Supervisor of Almaqased website.
الاعتماد والإشراف | Supervision
تحت إشراف:
فضيلة الشيخ الدكتور محمد بن سعود العصيمي
المشرف العام على موقع المقاصد للاقتصاد الإسلامي
Inspiration and Data Source
This API is inspired by NaqausStocks.com.
Data source: Almaqased Cleansing Calculator
المشرف العام: د. محمد بن سعود العصيمي
Note: Supported Years: 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023
Development
Project Structure
.
├── api.http
├── cmd
│ └── api
│ └── main.go
├── docker-compose.yml
├── Dockerfile
├── go.mod
├── go.sum
├── internal
│ ├── config
│ │ ├── config.go
│ │ └── mongodb.go
│ ├── constants
│ │ └── constants.go
│ ├── handlers
│ │ ├── errors.go
│ │ ├── handlers.go
│ │ └── stocks.go
│ ├── middleware
│ │ ├── middleware.go
│ │ └── year_validator.go
│ ├── models
│ │ ├── error.go
│ │ └── stock.go
│ ├── routes
│ │ └── routes.go
│ └── utils
│ └── utils.go
├── LICENSE
├── Makefile
└── README.md
حساب مبلغ تطهير الأسهم | Stock Purification Amount Calculation
معادلة حساب مبلغ التطهير
يتم حساب مبلغ تطهير الأسهم باستخدام المعادلة التالية:
$$ \text{مبلغ التطهير} = \frac{\text{عدد الأسهم} \times \text{نسبة التطهير} \times \text{عدد أيام التملك}}{365.0} $$
حيث:
عدد الأسهم: إجمالي عدد الأسهم المملوكةنسبة التطهير: نسبة التطهير السنوية (النسبة المئوية)عدد أيام التملك: عدد الأيام التي تم فيها امتلاك الأسهم365.0: عدد أيام السنة (ثابت)
مثال
لـ 100 سهم بنسبة تطهير 2.5% تم امتلاكها لمدة 180 يوم:
$$ \text{مبلغ التطهير} = \frac{100 \times 0.025 \times 180}{365.0} = 1.23 $$
Stock Purification Amount Calculation
The purification amount for stocks is calculated using the following formula:
$$ \text{purificationAmount} = \frac{\text{numberOfStocks} \times \text{purificationRate} \times \text{daysHeld}}{365.0} $$
Where:
numberOfStocks: Total number of stocks heldpurificationRate: Annual purification rate (percentage)daysHeld: Number of days the stocks were held365.0: Days in a year (constant)
Example
For 100 stocks with 2.5% purification rate held for 180 days:
$$ \text{purificationAmount} = \frac{100 \times 0.025 \times 180}{365.0} = 1.23 $$
Architecture Design & Diagrams
Class Diagram
classDiagram
%% Core Classes based on actual project structure
class Config {
+MongoDB mongodb
+Load() error
+GetEnvVariable(key string, defaultValue string) string
}
class MongoDB {
+string URI
+string Database
+Connect() error
+GetClient() *mongo.Client
}
class Stock {
+string ID
+string Code
+string Name
+string Sector
+string ShariaOpinion
+float64 PurificationRate
+int Year
}
class StockHandler {
+GetStocks(c *fiber.Ctx) error
+GetStocksByYear(c *fiber.Ctx) error
+SearchStocks(c *fiber.Ctx) error
+CalculatePurification(c *fiber.Ctx) error
}
class ErrorHandler {
+HandleError(c *fiber.Ctx, err error) error
+NewAPIError(message string, status int) *APIError
}
class YearValidator {
+ValidateYear(year string) bool
+YearMiddleware(c *fiber.Ctx) error
}
class Routes {
+SetupRoutes(app *fiber.App)
+setupStockRoutes(app *fiber.App)
}
%% Relationships
Config --> MongoDB : uses
Routes --> StockHandler : registers
Routes --> YearValidator : uses
StockHandler --> ErrorHandler : uses
StockHandler --> Stock : manages
Docker-Compose Diagram
graph LR
subgraph Docker-Compose
subgraph naqa-network
api[API Service]
mongo[MongoDB]
api --> |depends_on| mongo
end
volume[(mongodb_data)]
mongo --> |volume| volume
api --> |port| port1[3000:3000]
mongo --> |port| port2[27017:27017]
subgraph Environment
env[Environment Variables:<br/>API_VERSION<br/>ENVIRONMENT<br/>PORT<br/>APP_NAME<br/>APP_DESCRIPTION<br/>MONGO_URI<br/>MONGO_DATABASE]
end
env --> api
end
Request Flow Diagram
sequenceDiagram
participant C as Client
participant F as Fiber App
participant M as Year Validator
participant H as Stock Handler
participant DB as MongoDB
C->>F: HTTP Request
F->>M: Validate Year
alt Invalid Year
M-->>C: Error Response
else Valid Year
M->>H: Process Request
H->>DB: Query Data
DB-->>H: Return Results
H-->>C: JSON Response
end
Building for Production
go build -o naqa-api cmd/api/main.go
المساهمة | Contributing
{فَأَمَّا الزَّبَدُ فَيَذْهَبُ جُفَاءً ۖ وَأَمَّا مَا يَنفَعُ النَّاسَ فَيَمْكُثُ فِي الْأَرْضِ}
نرحب بمساهماتكم في تطوير هذا المشروع. للمساهمة:
- انسخ المستودع (Fork)
- أنشئ فرعاً جديداً (
git checkout -b feature/amazing-feature) - أضف تعديلاتك (
git add .) - ثبّت التغييرات (
git commit -m 'Add some amazing feature') - ارفع التعديلات (
git push origin feature/amazing-feature) - أنشئ طلب تغيير (Pull Request)
We welcome contributions to enhance this project. To contribute:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Add your changes (
git add .) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please make sure to update tests as appropriate and follow our code of conduct.
Contributors
- Abdullah Alqahtani - Initial work - anqorithm
- Email: anqorithm@protonmail.com
- Yasser - zYaseer
License
This project is licensed under the MIT License - see the LICENSE file for details.
Credits
Data Source
- Almaqased Cleansing Calculator
- المشرف العام: د. محمد بن سعود العصيمي
Inspiration
This API is inspired by NaqausStocks.com
Directories