JSON
JSON (JavaScript Object Notation) صيغة نصية لتبادل البيانات تُجمَّع فيها القيم في كائنات بين أقواس معقوفة ومصفوفات بين أقواس مربعة. تحددها RFC 8259 ومعيار ECMA-404، ونوع وسائطها application/json. يستجيب Genesis API أيضًا بصيغة JSON.
أنواع القيم
| النوع | مثال | في Python |
|---|---|---|
| كائن | {"coin": "BTC"} | dict |
| مصفوفة | [0.11, 0.45] | list |
| نص | "ByBit" | str |
| رقم | 214, 0.92 | int, float |
| منطقي | true, false | True, False |
| قيمة فارغة | null | None |
أسماء الحقول والنصوص تأخذ علامات اقتباس مزدوجة فقط. لا تعليقات في JSON، والفاصلة بعد العنصر الأخير تجعل المستند غير صالح.
استجابة Genesis API
مثال افتراضي لاستجابة نقطة النهاية /arbitrage/spot-spot: صف واحد مع حذف بعض الحقول.
{
"success": true,
"data": [
{
"coin": "FUEL",
"exchange_buy": "ByBit",
"exchange_sell": "Gate",
"spread_pct": 0.11,
"deposit_enabled_buy": true,
"volume_24h_sell": null
}
],
"meta": {
"count": 1,
"updated_at": 1783802410,
"freshness_sec": 10,
"plan": "pro"
}
}
لكل استجابة ناجحة من Genesis API الشكل نفسه: success علامة النجاح، وdata يحمل البيانات، وmeta يحمل عدد العناصر ووقت unix لبناء البيانات وتأخر التسليم في خطتك بالثواني وخطتك. القيمة null في volume_24h_sell تعني غياب البيانات، فلا تعاملها كصفر. التفاصيل في قسم صيغة الاستجابة.
التحليل في Python
import os
import requests
response = requests.get(
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot",
headers={"X-API-Key": os.environ["GENESIS_API_KEY"]},
params={"min_spread": 0.5},
timeout=10,
)
body = response.json() # JSON → dict
if not body["success"]:
print(body["error"]["code"], body["error"]["message"])
else:
for row in body["data"]:
vol = row["volume_24h_sell"] # null → None
vol = "n/a" if vol is None else f"${vol:,.0f}"
print(row["coin"], f"{row['spread_pct']}%", vol)
تحوّل response.json() نص الاستجابة إلى قاموس Python. إذا لم يكن الجسم JSON، كصفحة خطأ من وكيل مثلًا، ترفع الدالة requests.exceptions.JSONDecodeError. نجاح التحليل لا يعني نجاح الطلب: أخطاء Genesis API تصل بصيغة JSON نفسها مع "success": false وكائن error، وأكوادها في قسم الأخطاء.
انظر أيضًا: REST API، السبريد، صيغة الاستجابة وETag والأخطاء، الدرس: أول طلب API مع HTTP والترويسات وJSON.
أسئلة وأجوبة
كيف أحوّل updated_at إلى تاريخ؟
هو وقت unix بالثواني. في Python تعطي datetime.fromtimestamp(1783802410, timezone.utc) التاريخ 11 يوليو 2026، 20:40:10 بالتوقيت العالمي UTC.