مرجع الواجهة البرمجية

شحن المركبات الكهربائية وتوجيه المدى

اكتشاف محطات الشحن والتخطيط للمسارات المراعي لمدى البطارية مع توقّفات الشحن.

شحن المركبات الكهربائية وتوجيه المدى

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

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

تتكوّن هذه الواجهة من جزأين: اكتشاف المحطات (GET /ev/stations) للعثور على محطات الشحن داخل منطقة عرض، والتخطيط المراعي للمدى (POST /ev/plan) لتحويل رحلة من نقطة إلى أخرى إلى رحلة قابلة للتنفيذ مع توقّفات الشحن الصحيحة في الأماكن الصحيحة.

الإحداثيات. جميع المواقع كائنات { "lat": number, "lng": number } (خط العرض أولاً). معامل الاستعلام bbox في /ev/stations بصيغة west,south,east,north. المسافات بالكيلومترات؛ وحالة البطارية بالنسبة المئوية. تحمل كل استجابة الحقل provider: "navvo-ev".

GET /ev/stations

اكتشف محطات الشحن داخل منطقة عرض الخريطة، مع تصفية اختيارية حسب الحدّ الأدنى لقدرة الشحن. مثالي لرسم محطات الشحن على خريطة، أو بناء مُنتقي محطات، أو تحميل الممر مُسبقاً قبل التخطيط لرحلة.

النطاق المطلوب: places

curl -s "https://navvo.io/api/v1/ev/stations?bbox=35.85,31.90,36.00,32.00&minKw=50&limit=100" \
  -H "x-api-key: nvvo_YOUR_KEY"

معاملات الاستعلام

bbox

string required

مربع إحاطة منطقة العرض بصيغة west,south,east,north (خط الطول/خط العرض بالدرجات العشرية). تُعاد فقط المحطات الواقعة داخل هذا المربع.

minKw

number

الحدّ الأدنى لقدرة محطة الشحن بالكيلوواط. عند تعيينه، تُعاد فقط المحطات التي لا تقلّ قيمة maxKw لديها عن هذه القيمة — مثل minKw=50 لمحطات الشحن السريع بالتيار المستمر فقط. اتركه للحصول على جميع مستويات القدرة.

connector

string

مُرشّح نوع القابس (مطابقة جزئية غير حسّاسة لحالة الأحرف) — مثل CCS أو CHAdeMO أو Type2 أو Tesla أو GB/T. تُعاد فقط المحطات التي تملك قابساً واحداً على الأقل من هذا النوع. طابِق القابس الذي تحتاجه مركبتك.

available

boolean

عند 1/true، تُعاد فقط المحطات القابلة للاستخدام حالياً — وتُستبعَد المحطات ذات الحالة غير المتصلة / خارج الخدمة / غير المتاحة / المعطّلة.

network

string

تصفية حسب شبكة/مشغّل الشحن (مطابقة جزئية غير حسّاسة لحالة الأحرف). اكتشف الشبكات المتاحة عبر GET /ev/networks.

limit

number

العدد الأقصى للمحطات المُعادة. القيمة الافتراضية 100، والحدّ الأقصى 500. تُرتَّب المحطات تنازلياً حسب maxKw بحيث تأتي أقوى محطات الشحن أولاً.

تُعيد الاستجابة المرشّحات الفعّالة filters ({ minKw, connector, availableOnly, network }) لتأكيد ما طُبِّق. وتتجمّع المرشّحات — مثل ?minKw=50&connector=CCS&available=1 يعيد فقط محطات CCS السريعة العاملة.

الاستجابة

