StatistaAmeri/API-DOCUMENTATION-FA.md

# مستندات API قیمت ها

این API برای دریافت قیمت ها و داده های بازار به صورت JSON ساخته شده است.  
تمام endpoint های اشتراکی با `/api/v1` شروع می شوند و فقط خواندنی هستند.

## 1. آدرس پایه

```txt
https://statista.steelforesight.ir
```

## 2. احراز هویت

برای تمام درخواست ها باید هدر زیر ارسال شود:

```http
Authorization: Bearer YOUR_API_TOKEN
```

اگر این هدر ارسال نشود یا توکن اشتباه باشد، پاسخ `401` برمی گردد.

نمونه:

```js
const TOKEN = "YOUR_API_TOKEN";

const res = await fetch("https://statista.steelforesight.ir/api/v1/prices/latest", {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await res.json();
```

## 3. دریافت همه داده ها در یک درخواست

```http
GET /api/v1/prices/latest
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/prices/latest
```

این endpoint همه دیتاست ها را در یک پاسخ JSON برمی گرداند.

نمونه ساختار پاسخ:

```json
{
  "generated_at": "2026-07-04T10:50:00Z",
  "datasets": {
    "metals": [],
    "live_commodities": [],
    "currency": [],
    "gold": [],
    "coin": [],
    "commodity": [],
    "steel_stocks": [],
    "crypto": {},
    "world_economy": []
  }
}
```

معنی هر کلید:

| کلید | منبع | توضیح |
|---|---|---|
| `metals` | دیتابیس داخلی | محصولات فلزی و فولادی |
| `currency` | TGJU | ارز |
| `gold` | TGJU | طلا و نقره |
| `coin` | TGJU | سکه |
| `commodity` | Yahoo Finance | کامودیتی های جهانی مثل نفت، طلا، مس و غیره |
| `steel_stocks` | CompaniesMarketCap | شرکت های فولادی جهان |
| `crypto` | CoinGecko | کریپتو، مارکت جهانی و ترندها |
| `world_economy` | Trading Economics | شاخص های اقتصاد کلان کشورها |
| `live_commodities` | داخلی/لایو | دیتاست کامودیتی زنده، اگر فعال باشد |

## 4. محصولات فلزی و فولادی

### 4.1 فهرست کامل گروه ها، دسته ها و محصولات

```http
GET /api/v1/metals/tree
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/metals/tree
```

نمونه پاسخ:

```json
{
  "Minor Metals": {
    "Lithium": [
      "Lithium Carbonate 99.5%min China",
      "Lithium Hydroxide 56.5%min China"
    ],
    "Cobalt": [
      "Cobalt Metal 99.8%min China"
    ]
  },
  "Carbon Steel": {
    "Rebar": [
      "Rebar HRB400 20mm China"
    ]
  }
}
```

تعداد محصولات فلزی موجود در کاتالوگ داخلی:

```txt
674 نام محصول یکتا
686 رکورد در گروه/دسته، چون بعضی محصولات در بیش از یک دسته دیده می شوند
```

### 4.2 آخرین قیمت همه محصولات فلزی

```http
GET /api/v1/metals/latest
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/metals/latest
```

نمونه پاسخ:

```json
[
  {
    "group": "Minor Metals",
    "category": "Lithium",
    "title": "Lithium Carbonate 99.5%min China",
    "date": "2026-07-04",
    "low": 72000,
    "mid": 73500,
    "high": 75000,
    "prev_mid": 73000,
    "pct": 0.68
  }
]
```

توضیح فیلدها:

| فیلد | توضیح |
|---|---|
| `group` | گروه اصلی محصول |
| `category` | دسته محصول |
| `title` | نام محصول |
| `date` | تاریخ آخرین قیمت |
| `low` | کمترین قیمت |
| `mid` | قیمت میانی |
| `high` | بیشترین قیمت |
| `prev_mid` | قیمت میانی قبلی |
| `pct` | درصد تغییر نسبت به قیمت قبلی |

### 4.3 تاریخچه قیمت یک محصول

```http
GET /api/v1/metals/history?title=PRODUCT_TITLE&days=365
```

پارامترها:

| پارامتر | توضیح |
|---|---|
| `title` | نام دقیق محصول |
| `days` | تعداد روزهای تاریخچه. اگر `0` باشد، همه تاریخچه برمی گردد |

نمونه پاسخ:

```json
[
  {
    "date": "2026-07-01",
    "low": 71000,
    "mid": 72500,
    "high": 74000
  }
]
```

### 4.4 جستجوی محصول

```http
GET /api/v1/metals/search?q=lithium
```

نمونه پاسخ:

```json
[
  {
    "title": "Lithium Carbonate 99.5%min China",
    "group": "Minor Metals",
    "category": "Lithium"
  }
]
```

## 5. TGJU: ارز، طلا و سکه

داده های TGJU در سه endpoint جدا ارائه می شوند.

### 5.1 ارز

```http
GET /api/v1/currency
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/currency
```

### 5.2 طلا

```http
GET /api/v1/gold
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/gold
```

### 5.3 سکه

```http
GET /api/v1/coin
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/coin
```

نمونه پاسخ TGJU:

