NAQA API | نقاء API

{فَأَمَّا الزَّبَدُ فَيَذْهَبُ جُفَاءً ۖ وَأَمَّا مَا يَنفَعُ النَّاسَ فَيَمْكُثُ فِي الْأَرْضِ}

سورة الرعد - آية 17

نظرة عامة | 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

cp .env.example .env
API_VERSION=1.0.0
ENVIRONMENT=development
PORT=3000
APP_NAME="Naqa API"
APP_DESCRIPTION="Naqa API is a RESTful service designed to provide data on the purification process of Saudi stocks."
MONGO_URI="mongodb://mongodb:27017"
MONGO_DATABASE="naqa"
SEED_DATA="false"

التصنيف الشرعي | 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

Access the API on GCP

Prerequisites

Go 1.23.4 or higher
Git
MongoDB

Version Information

Version: 1.13.0
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
API_VERSION=1.0.0
ENVIRONMENT=development
PORT=3000
APP_NAME="Naqa API"
APP_DESCRIPTION="Naqa API is a RESTful service designed to provide data on the purification process of Saudi stocks."
MONGO_URI="mongodb://mongodb:27017"
MONGO_DATABASE="naqa"
SEED_DATA="false"

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

أداء النظام | System Performance

مؤشرات الأداء

استخدام المعالج: 0.0%
استخدام الذاكرة: 31.1 MB
زمن الاستجابة: 195ms
الاتصالات المفتوحة: 7.8 MB

Performance Metrics

CPU & Memory Usage

System Statistics

CPU Usage: 0.0%
Memory Usage: 31.1 MB
Response Time: 195ms
Open Connections: 7.8 MB

Monitoring Features

CPU/Memory tracking
Response time analysis
Connection monitoring
Error rate tracking
Resource utilization
Performance trends

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&sector=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
├── assets
│   ├── 1.png
│   └── 2.png
├── 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
│   ├── seeders
│   │   └── seeders.go
│   └── utils
│       └── utils.go
├── LICENSE
├── Makefile
├── README.md
└── sources
    ├── final_2015.json
    ├── final_2016.json
    ├── final_2017.json
    ├── final_2018.json
    ├── final_2019.json
    ├── final_2020.json
    ├── final_2021.json
    ├── final_2022.json
    └── final_2023.json

حساب مبلغ تطهير الأسهم | 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 held
purificationRate: Annual purification rate (percentage)
daysHeld: Number of days the stocks were held
365.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<br/>SEED_DATA]
        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: [email protected]
Yasser - zYaseer

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.github/workflows		.github/workflows
assets		assets
cmd/api		cmd/api
internal		internal
sources		sources
.air.toml		.air.toml
.env.example		.env.example
.gitignore		.gitignore
.releaserc.json		.releaserc.json
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
api.http		api.http
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

License

anqorithm/naqa-api

Folders and files

Latest commit

History

Repository files navigation

NAQA API | نقاء API

نظرة عامة | Overview

المميزات الرئيسية | Key Features

المتطلبات | Requirements

تثبيت المشروع | Project Setup

المتغيرات البيئية | Environment Variables

التصنيف الشرعي | Shariah Classification

السنوات المدعومة | Supported Years

Overview

Key Features

Deployed on GCP

Prerequisites

Version Information

Quick Start

Installation

Environment

Usage

Environment Variables

Running the Application

Local Development

أداء النظام | System Performance

مؤشرات الأداء

Performance Metrics

CPU & Memory Usage

System Statistics

Docker Setup

Using Docker Compose (Recommended)

Manual Docker Build

API Endpoints

Base URL

Available Endpoints

Search Examples

Search by Name

Search by Code

Search by Sector

Search by Sharia Opinion

Combined Search

مصدر البيانات | Data Source

الاعتماد والإشراف | Supervision

Inspiration and Data Source

Development

Project Structure

حساب مبلغ تطهير الأسهم | Stock Purification Amount Calculation

معادلة حساب مبلغ التطهير

مثال

Stock Purification Amount Calculation

Example

Architecture Design & Diagrams

Class Diagram

Docker-Compose Diagram

Request Flow Diagram

Building for Production

المساهمة | Contributing

Contributors

License

Credits

Data Source

Inspiration

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 26

Packages 0

Contributors 2

Languages

Packages