{
  "provider": "navvo-ev",
  "count": 2,
  "stations": [
    {
      "id": "ev_amman_abdali_01",
      "name": "Abdali Boulevard Fast Charge",
      "network": "Navvo EV Network",
      "lat": 31.9566,
      "lng": 35.9106,
      "connectors": [
        { "type": "CCS2", "kw": 150, "count": 2 },
        { "type": "Type2", "kw": 22, "count": 4 }
      ],
      "maxKw": 150,
      "status": "operational",
      "pricing": "0.085 JOD/kWh",
      "address": "Abdali Boulevard, Amman"
    },
    {
      "id": "ev_amman_mecca_02",
      "name": "Mecca Mall Charging Hub",
      "network": "Navvo EV Network",
      "lat": 31.9667,
      "lng": 35.8589,
      "connectors": [
        { "type": "CCS2", "kw": 60, "count": 2 },
        { "type": "CHAdeMO", "kw": 50, "count": 1 }
      ],
      "maxKw": 60,
      "status": "operational",
      "pricing": "0.090 JOD/kWh",
      "address": "Mecca Street, Amman"
    }
  ]
}

الحقل	النوع	الوصف
`provider`	string	دائماً `"navvo-ev"`.
`count`	number	عدد المحطات المُعادة (طول `stations`).
`stations[].id`	string	مُعرِّف ثابت للمحطة.
`stations[].name`	string	الاسم المعروض لموقع الشحن.
`stations[].network`	string	الشبكة المُشغِّلة التي تنتمي إليها المحطة.
`stations[].lat` / `lng`	number	إحداثيات المحطة.
`stations[].connectors[]`	array	مجموعات الموصِّلات: `type` (مثل `CCS2`، `Type2`، `CHAdeMO`، `GB/T`)، `kw` (القدرة لكل موصِّل)، `count` (عدد الموصِّلات من ذلك النوع).
`stations[].maxKw`	number	أعلى قدرة متاحة في الموقع (أقوى موصِّل). تُستخدم للتصفية والترتيب.
`stations[].status`	string	`"operational"` أو `"offline"` أو `"unknown"`.
`stations[].pricing`	string \| null	السعر بصيغة مقروءة (مثل `"0.085 JOD/kWh"`)، أو `null` عند عدم نشره.
`stations[].address`	string	أفضل عنوان معروف للشارع.

استخدم التصفية بـ minKw=50 لإظهار محطات الشحن السريع بالتيار المستمر فقط عند التخطيط لرحلة بين المدن — فمحطات التيار المتردّد البطيئة (maxKw من 7 إلى 22) نادراً ما تكون مفيدة لتوقّف شحن على طريق سريع.

GET /ev/networks

كتالوج شبكات/مشغّلي الشحن في البيانات، لكلٍّ عدد محطاته وأقوى شاحن فيه — لواجهة "تصفية حسب الشبكة". مرّر اسم شبكة إلى GET /ev/stations?network=.

curl -s "https://navvo.io/api/v1/ev/networks" -H "x-api-key: $NAVVO_API_KEY"

{
  "provider": "navvo-ev", "count": 2,
  "networks": [
    { "network": "Navvo Charge", "count": 6, "maxKw": 150 },
    { "network": "Desert Power", "count": 2, "maxKw": 120 }
  ]
}

الحقل	النوع	ملاحظات
`networks[].network`	string	اسم المشغّل (`"Unknown"` للمحطات بلا شبكة مُحدَّدة)
`networks[].count`	number	عدد محطات تلك الشبكة
`networks[].maxKw`	number	أقوى شاحن في تلك الشبكة

POST /ev/plan

تخطيط مسار مراعٍ للمدى. بإعطائه نقطة انطلاق ووجهة ومدى البطارية، يسير المُخطِّط على ممر مسار Navvo ويُدرِج أقوى محطة شحن قريبة كلما انخفض المدى المُتوقَّع دون احتياطي الأمان. ويُعيد ما إذا كانت الرحلة قابلة للتنفيذ وأين تُجرى التوقّفات بالضبط.

النطاق المطلوب: routing

