مكتبة بايثون (Python SDK)

عميل بايثون الرسمي navvo هو غلاف من جهة الخادم لخدمة Navvo على الويب. وهو مكتوب بأنواع محدّدة، ويعيد المحاولة تلقائيًا، وبلا تبعيات — افتراضيًا يستخدم مكتبة بايثون القياسية فقط، فيُثبَّت ويعمل في أي بيئة؛ وإذا كانت httpx مُثبَّتة فسيستخدمها تلقائيًا لتجميع الاتصالات. لا يحتوي على واجهة خرائط ولا جلب بلاطات — لعرض خريطة في المتصفح استخدم خرائط Navvo.

يتطلّب: بايثون 3.8+ · عنوان الأساس: https://navvo.io/api/v1

التثبيت

pip install navvo
# نقل HTTP مجمّع اختياري:
pip install "navvo[httpx]"

المصادقة

تُرسَل كل طلبات الاستدعاء عبر ترويسة x-api-key. يُقرأ المفتاح من متغيّر البيئة NAVVO_API_KEY افتراضيًا، أو مرّره صراحةً:

from navvo import NavvoClient

navvo = NavvoClient()                       # يستخدم $NAVVO_API_KEY
navvo = NavvoClient("nvvo_your_key_here")   # صراحةً

لا تضع المكتبة المفتاح في الرابط أبدًا — باستثناء style_url() التي تبني رابط نمط خريطة يُجلب من المتصفح، حيث يجب تمرير المفتاح كـ ?api_key= (لا يمكن للمتصفحات إضافة ترويسات على طلبات النمط/البلاطات).

بداية سريعة

from navvo import NavvoClient, LatLng, BBox

with NavvoClient() as navvo:
    # ترميز جغرافي أمامي — تُحوَّل الإحداثيات النصية إلى أرقام تلقائيًا
    hits = navvo.geocode("مستشفى العبدلي، عمّان", limit=5)
    print(hits[0].lat, hits[0].lng, hits[0].display_name)

    # خطّط مسارًا — تمرّر lat/lng والمكتبة تُسلسل lon/lat على الشبكة
    plan = navvo.route(locations=[
        {"lat": 31.95, "lng": 35.91, "name": "A"},
        {"lat": 31.99, "lng": 35.95, "name": "B"},
    ], costing="auto")
    print("الوقت المتوقّع بالثواني:", plan.trip["summary"]["time"])
    path = plan.geometry()          # خطّ مرمّز مفكوك -> list[LatLng]

    # بيانات حيّة وفق الظروف
    wx = navvo.weather_point(31.95, 35.91)
    inc = navvo.incidents(bbox=BBox(35.85, 31.9, 35.99, 31.99), limit=10)

الإحداثيات — لن تنقلب أبدًا

تمرّر النقاط دائمًا كـ LatLng(lat=..., lng=...) (أو قاموس {"lat":.., "lng":..} أو صفّ (lat, lng)). تتولّى المكتبة كل اختلافات صيغة الشبكة: {lon, lat} لـ route()/traffic_route()، و{lat, lon} لحمولات تمرير المسارات، ومعاملات lat/lon منفصلة للترميز العكسي، وwest,south,east,north لـ BBox، و[lng, lat] لـ GeoJSON، وصيغة WKT POINT(lng lat) لمركز المكان (فُكّها عبر place.center_latlng).

إعادة المحاولة والأخطاء

تُعاد المحاولة على الأعطال العابرة (5xx، 429/الحصّة، انقطاعات الشبكة) بتراجع أُسّي مع تشويش كامل، مع احترام Retry-After؛ ولا يُعاد على أخطاء العميل (400/401/403/404). كل الأخطاء ترث من NavvoError:

from navvo.errors import (
    NavvoRateLimitError, NavvoForbiddenError, NavvoServiceUnavailableError,
)

try:
    r = navvo.geocode("مستشفى العبدلي، عمّان")
except NavvoRateLimitError as e:
    print("تجاوز الحدّ، أعد المحاولة بعد", e.retry_after, "ثانية")
except NavvoForbiddenError as e:
    print("مشكلة نطاق/حصّة:", e.reason or e.message)
except NavvoServiceUnavailableError:
    print("محرّك الترميز معطّل مؤقتًا — استخدم بديلًا")

يُفكّ غلاف الترميز/المسارات ({provider, available, data}) من أجلك تلقائيًا، ويُعيد slug مكان غير معروف القيمة None (قيمة فارغة ناعمة، وليست خطأً).

خريطة الدوال

تقابل كل دالة نقطة النهاية الموثّقة في مرجع الواجهة. تُعيد geocode وplaces وplace وroute وmatrix كائنات بأنواع محدّدة مع تحليل الحقول الشائعة والحفاظ على الحمولة الكاملة في .raw.