Bagaimana cara mencari perhentian pengangkutan berhampiran menggunakan API?

Untuk mencari perhentian sekitar satu titik, hantar latitud, longitud dan radiusnya ke API berdekatan. Periksa status jawapan, entiti yang dikembalikan dan maklumat liputan sebelum memaparkan senarai atau peta.

Dalam kontrak ROOTE roote-1.0.0, laluan GET /v1/transit/nearby menjejaki lokasi pengangkutan berhampiran. Ia tidak mengambil keberangkatan atau amaran masa nyata. Pencarian lokasi dan pencarian perjalanan seterusnya adalah dua operasi berasingan.

Tetapkan parameter

Permintaan menggunakan lat untuk latitud dan lng untuk longitud. Alias lon juga diterangkan dalam kontrak. Parameter radius menyatakan radius dalam meter; limit mengehadkan bilangan keputusan yang diminta. Penapis modes boleh menentukan mod pengangkutan.

Koordinat ini adalah contoh carian di Bordeaux; ia tidak menjamin perhentian sebenar. Sila rujuk kontrak OpenAPI ROOTE untuk batasan, medan dan syarat terkini.

Hantar permintaan pertama dari pelayan

Berikut adalah contoh JavaScript untuk persekitaran Node.js dengan fetch. Token, jika digunakan, disimpan dalam pembolehubah persekitaran pelayan. Contoh ini tidak memerlukan rahsia di pelayar.

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
  };
}

Kontrak yang dirujuk menyediakan akses tanpa nama atau token, mengikut polisi yang berkuat kuasa. Sahkan hak dan had akses anda. Jawapan HTTP yang betul tidak menggantikan pengesahan kandungan; dalam pengeluaran, gunakan juga pengesahan objek mengikut skema.

Baca entiti dan hubungan mereka

Koleksi stations mengandungi lokasi yang dikembalikan. Untuk setiap satu, periksa terutamanya id, name, entity_kind, location dan distance_meters. Rujukan line_ids dan operator_ids membolehkan penggabungan koleksi lines dan operators apabila disediakan.

Paparkan jarak geografi sebagai jarak. Jangan tukar menjadi masa berjalan tanpa pengiraan laluan. Panduan mencari perhentian berhampiran menjelaskan mengapa akses boleh mengubah perjalanan sebenar.

Juga, uruskan maklumat tidak diketahui secara jelas. Dalam kontrak, accessibility.wheelchair boleh bernilai unknown: nilai ini bukan yes atau no. Keupayaan keberangkatan yang diumumkan bukan senarai keberangkatan sebenar.

Paparkan senarai atau peta

Gunakan ID untuk menstabilkan elemen antara muka, nama untuk label dan lokasi untuk posisi. Kaitkan laluan melalui rujukan, bukan dengan menghampirkan nama.

Jika anda memaparkan warna laluan atau label daripada data, anggap ia sebagai input luaran yang perlu disahkan. Untuk nama, gunakan teks, bukan HTML yang disuntik.

Simpan penjelasan sumber dan paparkan yang diwajibkan kontrak.

Urus keputusan kosong, jawapan separa dan ralat

Keputusan empty menerangkan carian tanpa hasil dalam julat diketahui. Ia tidak membuktikan ketiadaan pengangkutan fizikal. Jawapan partial mungkin mengandungi lokasi berguna dan juga amaran batas: tunjukkan hasil dan amaran berkaitan.

Baca coverage, warnings dan had dalam meta. Senarai yang dipotong bukan liputan penuh. Jika berlaku ralat rangkaian atau HTTP, paparkan ketidaktersediaan tanpa menggantikan hasil dengan 'tiada perhentian'.

Untuk kod 429, rujuk arahan pemulihan dan tajuk perkhidmatan. Elak cuba semula secara berulang.

Bezakan stesen, zon dan platform

Medan entity_kind membezakan peringkat lokasi. Dua keputusan bersebelahan mungkin platform berbeza; dua nama serupa mungkin dari sumber berlainan.

Jangan gabungkan lokasi hanya berdasarkan kesesakan. Gunakan hubungan dan identiti yang didokumentasi oleh perkhidmatan. Panduan kami GTFS, GTFS-RT dan GBFS menerangkan konteks data.

Sediakan integrasi produksi

Mula pencarian apabila kedudukan atau penapis berubah berguna. Gabung panggilan serupa, tetapkan had masa dan sesuaikan cache mengikut jenis data dan keadaan perkhidmatan.

Senarai lokasi dan ketersediaan masa nyata mempunyai keperluan kesegaran berbeza. Uji kelancaran dengan jawapan lengkap, kosong, separa dan ralat sebelum tampilkan carian kepada pengguna.

Kembangkan pencarian kepada perkhidmatan bandar

Perhentian dan perkhidmatan bandar menggunakan laluan berbeza. Untuk mencari tandas di sekitar titik yang sama, laluan GET /v1/services/nearby memerlukan lat dan lon, dengan types=toilets. Jangan hantar modes=toilets ke laluan ini: kosa kata itu milik URL peta, bukan penapis Perkhidmatan.

Contoh JavaScript berikut membina URL Perkhidmatan untuk radius 600 meter. Ia tidak menghantar permintaan; gunakan semula kawalan HTTP dan kontrak yang diterangkan sebelum ini. Koleksi yang dijangka menjadi services, bukan stations. Simpan service_type, location, distance_meters dan atribut yang benar-benar ada.

Kontrak REST mendokumentasikan antaranya toilets, drinking_water, fountain, wifi, parking, charging, aed dan locker. Jenis yang didedahkan oleh MCP mungkin berbeza. Untuk parameter diterima, had dan batasan akses anda, rujuk skema antara muka yang digunakan.

Atribut perkhidmatan tidak menjamin ia dibuka semasa pencarian. Kebolehcapaian yang tidak diketahui bukan bermakna perkhidmatan tidak boleh diakses; senarai kosong akibat ralat tidak membuktikan tiada tandas. Simpan data khusus setiap keluarga daripada hanya menukarnya kepada nama dan titik.

Untuk peta gabungan, kaitkan hasil kepada keluarga dan pengenalan mereka. Paparkan ralat Perkhidmatan tanpa memadam perhentian yang dikembalikan oleh Transit. Pencarian kekal tertumpu pada titik yang sama, tetapi status dan liputan boleh berbeza.

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());

Mendiagnosis pencarian kosong atau ralat

Teruskan memasukkan peta yang ditapis ke dalam laman web

Membina pembantu di sekitar pencarian ini

Soalan Lazim

Adakah Nearby menyediakan keberangkatan seterusnya?

Tidak dalam kontrak yang ditunjukkan sini. Laluan ini mencari lokasi pengangkutan; keberangkatan memerlukan kapasiti berasingan.

Bolehkah memaparkan senarai kosong selepas ralat?

Paparkan ketidaktersediaan. Ralat tidak buktikan ketiadaan perhentian.

Bolehkah letakkan token API dalam pelayar?

Rahsia harus kekal di pelayan. Gunakan model akses yang disediakan untuk aplikasi dan akaun anda.