# كيف تبحث عن محطات النقل القريبة باستخدام API؟

> اكتشف كيفية البحث عن المحطات القريبة مع API الخاص بـ ROOTE: الإحداثيات، نصف القطر، مثال جافا سكريبت، قراءة النتائج وإدارة الأخطاء.

Source: https://www.roote.ai/ar/guides/kayfa-tabhat-an-nuqata-al-munqilat-al-muqarraba-bi-api/
Language: ar
Author: ROOTE

للبحث عن المحطات حول نقطة ما، قم بتمرير خطوط العرض والطول ونصف القطر إلى API القريب. تحقق بعد ذلك من حالة الرد، والكيانات المرجعة، ومعلومات التغطية قبل عرض القائمة أو الخريطة.

في العقد ROOTE roote-1.0.0، تتيح المسار GET /v1/transit/nearby اكتشاف أماكن النقل القريبة. لا تسترجع المغادرات أو التنبيهات في الوقت الحقيقي. البحث عن مكان ما والبحث عن مروره التالي هما عمليتان منفصلتان.

## تحديد المعلمات

تستخدم الطلب المتغير lat لخط العرض و lng لخط الطول. الاسم المستعار lon موصوف أيضًا في العقد. يعبر المعامل radius عن نصف القطر بالمتر؛ ويحدد limit العدد الأقصى للنتائج المطلوبة. يمكن لفلتر modes تحديد أنماط النقل.

| المُعامل | مثال | المعنى |
| --- | --- | --- |
| lat | 44.8378 | خط عرض نقطة البحث |
| lng | -0.5792 | خط طول نقطة البحث |
| radius | 600 | النصف القطر المطلوب بالمتر |
| limit | 10 | الحد الأقصى للنتائج المطلوبة |
| modes | bus,tram | أنماط النقل المطلوبة |

