التوثيق

عشرةُ مسارات. وهذه الصفحةُ ومواصفةُ OpenAPI تُولَدان من المصدر نفسِه، فلا تنحرف إحداهما عن الأخرى.

العنوانُ الأساس

https://nafarat.app/v1

المصادقة

Authorization: Bearer nfr_live_…

أو X-Nafarat-Key: nfr_live_…

مواصفةُ OpenAPI 3.1 جاهزةٌ للتوليد الآليّ للعملاء: GET /v1/openapi.json — مفتوحةٌ بلا مفتاح.

دليلُ الربط الكامل — للقراءة والطباعة والمشاركة مع فريقك

المفاتيحُ (live وtest) والمصادقة، وكلُّ مسارٍ بردٍّ حقيقيّ، والحدودُ والأخطاء، وأمثلةٌ كاملةٌ بـJavaScript وPython وPHP وDart، وقائمةُ تحقّقٍ قبل الإطلاق. PDF · 24 صفحة · 315 ك.ب · 16 تشرين الأوّل 2026

تنزيل الدليل

المسارات

المسار	ماذا يفعل	مفتاح؟
GET /v1/coverage	التغطيةُ وجودتُها لكلّ محافظة	مفتوح
GET /v1/data-version	بصمةُ إصدار البيانات الحاليّ وتاريخُه	مفتوح
GET /v1/geocode/reverse	اسمُ المكان عند إحداثيّة	نعم
GET /v1/geocode/search	بحثُ الأماكن بالاسم	نعم
GET /v1/openapi.json	هذه المواصفة	مفتوح
GET /v1/routes	قائمةُ الخطوط — مُرشَّحةٌ بنطاق الاشتراك	نعم
GET /v1/routes/{id}	تفصيلُ خطٍّ: محطّاتُه وهندستُه وأجرتُه	نعم
POST /v1/routing/plan	تخطيطُ رحلةٍ بين نقطتين	نعم
GET /v1/stations	محطّاتٌ قربَ نقطةٍ أو داخلَ مستطيل	نعم
GET /v1/usage	استهلاكُ الاشتراك وحصّتُه — لا يُحسب من الحصّة	نعم

الترويساتُ في كلّ ردّ

الترويسة	ماذا تعني
`X-RateLimit-Limit` / `-Remaining` / `-Reset`	سقفُك اللحظيُّ في الثانية، والمتبقّي منه — مقيسٌ من العدّاد لا مطروحٌ تقديراً.
`X-Quota-Limit` / `-Remaining`	حصّةُ المدّة والمتبقّي منها — للاشتراك كلِّه: مفاتيحُك تتقاسمها وتتقاسم السقفَ اللحظيّ. و`GET /v1/usage` لا يُحتسب منها.
`X-Quota-Reset`	لحظةُ التصفير — نهايةُ مدّة اشتراكك لا أوّلُ الشهر الميلاديّ.
`X-Subscription-Status`	`active` أو `grace`. و`grace` تعني أن مدّتك انتهت وتعمل بمهلة ٧٢ ساعة — جدّد.
`X-Nafarat-Scope`	المحافظاتُ المشمولةُ باشتراكك، مفصولةً بفاصلة.
`X-Nafarat-Data-Version`	بصمةُ إصدار البيانات التي أُجيب بها. اذكرها في أيّ مقارنةٍ بين ردّين.
`X-Request-Id`	معرّفُ الطلب. اذكره في كلّ بلاغِ دعم — به نجد طلبَك بعينه.

GET /v1/coverage

التغطيةُ وجودتُها لكلّ محافظة Coverage and measured quality per governorate

مثال

curl 'https://nafarat.app/v1/coverage'

GET /v1/data-version

بصمةُ إصدار البيانات الحاليّ وتاريخُه Current data version fingerprint and its date

مثال

curl 'https://nafarat.app/v1/data-version'

GET /v1/geocode/reverse

اسمُ المكان عند إحداثيّة Place name at a coordinate

المعاملات

المعامل	النوع	إلزاميّ	الوصف
`lat`	number	نعم
`lng`	number	نعم

