StatistaAmeri/API-SHARE.md

# مستند API اشتراک قیمت ها

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

## اطلاعات اصلی

Base URL:

```txt
https://YOUR-DOMAIN.com
```

Header احراز هویت:

```http
Authorization: Bearer YOUR_API_TOKEN
```

توکن در بک اند از متغیر محیطی زیر خوانده می شود:

```txt
API_TOKEN
```

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

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

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

این endpoint همه دیتاست های اصلی را در یک JSON واحد برمی گرداند.

نمونه درخواست JavaScript:

```js
const API = "https://YOUR-DOMAIN.com";
const TOKEN = "YOUR_API_TOKEN";

const response = await fetch(`${API}/api/v1/prices/latest`, {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`API error: ${response.status}`);
}

const data = await response.json();
console.log(data.generated_at);
console.log(data.datasets.metals);
console.log(data.datasets.currency);
```

ساختار کلی پاسخ:

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

## فهرست کامل محصولات فلزی

برای دیدن همه گروه ها، دسته ها و نام محصولات:

```http
GET /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"
    ]
  }
}
```

تعداد فعلی محصولات فلزی در دیتابیس اصلی: **674 محصول**.

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

```http
GET /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` | درصد تغییر نسبت به قیمت قبلی |

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

```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
  },
  {
    "date": "2026-07-02",
    "low": 72000,
    "mid": 73500,
    "high": 75000
  }
]
```

## جستجوی محصول فلزی

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

نمونه پاسخ:

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

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

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

```http
GET /api/v1/currency
GET /api/v1/gold
GET /api/v1/coin
```

همین داده ها داخل endpoint کلی هم وجود دارند:

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

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

```json
[
  {
    "name": "دلار",
    "price": 610000,
    "change_val": "1,200 (0.2%)",
    "pct": 0.2,
    "dir": "up",
    "fetched_at": "2026-07-04T09:30:00Z"
  }
]
```

نمونه پاسخ طلا:

```json
[
  {
    "name": "طلای 18 عیار",
    "price": 7200000,
    "change_val": "25,000 (0.35%)",
    "pct": 0.35,
    "dir": "up",
    "fetched_at": "2026-07-04T09:30:00Z"
  }
]
```

نمونه پاسخ سکه:

```json
[
  {
    "name": "سکه امامی",
    "price": 850000000,
    "change_val": "-1,500,000 (0.18%)",
    "pct": -0.18,
    "dir": "down",
    "fetched_at": "2026-07-04T09:30:00Z"
  }
]
```

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

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

## CoinGecko: کریپتو

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

داخل endpoint کلی:

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

نمونه پاسخ:

```json
{
  "coins": [
    {
      "id": "bitcoin",
      "symbol": "BTC",
      "name": "Bitcoin",
      "image": "https://...",
      "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,
      "circ_supply": 19600000,
      "ath": 69000,
      "sparkline": [64200, 64500, 65000],
      "dir": "up"
    }
  ],
  "global": {
    "market_cap_usd": 2500000000000,
    "volume_usd": 90000000000,
    "btc_dominance": 51.2,
    "eth_dominance": 17.4,
    "market_cap_change_24h": 1.1,
    "active": 12000
  },
  "trending": [
    {
      "id": "example",
      "symbol": "EXM",
      "name": "Example Coin",
      "rank": 120,
      "thumb": "https://...",
      "price": 1.23,
      "pct_24h": 4.5
    }
  ],
  "fetched_at": "2026-07-04T09:30:00Z"
}
```

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

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

داخل endpoint کلی:

```js
data.datasets.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-04T09:30:00Z"
  }
]
```

توضیح:

| فیلد | توضیح |
|---|---|
| `code` | نماد شرکت |
| `rank` | رتبه شرکت در لیست منبع |
| `name` | نام شرکت |
| `market_cap` | ارزش بازار، بر حسب میلیارد دلار |
| `price` | قیمت سهم |
| `today_pct` | درصد تغییر امروز |
| `dir` | جهت تغییر |
| `country` | کشور شرکت |
| `fetched_at` | زمان دریافت داده |

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

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

داخل endpoint کلی:

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

نمونه پاسخ:

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

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

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

داخل endpoint کلی:

```js
data.datasets.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-04T09:30:00Z"
  }
]
```

## کشف endpoint ها

برای گرفتن لیست endpoint های موجود:

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

## نمونه کامل برای دوست شما

```js
const API = "https://YOUR-DOMAIN.com";
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 catalog = await getJson("/api/v1/metals/tree");
const latestMetals = await getJson("/api/v1/metals/latest");
const allPrices = await getJson("/api/v1/prices/latest");

console.log("Catalog:", catalog);
console.log("Latest metals:", latestMetals);
console.log("TGJU currency:", allPrices.datasets.currency);
console.log("Crypto:", allPrices.datasets.crypto);
```

## خلاصه دیتاست ها

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