কিভাবে একটি API ব্যবহার করে নিকটবর্তী পরিবহন স্টপগুলি খুঁজবেন?

কোনো স্থানের আশে-পাশের স্টপগুলি খুঁজতে, তার অক্ষাংশ, দ্রাঘিমাংশ এবং একটি রেডিয়াস একটি নিকটবর্তী API-তে সরবরাহ করুন। পরে প্রতিক্রিয়ার অবস্থা, ফেরানো সত্তাগুলি এবং কভারেজ তথ্য যাচাই করে তালিকা বা মানচিত্র দেখান।

ROOTE roote-1.0.0 চুক্তিতে, GET /v1/transit/nearby রুট নিকটবর্তী পরিবহন স্থান আবিষ্কার করে। এটি রিয়েল-টাইমে ক্লান্তি বা সতর্কতা সংগ্রহ করে না। একটি স্থান খোঁজা এবং এর পরবর্তী প্রস্থান অনুসন্ধান দুটি পৃথক অপারেশন।

প্যারামিটার নির্ধারণ করুন

অনুরোধে lat অক্ষাংশ এবং lng দ্রাঘিমাংশ হিসাবে ব্যবহৃত হয়। lon নামে একটি উপনামও চুক্তিতে উল্লেখ আছে। radius প্যারামিটারটি মিটার হিসেবে রেডিয়াস প্রকাশ করে; limit অনুরোধকৃত ফলাফলের সংখ্যা নির্ধারণ করে। modes ফিল্টার পরিবহন মোড নির্দিষ্ট করতে পারে।

এই স্থানাংকগুলি বোর্দো শহরের একটি অনুসন্ধানের উদাহরণ; সেগুলি কোনও নিশ্চিহ্নিত স্টপ নির্দেশ করে না। বর্তমান সীমাবদ্ধতা, ক্ষেত্র এবং শর্তাবলীর জন্য ROOTE OpenAPI চুক্তি দেখুন ।

সার্ভার সাইড থেকে প্রথম অনুরোধ পাঠান

Node.js পরিবেশে fetch সহ একটি JavaScript উদাহরণ এখানে দেওয়া হলো। আপনার যদি একটি টোকেন থাকে তবে সেটি সার্ভার সাইডের পরিবেশ ভেরিয়েবল হিসেবে থাকবে। উদাহরণটি ব্রাউজারে কোনও সিক্রেট রাখার প্রয়োজন রাখে না।

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 মান পেতে পারে যা হ্যাঁ কিংবা না নয়। ঘোষণা করা প্রস্থান সম্ভাবনা তালিকা নয়।

তালিকা বা মানচিত্র প্রদর্শন করুন

ইন্টারফেস আইটেম স্থিতিশীল করতে id, তাদের লেবেল করতে name এবং অবস্থান করতে location ব্যবহার করুন। লাইনগুলি নামের তুলনা না করে রেফারেন্স দ্বারা যুক্ত করুন।

লাইন রঙ বা লেবেল ডেটা থেকে প্রদর্শন করলে এগুলি বাইরের ইনপুট হিসেবে যাচাই করুন। নামের জন্য HTML ইনজেকশন না করে টেক্সট ব্যবহার করুন।

উৎসের অট্রিবিউশন সংরক্ষণ করুন এবং চুক্তি নির্দেশ করা অট্রিবিউশন প্রদর্শন করুন।

শূন্য ফলাফল, আংশিক ফলাফল ও ত্রুটি পরিচালনা করুন

empty ফলাফল মানে পরিচিত এলাকায় কোন ফলাফল নেই; এটি পরিবহনের শারীরিক অভাব নির্দেশ করে না। partial উত্তর সীমাবদ্ধতা প্রদর্শন করতে পারে; ফলাফল ও সংশ্লিষ্ট সতর্কতা দেখান।

coverage, warnings এবং meta-র সীমাবদ্ধতা পড়ুন। কাটছাঁট করা তালিকা পূর্ণ কভারেজ নয়। নেটওয়ার্ক বা HTTP ত্রুটিতে "কোন স্টপ নেই" দিয়ে ফলাফল প্রতিস্থাপন না করে অসুবিধা দেখান।

429 কোডে পুনরায় চেষ্টার নির্দেশনা ও সার্ভিসের হেডারগুলি দেখুন। লুপ পুনরায় চেষ্টা এড়িয়ে চলুন।

স্টেশন, জোন ও প্ল্যাটফর্ম পার্থক্য করুন