مثال

curl 'https://nafarat.app/v1/geocode/reverse' \
  -H 'Authorization: Bearer nfr_live_…'

GET /v1/geocode/search

بحثُ الأماكن بالاسم Search places by name

المعاملات

المعامل	النوع	إلزاميّ	الوصف
`q`	string	نعم	النصُّ المبحوث (حرفان فأكثر)
`near_lat`	number	لا	ترجيحٌ بالقرب — مع near_lng
`near_lng`	number	لا
`limit`	integer	لا	١–٢٠ · الافتراض ١٠

مثال

curl 'https://nafarat.app/v1/geocode/search' \
  -H 'Authorization: Bearer nfr_live_…'

GET /v1/openapi.json

هذه المواصفة This specification

مثال

curl 'https://nafarat.app/v1/openapi.json'

GET /v1/routes

قائمةُ الخطوط — مُرشَّحةٌ بنطاق الاشتراك List routes, filtered by subscription scope

المعاملات

المعامل	النوع	إلزاميّ	الوصف
`governorate`	string	لا	اسمُ المحافظة
`vehicle_type`	string	لا	نوعُ المركبة
`q`	string	لا	بحثٌ في الاسم
`page`	integer	لا	الافتراض ١
`per_page`	integer	لا	١–٢٠٠ · الافتراض ٥٠

مثال

curl 'https://nafarat.app/v1/routes' \
  -H 'Authorization: Bearer nfr_live_…'

GET /v1/routes/{id}

تفصيلُ خطٍّ: محطّاتُه وهندستُه وأجرتُه Route detail: stations, geometry and fares

المعاملات

المعامل	النوع	إلزاميّ	الوصف
`id`	integer	نعم	معرّفُ الخطّ

مثال

curl 'https://nafarat.app/v1/routes/1' \
  -H 'Authorization: Bearer nfr_live_…'

POST /v1/routing/plan

تخطيطُ رحلةٍ بين نقطتين Plan a trip between two points

جسمُ الطلب (JSON)

الحقل	النوع	إلزاميّ	الوصف
`from`	object	نعم	نقطةُ الانطلاق {lat,lng}
`to`	object	نعم	نقطةُ الوصول {lat,lng}
`priority`	string	لا	fastest \| cheapest \| least_walking
`max_results`	integer	لا	١–١٠ · الافتراض ٣

مثال

curl -X POST 'https://nafarat.app/v1/routing/plan' \
  -H 'Authorization: Bearer nfr_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"from":{"lat":33.3086,"lng":44.4009},"to":{"lat":33.3400,"lng":44.4300}}'

GET /v1/stations

محطّاتٌ قربَ نقطةٍ أو داخلَ مستطيل Stations near a point or inside a bounding box

المعاملات

المعامل	النوع	إلزاميّ	الوصف
`lat`	number	لا	مع lng — صيغةُ القرب
`lng`	number	لا	مع lat
`radius_km`	number	لا	٠٫٠٥–٥ · الافتراض ١
`north`	number	لا	مع south وeast وwest — صيغةُ المستطيل
`south`	number	لا
`east`	number	لا
`west`	number	لا
`limit`	integer	لا	١–٣٠٠ · الافتراض ١٠٠

مثال

curl 'https://nafarat.app/v1/stations' \
  -H 'Authorization: Bearer nfr_live_…'

GET /v1/usage

استهلاكُ الاشتراك وحصّتُه — لا يُحسب من الحصّة Subscription usage and quota — not counted against the quota

المعاملات

المعامل	النوع	إلزاميّ	الوصف
`days`	integer	لا	١–٩٠ · الافتراض ٣٠

مثال

curl 'https://nafarat.app/v1/usage' \
  -H 'Authorization: Bearer nfr_live_…'

قبل أن تبني: اقرأ التغطية — نجاحُ التوجيه يختلف بين محافظةٍ وأخرى، والزمنُ مقدَّرٌ لا مرصود في أكثر الخطوط. ثمّ الأخطاء لتعرف ما يُحتسب من حصّتك وما لا يُحتسب.