تُستخدم هذه الإحداثيات كمثال للبحث في بوردو؛ وهي لا تشير إلى محطة مضمونة. راجع [عقد OpenAPI الخاص بـ ROOTE](https://api.roote.ai/openapi.json) للحدود، الحقول والشروط الحالية.

## أرسل طلبًا أوليًا من جانب الخادم

إليك مثال جافا سكريبت لبيئة Node.js تدعم fetch. يحتفظ الرمز المميز، إذا استخدمت وصولًا به، في متغير بيئة على جانب الخادم. لا يتطلب المثال وضع سر في المتصفح.

```
async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
  const url = new URL('https://api.roote.ai/v1/transit/nearby');
  url.search = new URLSearchParams({
    lat: '44.8378',
    lng: '-0.5792',
    radius: '600',
    limit: '10',
    modes: 'bus,tram'
  }).toString();

  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;

  const response = await fetch(url, {
    headers,
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) {
    throw new Error(`Erreur HTTP ${response.status}`);
  }

  const data = await response.json();
  if (data.contract_version !== 'roote-1.0.0') {
    throw new Error('Version du contrat non reconnue');
  }
  if (!['success', 'empty', 'partial'].includes(data.status)) {
    throw new Error('Recherche indisponible');
  }
  if (!Array.isArray(data.stations)) {
    throw new Error('Réponse sans collection stations valide');
  }

  return {
    status: data.status,
    stations: data.stations,
    lines: data.lines,
    operators: data.operators,
    coverage: data.coverage,
    warnings: data.warnings,
    attributions: data.attributions,
    meta: data.meta
  };
}
```

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

## قراءة الكيانات وعلاقاتها

تحتوي مجموعة المحطات على الأماكن المرجعة. لكل منها، تحقق من id، name، entity_kind، location و distance_meters. تشير line_ids و operator_ids إلى مجموعات الخطوط والمشغلين إذا تم توفيرها.

اعرض مسافة جغرافية كما هي. لا تحولها إلى وقت مشي دون حساب المسار. يشرح الدليل [العثور على محطة قريبة](https://www.roote.ai/ar/guides/%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%A7%D9%84%D8%A8%D8%AD%D8%AB-%D8%B9%D9%86-%D8%A7%D9%82%D8%B1%D8%A8-%D9%85%D8%AD%D8%B7%D8%A9-%D8%AD%D8%A7%D9%81%D9%84%D8%A7%D8%AA-%D8%A7%D9%88-%D8%AA%D8%B1%D8%A7%D9%85/) لماذا قد تؤثر طرق الوصول على التنقل الفعلي.

عالج أيضًا المعلومات غير المعروفة بشكل صريح. قد يكون accessibility.wheelchair في العقد مساويًا لـ unknown: وهذه القيمة لا تعادل نعم ولا لا. القدرة المعلنة للمغادرات لا تمثل قائمة المغادرات.

## عرض قائمة أو خريطة

استخدم المعرف لتثبيت العناصر في الواجهة، والاسم لتسميتها، و location لموقعها. اربط الخطوط عبر المراجع وليس بجمع أسماءها.

إذا عرضت ألوان الخطوط أو التسميات من البيانات، فاخلطها كمدخلات خارجية يجب التحقق منها. استعمل نصًا للأسماء بدلًا من HTML مدخل.

احفظ نسب المصادر وعرض التي يحددها العقد كواجبة.

## إدارة النتيجة الفارغة، الرد الجزئي والخطأ

تعبر النتيجة الفارغة empty عن بحث لا يُرجع نتائج ضمن النطاق المعرف. هذا لا يعني انعدام النقل فعليًا. قد تحتوي الاستجابة partial على أماكن مفيدة مع تحذير: اعرض النتائج والتحذير المناسب.

اقرأ التغطية، التحذيرات والقيود في meta. لا تمثل القائمة المختصرة تغطية كاملة. في حالة خطأ شبكة أو HTTP، اعرض حالة عدم التوفر دون استبدال النتيجة بـ "لا توجد محطات".

بالنسبة للرمز 429، راجع تعليمات الاستئناف ورؤوس الخدمة المحتملة. تجنب إعادة الطلبات بشكل متكرر.

## تمييز المحطات، المناطق والارصفة

يفرق الحقل entity_kind بين مستويات متعددة للأماكن. قد تتعلق نتيجتان متجاورتان بأرصفة مختلفة؛ وقد تنتمي أسماء متشابهة إلى مصادر مختلفة.

لا تدمج الأماكن تلقائيًا بناءً على القرب فقط. استخدم العلاقات والهويات الموثقة من الخدمة. يشرح دليلنا [GTFS، GTFS-RT و GBFS](https://www.roote.ai/ar/guides/gtfs-gtfs-rt-wlgbfs-matha-farq/) سياق البيانات.

## التحضير للتكامل في الإنتاج

قم ببدء البحث عند تغيّر الموقع أو الفلاتر بشكل مفيد. اجمع الطلبات المتطابقة، حدد مهلة زمنية وعدل التخزين المؤقت حسب نوع البيانات وظروف الخدمة.

قائمة الأماكن وتوفر الوقت الحقيقي ليستا متطابقتين في متطلبات التحديث. تحقق من المسار مع ردود كاملة، فارغة، جزئية وأخطاء قبل عرض البحث للمستخدمين.

## توسيع البحث ليشمل الخدمات الحضرية

تستخدم المحطات والخدمات الحضرية مسارات منفصلة. للبحث عن دورات المياه حول نفس النقطة، تنتظر طريقة GET /v1/services/nearby معلمات lat و lon، مع types=toilets. لا ترسل modes=toilets إلى هذا المسار: هذه المصطلحات تخص عنوان URL للخريطة، وليست من فلتر الخدمات.

مثال جافا سكريبت التالي يبني عنوان URL للخدمات بنطاق 600 متر. لا يُطلق الطلب تلقائياً؛ أعد استخدام ضوابط HTTP والعقد التي ذُكرت أعلاه. المجموعة المتوقعة تصبح services بدلاً من stations. احتفظ بـ service_type و location و distance_meters والسمات الموجودة فعلياً.

توثق واجهة REST بشكل خاص أنواع toilets و drinking_water و fountain و wifi و parking و charging و aed و locker. قد تختلف الأنواع المعروضة من MCP. لمعرفة المعاملات المقبولة، حدودها، وقيود الوصول الخاصة بك، راجع مخطط الواجهة المستخدمة.

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

لخريطة مركبة، اربط النتائج بفئتها ومعرفاتها. اعرض خطأ في الخدمات دون مسح المحطات المرتجعة من Transit. يبقى البحث مركّزاً على نفس النقطة، لكن الحالات والتغطيات قد تختلف.

```
const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
  lat: '44.8416106', lon: '-0.5810938',
  radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());
```

[تشخيص بحث فارغ أو به خطأ](https://www.roote.ai/ar/guides/%D9%84%D8%A7-%D9%86%D8%AA%D8%A7%D8%A6%D8%AC-%D8%A7%D9%88-%D8%AE%D8%B7%D8%A3-%D9%81%D9%8A-%D9%88%D8%A7%D8%AC%D9%87%D8%A9-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D8%A7%D9%84%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-%D9%83%D9%8A%D9%81-%D9%86%D9%81%D8%B1%D9%82/)

[دمج خريطة مُرشحة مباشرة في موقع إلكتروني](https://www.roote.ai/ar/guides/kaifa-kharitat-taharruk-fi-mawqiak/)

[بناء مساعد حول هذه الأبحاث](https://www.roote.ai/ar/guides/%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%A5%D9%86%D8%B4%D8%A7%D8%A1-%D9%85%D8%B3%D8%A7%D8%B9%D8%AF-%D9%8A%D8%AC%D8%AF-%D9%88%D8%B3%D8%A7%D8%A6%D9%84-%D8%A7%D9%84%D9%86%D9%82%D9%84-%D8%AD%D9%88%D9%84-%D8%A7%D9%84%D8%B9%D9%86%D9%88%D8%A7%D9%86/)

## الأسئلة المتكررة

### هل يوفر Nearby المغادرات القادمة؟

ليس في العقد المعروض هنا. يكشف هذا المسار عن أماكن النقل؛ وتتطلب المغادرات قدرة منفصلة.

### هل يمكن عرض قائمة فارغة بعد خطأ؟

اعرض حالة عدم التوفر. الخطأ لا يثبت انعدام المحطات.

### هل يمكن وضع رمز API في المتصفح؟

يجب أن يبقى السر على جانب الخادم. استخدم نموذج الوصول المخصص لتطبيقك وحسابك.