entity_kind ক্ষেত্র বিভিন্ন স্থান স্তর চিহ্নিত করে। দুই কাছাকাছি ফলাফল আলাদা প্ল্যাটফর্ম হতে পারে; দুই মিল থাকা একই নাম বিভিন্ন উৎস হতে পারে।

শুধুমাত্র কাছাকাছি দ্বারা জায়গা স্বয়ংক্রিয়ভাবে মিলিয়ে ফেলবেন না। পরিষেবা দস্তাবেজ অনুযায়ী সম্পর্ক ও পরিচয় ব্যবহার করুন। আমাদের গাইড GTFS, GTFS-RT এবং GBFS তথ্য প্রেক্ষাপট ব্যাখ্যা করে।

প্রোডাকশনে ইন্টিগ্রেশন প্রস্তুত করুন

অবস্থান বা ফিল্টার কার্যকর পরিবর্তনের সময় অনুসন্ধান শুরু করুন। সমান বিমূর্ত কল গোষ্ঠীবদ্ধ করুন, টাইমআউট নির্ধারণ করুন এবং ডেটা ধরনের ও সার্ভিস শর্তের জন্য ক্যাশ সামঞ্জস্য করুন।

স্থান তালিকা এবং রিয়েল-টাইম উপলভ্যতা আলাদা নতুনত্ব প্রয়োজন। পূর্ণ, শূন্য, আংশিক ও ত্রুটিপূর্ণ প্রতিক্রিয়া যাচাই করুন যাতে ভাল অনুসন্ধান দর্শন প্রদান করতে পারেন।

শহুরে সেবাসমূহে অনুসন্ধান প্রসারিত করা

স্টপ এবং শহুরে সেবাসমূহ আলাদা রোড ব্যবহার করে। একই স্থানের আশেপাশে টয়লেট খুঁজতে, GET /v1/services/nearby রোডটিতে lat এবং lon প্রেরণ করুন, সাথে types=toilets। এই রোডে modes=toilets পাঠাবেন না: এই শব্দটি মানচিত্রের URL এর জন্য, Services ফিল্টারের জন্য নয়।

নিম্নলিখিত JavaScript উদাহরণটি ৬০০ মিটার ব্যাসার্ধের জন্য একটি সার্ভিস URL তৈরি করে। এটি অনুরোধ প্রেরণ করে না; উপরোক্ত HTTP এবং চুক্তি নিয়ন্ত্রণগুলি পুনরায় ব্যবহার করুন। প্রত্যাশিত সংগ্রহ services হবে, stations নয়। service_type, location, distance_meters এবং প্রকৃত উপস্থিত অ্যাট্রিবিউটগুলি সংরক্ষণ করুন।

REST চুক্তিটি বিশেষত toilets, drinking_water, fountain, wifi, parking, charging, aed এবং locker ডকুমেন্ট করে। MCP এর মাধ্যমে প্রকাশিত ধরনেরা পার্থক্য হতে পারে। গৃহীত প্যারামিটার, তাদের সীমা এবং আপনার প্রবেশাধিকার সীমার জন্য ব্যবহৃত ইন্টারফেসের স্কিমা দেখুন।

যে কোনো সার্ভিসের অ্যাট্রিবিউটগুলি অনুসন্ধানের সময়ে তার খোলা থাকার নিশ্চয়তা দেয় না। অজানা অ্যাক্সেসযোগ্যতা মানে সার্ভিস অনুপলব্ধ নয়; ত্রুটির কারণে খালি তালিকা টয়লেটের অনুপস্থিতির প্রমাণ নয়। প্রতিটি পরিবারের ডেটা আলাদা রেখে শুধু নাম এবং স্থান এ সংকুচিত করবেন না।

একটি সম্মিলিত মানচিত্রের জন্য, ফলাফলগুলো তাদের পরিবার এবং পরিচায়কসহ যুক্ত করুন। Transit দ্বারা প্রদত্ত স্টপগুলো মুছে না ফেলে Services ত্রুটি প্রদর্শন করুন। অনুসন্ধান একই কেন্দ্রের দিকে থাকবে, তবে অবস্থা এবং কাভারেজ ভিন্ন হতে পারে।

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 টোকেন কি ব্রাউজারে রাখা যাবে?

গোপন তথ্য অবশ্যই সার্ভার সাইডে থাকতে হবে। আপনার অ্যাপ ও অ্যাকাউন্টে নির্ধারিত অ্যাক্সেস মডেল ব্যবহার করুন।