لديك أسئلة أو مشكلات؟ اكتب في GitHub Discussions.

لا تحتاج إلى SDK. يعمل Frankfurter عبر HTTPS عادي ويُرجع JSON بسيطًا، فتكفيك مكتبة HTTP التي تستخدمها أصلًا. دون مفتاح API ودون حساب.

البدء السريع

احصل على سعر وحوّل المبلغ:

import requests

res = requests.get("https://api.frankfurter.dev/v2/rate/usd/eur")
data = res.json()
total = 100 * data["rate"]

الاستجابة كائن بسيط واحد: {"date": "2026-07-17", "base": "USD", "quote": "EUR", "rate": 0.8739}. ورمز العملة غير الصالح يُرجع 422 مع رسالة JSON.

حسابات آمنة للمبالغ المالية

الأعداد العشرية العائمة (float) مناسبة للعرض وخاطئة للمحاسبة. حلّل الأسعار بوصفها Decimal بتمرير parse_float إلى json.loads:

from decimal import Decimal

import requests

res = requests.get("https://api.frankfurter.dev/v2/rate/usd/eur")
data = res.json(parse_float=Decimal)
total = Decimal("100") * data["rate"]

عدة عملات دفعة واحدة

تُرجع /v2/rates مصفوفة بسيطة، بصف واحد لكل عملة مقابلة. حوّلها إلى قاموس بحث باستخدام comprehension. واحذف quotes للحصول على جميع العملات.

res = requests.get(
    "https://api.frankfurter.dev/v2/rates",
    params={"base": "usd", "quotes": "eur,gbp,jpy"},
)
rates = {row["quote"]: row["rate"] for row in res.json()}

خزّن ما لا يتغيّر

لا تتغير الأسعار التاريخية للمصدر المثبّت، فخزّنها مؤقتًا للمدة التي تريدها. أما الأسعار المدمجة فقد تتغير مع وصول بيانات جديدة، وتتغير أحدث الأسعار حين تنشر المصادر، بضع مرات في يوم العمل على الأكثر، لذا امنحها مدة صلاحية (TTL) قصيرة. ومع requests-cache، يكفي سطر واحد للتخزين المؤقت:

import requests_cache

session = requests_cache.CachedSession("frankfurter", expire_after=3600)
res = session.get("https://api.frankfurter.dev/v2/rate/usd/eur")
data = res.json()

البرمجة غير المتزامنة

في تطبيق ويب غير متزامن، استخدم httpx:

import httpx

API = "https://api.frankfurter.dev"


async def rate(base, quote):
    async with httpx.AsyncClient(base_url=API) as client:
        res = await client.get(f"/v2/rate/{base}/{quote}")
        res.raise_for_status()
        return res.json()["rate"]

تثبيت مصدر رسمي

تحصل افتراضيًا على السعر المدمج من جميع المصادر. أضف providers لتثبيت جهة واحدة بعينها، وهذا مهم حين تشترط جهة تنظيمية السعر الذي ينشره بنكها المركزي، مثل السعر المرجعي للبنك المركزي الأوروبي لضريبة القيمة المضافة في الاتحاد الأوروبي.

res = requests.get(
    "https://api.frankfurter.dev/v2/rate/usd/eur",
    params={"providers": "ecb"},
)
data = res.json()

تصفّح جميع المصادر. يتبع المصدر المثبّت جدول نشره الخاص، لذا قد يتأخر أحدث أسعاره عن أحدث سعر مدمج بيوم.

تحلّل سلسلة زمنية؟

لنطاقات التواريخ والتجميع الشهري والرسوم البيانية، تُحمَّل نقطة نهاية CSV مباشرة في DataFrame. راجع pandas.