يُسقِط المُخطِّط حالة البطارية على طول المسار. انطلاقاً من currentPercent، يستهلك المدى أثناء سيره على الممر؛ وكلما انخفض الشحن المُتوقَّع دون reservePercent قبل بلوغ محطة الشحن التالية القابلة للوصول، يبحث ضمن مسافة detourKm من المسار عن أقوى محطة تعمل، ويُدرِج توقّفاً عندها، ثم يستأنف الإسقاط من حالة مُعاد شحنها. وإذا كانت الفجوة أطول من أن تُجتاز حتى من شحن كامل، تُوسَم الرحلة بأنها غير قابلة للتنفيذ مع حقل reason.

جسم الطلب

from

object required

نقطة الانطلاق بصيغة { "lat": number, "lng": number }.

object required

الوجهة بصيغة { "lat": number, "lng": number }.

rangeKm

number required

مدى القيادة القابل للاستخدام عند بطارية ممتلئة، بالكيلومترات. هذا هو المدى الواقعي الذي تثق به، لا القيمة المتفائلة المُعلَنة.

currentPercent

number

حالة شحن البطارية الحالية بالنسبة المئوية. القيمة الافتراضية 80.

reservePercent

number

احتياطي الأمان — لا يسمح المُخطِّط أبداً للشحن المُتوقَّع بالانخفاض دون هذه القيمة قبل بلوغ محطة شحن. القيمة الافتراضية 15.

detourKm

number

أقصى انحراف مسموح به عن ممر المسار للوصول إلى محطة شحن، بالكيلومترات. القيمة الافتراضية 5.

{
  "from": { "lat": 31.9539, "lng": 35.9106 },
  "to": { "lat": 29.5321, "lng": 35.0061 },
  "rangeKm": 150,
  "currentPercent": 80,
  "reservePercent": 15,
  "detourKm": 5
}

الاستجابة

المسافة من عمّان (≈31.95، 35.91) إلى العقبة (≈29.53، 35.01) نحو 330 كم على الطريق الصحراوي. وبمركبة مداها الكامل 150 كم تنطلق بشحن 80% واحتياطي 15%، لا يكفي شحن واحد — فيُدرِج المُخطِّط توقّفين ليُبقي البطارية المُتوقَّعة فوق الاحتياطي طوال الطريق.

{
  "provider": "navvo-ev",
  "feasible": true,
  "chargingNeeded": true,
  "totalKm": 330.4,
  "stopCount": 2,
  "stops": [
    {
      "station": {
        "id": "ev_qatraneh_hwy_07",
        "name": "Al-Qatraneh Highway Charge",
        "network": "Navvo EV Network",
        "lat": 31.2522,
        "lng": 36.0489,
        "connectors": [ { "type": "CCS2", "kw": 120, "count": 2 } ],
        "maxKw": 120,
        "status": "operational",
        "pricing": "0.095 JOD/kWh",
        "address": "Desert Highway, Al-Qatraneh"
      },
      "atKm": 98.6,
      "detourKm": 1.2
    },
    {
      "station": {
        "id": "ev_maan_south_14",
        "name": "Ma'an South Fast Charge",
        "network": "Navvo EV Network",
        "lat": 30.1721,
        "lng": 35.7330,
        "connectors": [ { "type": "CCS2", "kw": 150, "count": 1 }, { "type": "CHAdeMO", "kw": 50, "count": 1 } ],
        "maxKw": 150,
        "status": "operational",
        "pricing": "0.090 JOD/kWh",
        "address": "Desert Highway, Ma'an"
      },
      "atKm": 218.3,
      "detourKm": 2.8
    }
  ]
}