```json
[
  {
    "name": "دلار / نقدی",
    "price": 610000,
    "change_val": "(0%) 0",
    "pct": 0,
    "dir": "up",
    "fetched_at": "2026-07-04T10:41:25Z"
  }
]
```

توضیح فیلدها:

| فیلد | توضیح |
|---|---|
| `name` | نام آیتم |
| `price` | قیمت عددی |
| `change_val` | متن تغییر قیمت طبق منبع |
| `pct` | درصد تغییر |
| `dir` | جهت تغییر، مثل `up` یا `down` |
| `fetched_at` | زمان دریافت داده |

در endpoint کلی:

```js
data.datasets.currency
data.datasets.gold
data.datasets.coin
```

## 6. CoinGecko: کریپتو

```http
GET /api/v1/crypto
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/crypto
```

نمونه پاسخ:

```json
{
  "coins": [
    {
      "id": "bitcoin",
      "symbol": "BTC",
      "name": "Bitcoin",
      "rank": 1,
      "price": 65000,
      "pct_1h": 0.1,
      "pct_24h": 1.2,
      "pct_7d": -3.4,
      "market_cap": 1280000000000,
      "volume_24h": 32000000000,
      "high_24h": 66000,
      "low_24h": 64000,
      "sparkline": [],
      "dir": "up"
    }
  ],
  "global": {
    "market_cap_usd": 2500000000000,
    "volume_usd": 90000000000,
    "btc_dominance": 51.2,
    "eth_dominance": 17.4
  },
  "trending": [],
  "fetched_at": "2026-07-04T10:41:25Z"
}
```

در endpoint کلی:

```js
data.datasets.crypto
```

## 7. CompaniesMarketCap: سهام شرکت های فولادی

```http
GET /api/v1/steel-stocks
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/steel-stocks
```

نمونه پاسخ:

```json
[
  {
    "code": "NUE",
    "rank": 1,
    "name": "Nucor",
    "market_cap": 38.5,
    "price": 156.2,
    "today_pct": 1.4,
    "dir": "up",
    "country": "United States",
    "fetched_at": "2026-07-04T10:41:25Z"
  }
]
```

در endpoint کلی:

```js
data.datasets.steel_stocks
```

## 8. Yahoo Finance: کامودیتی های جهانی

```http
GET /api/v1/commodity
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/commodity
```

نمونه پاسخ:

```json
[
  {
    "symbol": "GC=F",
    "name": "Gold",
    "price": 2350.5,
    "change": 8.2,
    "pct": 0.35,
    "currency": "USD",
    "up": true
  }
]
```

در endpoint کلی:

```js
data.datasets.commodity
```

## 9. Trading Economics: اقتصاد جهان

```http
GET /api/v1/world-economy
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/world-economy
```

نمونه پاسخ:

```json
[
  {
    "country": "United States",
    "gdp": 27360,
    "gdp_growth": 1.4,
    "interest_rate": 5.5,
    "inflation_rate": 3.2,
    "jobless_rate": 4.0,
    "gov_budget": -6.3,
    "debt_gdp": 122.3,
    "current_account": -3.0,
    "population": 335,
    "fetched_at": "2026-07-04T10:41:25Z"
  }
]
```

در endpoint کلی:

```js
data.datasets.world_economy
```

## 10. کشف endpoint های موجود

```http
GET /api/v1/datasets
```

آدرس کامل:

```txt
https://statista.steelforesight.ir/api/v1/datasets
```

این endpoint لیست مسیرهای API را برمی گرداند.

## 11. نمونه کامل JavaScript

```js
const API = "https://statista.steelforesight.ir";
const TOKEN = "YOUR_API_TOKEN";

async function getJson(path) {
  const res = await fetch(`${API}${path}`, {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
    },
  });

  if (!res.ok) {
    throw new Error(`API request failed: ${res.status}`);
  }

  return res.json();
}

const allPrices = await getJson("/api/v1/prices/latest");

console.log(allPrices.datasets.metals);
console.log(allPrices.datasets.currency);
console.log(allPrices.datasets.gold);
console.log(allPrices.datasets.coin);
console.log(allPrices.datasets.crypto);
console.log(allPrices.datasets.steel_stocks);
console.log(allPrices.datasets.commodity);
console.log(allPrices.datasets.world_economy);
```

## 12. نمونه تست با PowerShell

```powershell
$TOKEN = "YOUR_API_TOKEN"

$data = Invoke-RestMethod `
  -Uri "https://statista.steelforesight.ir/api/v1/prices/latest" `
  -Headers @{ Authorization = "Bearer $TOKEN" }

$data.datasets.currency | Select-Object -First 5
$data.datasets.gold | Select-Object -First 5
$data.datasets.coin | Select-Object -First 5
```

اگر متن فارسی در PowerShell خراب نمایش داده شد، مشکل از encoding ترمینال است. برای بهتر شدن نمایش:

```powershell
chcp 65001
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
```

## 13. وضعیت فعلی دیتاست های Live

طبق آخرین خروجی live API:

```txt
TGJU currency: 33
TGJU gold: 14
TGJU coin: 5
Yahoo Finance commodities: 19
CompaniesMarketCap steel stocks: 81
CoinGecko top crypto: 100
CoinGecko trending: 15
```

کاتالوگ داخلی فلزات:

```txt
674 نام محصول فلزی/فولادی یکتا
```