StatistaAmeri/API-SHARE.md

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

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

اطلاعات اصلی

Base URL:

https://YOUR-DOMAIN.com

Header احراز هویت:

Authorization: Bearer YOUR_API_TOKEN

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

API_TOKEN

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

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

GET /api/v1/prices/latest

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

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

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);

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

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

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

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

GET /api/v1/metals/tree

نمونه پاسخ:

{
  "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 محصول.

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

GET /api/v1/metals/latest

نمونه پاسخ:

[
  {
    "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	درصد تغییر نسبت به قیمت قبلی

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

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

پارامترها:

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

نمونه پاسخ:

[
  {
    "date": "2026-07-01",
    "low": 71000,
    "mid": 72500,
    "high": 74000
  },
  {
    "date": "2026-07-02",
    "low": 72000,
    "mid": 73500,
    "high": 75000
  }
]

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

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

نمونه پاسخ:

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

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

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

GET /api/v1/currency
GET /api/v1/gold
GET /api/v1/coin

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

data.datasets.currency
data.datasets.gold
data.datasets.coin

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

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

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

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

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

[
  {
    "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: کریپتو

GET /api/v1/crypto

داخل endpoint کلی:

data.datasets.crypto

نمونه پاسخ:

{
  "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: سهام شرکت های فولادی

GET /api/v1/steel-stocks

داخل endpoint کلی:

data.datasets.steel_stocks

نمونه پاسخ:

[
  {
    "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: کامودیتی های جهانی

GET /api/v1/commodity

داخل endpoint کلی:

data.datasets.commodity

نمونه پاسخ:

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

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

GET /api/v1/world-economy

داخل endpoint کلی:

data.datasets.world_economy

نمونه پاسخ:

[
  {
    "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 های موجود:

GET /api/v1/datasets

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

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	شاخص های اقتصاد کلان کشورها