כדי לחפש תחנות סביב נקודה מסוימת, העבר את קווי הרוחב, קווי האורך והרדיוס ל-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 עבור הגבולות, השדות והתנאים העדכניים.
מצא תחנות סביבך.
חקור תחנות שנרשמו סביב עיר או מיקומך. בדוק פרטים כדי לוודא אמצעי תחבורה ומידע זמין.
שליחת בקשה ראשונה בצד השרת
הנה דוגמת JavaScript לסביבת 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. קיבולת יציאות מצוינת אינה רשימת יציאות בפועל.
הצגת רשימה או מפה
השתמש ב-id לייצוב רכיבים בממשק, בשם לתווית וב-mocation למיקום. קשר קווים בהפניות במקום להתבסס על שמות דומים.
אם מציגים צבעי קווים או תוויות מהנתונים, התייחס אליהם כקלט חיצוני שיש לאמת. לשמות השתמש בטקסט ולא ב-HTML מוכנס.
שמור על קרדיטים למקורות והצג רק את הנדרשים בהסכם.
ניהול תוצאות ריקות, חלקיות ושגיאות
תוצאה empty מתארת חיפוש ללא תוצאות בתחום המוכר. זה אינו מוכיח העדר תחבורה פיזית. תגובה partial עשויה להכיל מקומות שימושיים לצד הגבלת נתונים: הצג תוצאות יחד עם אזהרה מתאימה.
קרא את coverage, warnings והמגבלות במטא. רשימה מקוצצת אינה מייצגת כיסוי מלא. במקרה שגיאת רשת או HTTP, הצג הודעת חוסר זמינות מבלי להחליף בתוצאה של "אין תחנה".
לקוד 429 עיין בהנחיות ההתאוששות ובכותרות השירות. הימנע מחזרות ללא הפסקה.
הבחנה בין תחנות, אזורים ורציפים
שדה entity_kind מבדיל רמות שונות של מיקומים. תוצאות סמוכות עשויות להיות רציפים נפרדים; שמות דומים שייכים למקורות שונים.
אל תאחד מקומות בגלל קרבה בלבד. השתמש בקשרים ובזהויות המתועדים על ידי השירות. המדריך שלנו GTFS, GTFS-RT ו-GBFS מסביר את הקשר של הנתונים.
הכנה לשילוב בפרודקשן
הפעל חיפושים כשמיקום או מסננים משתנים בצורה משמעותית. איחד קריאות זהות, הגדר טיימאאוט והתאם קאש לסוג הנתונים ותנאי השירות.
רשימת מקומות וזמינות בזמן אמת דורשות רעננות שונה. אמת מסלולים עם תגובות מלאות, ריקות, חלקיות ושגיאתיות לפני הצגת החיפוש למשתמשים.
להרחיב את החיפוש לשירותים עירוניים
תחנות ושירותים עירוניים משתמשים בנתיבים נפרדים. כדי לחפש שירותים סביב נקודה זהה, ה-GET /v1/services/nearby מצפה ל-lat ו-lon, עם types=toilets. אל תשלחו modes=toilets לנתיב זה: אוצר מילים זה שייך לכתובת המפה, לא לסינון Services.
דוגמת ה-JavaScript הבאה בונה כתובת URL לשירותים עבור רדיוס של 600 מטרים. היא אינה מפעילה את הבקשה; השתמשו שוב בבקרות HTTP ובעסקה שתוארו למעלה. האוסף הצפוי הוא services, במקום stations. שמרו על service_type, location, distance_meters והתכונות שקיימות בפועל.
העסקה של REST מתעדת בין היתר toilets, drinking_water, fountain, wifi, parking, charging, aed ו-locker. הסוגים המוצגים ב-MCP עשויים להשתנות. לפרמטרים הנתמכים, התחומים והמגבלות של הגישה שלכם, ראו את הסכימה של הממשק בשימוש.
התכונות של שירות אינן מבטיחות שהוא פתוח בזמן החיפוש. נגישות לא ידועה אינה שקולה לשירות בלתי נגיש; רשימה ריקה כתוצאה משגיאה אינה מוכיחה היעדר שירותים. שמרו על נתונים נקיים לכל משפחה במקום לצמצם לשם ונקודה.
למפה משולבת, קשרו את התוצאות למשפחתן ולמזהים שלהן. הציגו שגיאת Services מבלי למחוק את התחנות שהוחזרו על ידי 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 בדפדפן?
סוד חייב להישאר בצד השרת. השתמש בדגם הגישה המתוכנן לאפליקציה ולחשבון שלך.