الحقل	النوع	الوصف
`provider`	string	دائماً `"navvo-ev"`.
`feasible`	boolean	`true` إذا أمكن بلوغ الوجهة بالتوقّفات المُدرَجة؛ `false` إذا تعذّر اجتياز فجوة.
`chargingNeeded`	boolean	`false` عندما تتّسع الرحلة ضمن الشحن الحالي (لا حاجة لتوقّفات)؛ `true` خلاف ذلك.
`totalKm`	number	مسافة المسار الإجمالية بالكيلومترات.
`stopCount`	number	عدد توقّفات الشحن في `stops`.
`stops[].station`	object	المحطة المختارة — بالشكل نفسه لكائن المحطة في `GET /ev/stations`.
`stops[].atKm`	number	المسافة على طول المسار بالكيلومترات التي يقع عندها التوقّف.
`stops[].detourKm`	number	الانحراف عن ممر المسار للوصول إلى هذه المحطة (≤ قيمة `detourKm` لديك).
`reason`	string	موجود فقط عندما يكون `feasible` بقيمة `false` — يشرح سبب الفشل (مثل فجوة بين محطات الشحن أطول من المدى الكامل للمركبة).

عندما تتّسع الرحلة كاملةً ضمن الشحن الحالي، يختصر المُخطِّط المسار:

{
  "provider": "navvo-ev",
  "feasible": true,
  "chargingNeeded": false,
  "totalKm": 64.2,
  "stopCount": 0,
  "stops": []
}

وعندما يكون مقطعٌ ما ببساطة أطول من أن يُجتاز — لا توجد محطة شحن تعمل ضمن detourKm من الممر عبر فجوة أكبر من rangeKm — تكون الرحلة غير قابلة للتنفيذ:

{
  "provider": "navvo-ev",
  "feasible": false,
  "chargingNeeded": true,
  "totalKm": 412.0,
  "stopCount": 1,
  "stops": [ { "station": { "id": "ev_maan_south_14", "name": "Ma'an South Fast Charge", "maxKw": 150, "status": "operational" }, "atKm": 198.4, "detourKm": 2.8 } ],
  "reason": "No reachable charger within 5 km of the route for the 210 km stretch after Ma'an; reduce detour constraint or increase rangeKm."
}

تناسب القيم الافتراضية (currentPercent: 80، reservePercent: 15، detourKm: 5) رحلة نموذجية بين المدن. للسائقين الحذرين أو الأساطيل التجارية، ارفع reservePercent إلى 20–25 لبناء هامش أكبر؛ ووسِّع detourKm إذا مرّ المسار عبر مقاطع صحراوية متفرّقة قد تكون فيها أقرب محطة شحن على بُعد بضعة كيلومترات عن الطريق السريع.

تحقّق دائماً من feasible قبل عرض خطة على المستخدم. فالاستجابة بقيمة feasible: false لا تزال تُعيد أي توقّفات أمكن وضعها إضافةً إلى حقل reason — أظهِر هذا السبب ليتمكّن السائق من التعديل (الشحن أكثر قبل المغادرة، أو السماح بانحراف أطول، أو اختيار مركبة بمدى أعلى).

الأخطاء

الحالة	متى
`400`	التحقّق — مثل `bbox` غير صحيح، أو غياب `from`/`to`، أو `rangeKm` غير موجبة.
`401` / `403`	مفتاح مفقود/غير صالح، أو المفتاح يفتقر إلى النطاق المطلوب (`places` للمحطات، `routing` للتخطيط).

الملخّص

نقطة النهاية	النطاق	الجسم / الاستعلام	تُعيد
`GET /ev/stations`	`places`	`bbox`، `minKw?`، `limit?`	`{ provider, count, stations[] }`
`POST /ev/plan`	`routing`	`{ from, to, rangeKm, currentPercent?, reservePercent?, detourKm? }`	`{ provider, feasible, chargingNeeded, totalKm, stopCount, stops[], reason? }`

العطلات وحالة التشغيل

تقويمات العطلات للدول والمدن وحالة فتح الأماكن المراعية للعطلات.

النقل العام والتنقل الخفيف والوضع دون اتصال

محطات وخطوط النقل العام، ومحطات الدراجات والسكوترات، وتخطيط الرحلات، ومناطق الخريطة للعمل دون اتصال.