چگونه با یک API ایستگاه‌های حمل‌ونقل نزدیک را جستجو کنیم؟

برای جستجوی ایستگاه‌ها در اطراف یک نقطه، عرض جغرافیایی، طول جغرافیایی و شعاع آن را به یک API نزدیکی ارسال کنید. سپس وضعیت پاسخ، موجودیت‌های برگشتی و اطلاعات پوشش را بررسی کنید قبل از نمایش فهرست یا نقشه.

در قرارداد ROOTE roote-1.0.0، مسیر GET /v1/transit/nearby مکان‌های حمل‌ونقل نزدیک را کشف می‌کند. این مسیر، حرکت‌ها یا هشدارهای لحظه‌ای را بازیابی نمی‌کند. جستجوی مکان و جستجوی پاساژ بعدی دو عملیات جداگانه هستند.

تعریف پارامترها

در درخواست از lat برای عرض جغرافیایی و lng برای طول جغرافیایی استفاده می‌شود. مستعار lon نیز در قرارداد توضیح داده شده است. پارامتر radius شعاع را بر حسب متر بیان می‌کند؛ limit تعداد نتایج مورد درخواست را محدود می‌کند. فیلتر modes می‌تواند حالت‌های حمل‌ونقل را مشخص کند.

این مختصات نمونه‌ای برای جستجو در بوردو هستند؛ این مختصات تضمینی برای وجود ایستگاه نیستند. برای محدودیت‌ها، فیلدها و شرایط فعلی به قرارداد OpenAPI ROOTE مراجعه کنید.

ارسال اولین درخواست در سمت سرور

نمونه زیر کدی برای محیط 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 معتبر به تنهایی کفایت نمی‌کند؛ در محیط تولید، از اعتبارسنجی اشیا بر اساس طرح نیز استفاده کنید.

خواندن موجودیت‌ها و روابط آن‌ها

مجموعه stations مکان‌های برگشتی را شامل می‌شود. برای هرکدام، به خصوص id، name، entity_kind، location و distance_meters را بررسی کنید. ارجاعات line_ids و operator_ids امکان پیوند به مجموعه‌های lines و operators را در صورت وجود فراهم می‌کنند.

فاصله جغرافیایی را همان‌طور که هست نمایش دهید. آن را بدون محاسبه مسیر به زمان پیاده‌روی تبدیل نکنید. راهنمای پیدا کردن یک ایستگاه نزدیک توضیح می‌دهد چرا دسترسی‌ها ممکن است حرکت واقعی را تغییر دهند.

اطلاعات ناشناخته را نیز صراحتاً مدیریت کنید. در قرارداد، accessibility.wheelchair ممکن است مقدار unknown باشد: این مقدار معادل yes یا no نیست. داشتن ظرفیت اعلام شده برای حرکت‌ها به معنای فهرست حرکت‌ها نیست.

نمایش فهرست یا نقشه

برای ثبات عناصر رابط شناسه را استفاده کنید، نام را برای برچسب و location را برای موقعیت. خطوط را با استفاده از ارجاعات، نه نزدیک کردن نام‌ها، پیوند دهید.

اگر رنگ خطوط یا برچسب‌هایی از داده‌ها می‌آورید، آن‌ها را به عنوان ورودی خارجی که باید اعتبارسنجی شوند پردازش کنید. برای نام‌ها از متن استفاده کنید نه HTML تزریق‌شده.

حق مصادر را حفظ کنید و مواردی که قرارداد می‌گوید اجباری هستند را نمایش دهید.

مدیریت نتیجه خالی، پاسخ جزئی و خطا

نتیجه empty جستجویی بدون نتیجه در محدوده شناخته شده را توصیف می‌کند. این به معنای عدم وجود فیزیکی حمل‌ونقل نیست. پاسخ partial ممکن است مکان‌های مفیدی داشته باشد و در عین حال محدودیت‌ها را نشان دهد: نتایج و هشدار مناسب را ارائه دهید.

پوشش، هشدارها و محدودیت‌های اعمال‌شده در meta را بخوانید. فهرست کوتاه‌شده، پوشش جامع را توصیف نمی‌کند. در صورت بروز خطای شبکه یا HTTP، عدم دسترسی را نمایش دهید و نتیجه را با «هیچ ایستگاهی نیست» جایگزین نکنید.

برای کد 429، دستورالعمل‌های بازیابی و هدرهای احتمالی سرویس را بررسی کنید. از درخواست‌های مکرر در حلقه خودداری کنید.

تمایز بین ایستگاه‌ها، مناطق و سکوی انتظار

فیلد entity_kind سطوح مختلف مکان‌ها را متمایز می‌کند. دو نتیجه نزدیک ممکن است به سکوهای جداگانه تعلق داشته باشند؛ دو نام مشابه ممکن است متعلق به منابع مختلف باشند.

مکان‌ها را صرفاً بر اساس نزدیکی به طور خودکار ادغام نکنید. از روابط و شناسه‌های مستندسازی شده توسط سرویس استفاده کنید. راهنمای ما GTFS، GTFS-RT و GBFS زمینه داده‌ها را توضیح می‌دهد.

آماده‌سازی ادغام در تولید

زمانی که موقعیت یا فیلترها به شکل مفید تغییر می‌کنند، جستجوها را فعال کنید. تماس‌های یکسان را گروه‌بندی کنید، زمان انتظار تعریف کنید و حافظه کَش را بر اساس نوع داده و شرایط سرویس تنظیم کنید.

فهرست مکان‌ها و دسترسی زمان واقعی خواسته‌های تازه‌بودن متفاوتی دارند. مسیر را با پاسخ‌های کامل، خالی، جزئی و خطا اعتبارسنجی کنید قبل از نمایش جستجو به کاربران.

گسترش جستجو به خدمات شهری

ایستگاه‌ها و خدمات شهری از مسیرهای جداگانه‌ای استفاده می‌کنند. برای جستجوی دستشویی در اطراف همان نقطه، مسیر GET /v1/services/nearby مقادیر lat و lon را می‌طلبد، همراه با types=toilets. مقدار modes=toilets را به این مسیر ارسال نکنید: این اصطلاحات به آدرس نقشه مربوط است، نه فیلتر خدمات.

مثال JavaScript زیر یک URL خدمات را برای شعاع ۶۰۰ متر می‌سازد. این درخواست را فعال نمی‌کند؛ کنترل‌های HTTP و قراردادهای شرح داده شده در بالا را مجدداً استفاده کنید. مجموعه مورد انتظار به جای stations، services خواهد بود. 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());

تشخیص جستجوی خالی یا دارای خطا

ادغام مستقیم یک نقشه پالایش‌شده در یک سایت

ساخت یک دستیار بر پایه این جستجوها

پرسش‌های متداول

آیا Nearby حرکت‌های بعدی را فراهم می‌کند؟

خیر، در این قرارداد ارائه‌شده این مسیر مکان‌های حمل‌ونقل را کشف می‌کند؛ حرکت‌ها نیازمند ظرفیت جداگانه هستند.

آیا می‌توان پس از خطا فهرست خالی نمایش داد؟

عدم دسترسی را نمایش دهید. خطا دلیل بر نبود ایستگاه نیست.

آیا می‌توان توکن API را در مرورگر قرار داد؟

رمز نباید در سمت کلاینت باشد. از مدل دسترسی برنامه و حساب خود پیروی کنید.