בדרך (On The Way) — תיעוד ל-API ולסוכני AI
הכול כאן ציבורי, ללא מפתח API וללא הרשמה. הדף הזה הוא נקודת הכניסה למפתחים, לכלי מחקר ולסוכני AI שרוצים לקרוא את מאגר המקומות של בדרך.
מתי כדאי לסוכן להשתמש בבדרך
- המשתמש מחפש איפה לאכול, לטייל, לישון או לעצור בישראל — לפי עיר, לפי אזור, או לפי נקודת מוצא ויעד של נסיעה.
- צריך מקומות לאורך מסלול ולא רק ברדיוס מנקודה אחת ("מה יש בדרך מתל אביב לאילת ברדיוס 5 ק״מ").
- צריך סינון ישראלי-ספציפי שקשה למצוא במקום אחר: כשרות (כולל סוג ההשגחה וכשרות לפסח), טבעוני, ללא גלוטן, בשרי/חלבי, נגישות לכיסא גלגלים, מקומות ידידותיים למילואימניקים.
- צריך שכבות טבע חופשיות: מעיינות, נחלים, תצפיות, חופים ופארקים — עם פרטים כמו צל, מים זורמים והתאמה לילדים.
- צריך לדעת מה פתוח עכשיו בשעה נתונה, לפי שעות הפתיחה השבועיות השמורות לכל מקום.
ומתי לא
- רוב המאגר הוא ישראל (חינם). קיימות גם מפות של יעדים אחרים בעולם בגישה בתשלום — ראה /destinations — אך אלה קטנות ובשלבים מוקדמים.
- הזמנת שולחן, הזמנת חדר או תשלום: בדרך מפנה לאתר או לטלפון של העסק ואינו מבצע הזמנות.
- ביקורות משתמשים מפורטות או דירוג בזמן אמת — הדירוג המוצג מסונכרן מדי כמה חודשים ואינו חי.
נקודות קצה ציבוריות
| מתודה | נתיב | מה מקבלים |
|---|---|---|
GET | /api/places | כל המקומות הפעילים כ-JSON — שם, קטגוריה, עיר, קואורדינטות, שעות פתיחה, כשרות וסינונים. |
GET | /api/health | בדיקת חיים של השירות והחיבור למסד הנתונים. |
GET | /api/suggestions | הצעות הפיצ׳רים של הקהילה ומספר ההצבעות לכל אחת. |
GET | /openapi.json | מפרט OpenAPI 3.1 של כל מה שברשימה הזו. |
GET | /llms.txt | מדריך לסוכני AI: מתי להשתמש בבדרך, איך לקרוא לנו, ומה נמצא איפה. |
GET | /sitemap.xml | כל הדפים הציבוריים, כולל דף לכל מקום במאגר. |
GET | /robots.txt | כללי סריקה. /admin ו-/api חסומים לאינדוקס, כל השאר פתוח. |
Markdown במקום HTML
כל דף ציבורי מחזיר גם גרסת Markdown לאותה כתובת, לפי המוסכמה של acceptmarkdown.com. שולחים כותרת Accept: text/markdown ומקבלים Content-Type: text/markdown יחד עם Vary: Accept, כדי ששרתי מטמון לא יגישו את הגרסה הלא נכונה.
curl -H "Accept: text/markdown" https://on-the-way-two.vercel.app/places/food curl -H "Accept: text/markdown" https://on-the-way-two.vercel.app/place/<slug>
גם תשובת 404 מגיעה כ-Markdown עם רשימת המקומות שאליהם כדאי להמשיך, כדי שסוכן שנתקל בקישור שבור יוכל להתאושש בלי בקשה נוספת.
שגיאות
כל שגיאה חוזרת כ-application/problem+json לפי RFC 9457 — לעולם לא כדף HTML. הגוף כולל code יציב לקריאת מכונה,detail בעברית לתצוגה, ו-hint עם מה שכדאי לעשות. תמיד להסתעף לפי code, אף פעם לא לפי הטקסט.
{
"type": "https://on-the-way-two.vercel.app/docs#error-not-found",
"title": "Not Found",
"status": 404,
"code": "not_found",
"detail": "אין נקודת קצה בכתובת /api/nope.",
"hint": "נקודות הקצה הציבוריות: /api/places, /api/health, /api/suggestions."
}| code | HTTP | מתי |
|---|---|---|
not_found | 404 | הכתובת או המשאב לא קיימים. הגוף כולל את רשימת נקודות הקצה הציבוריות. |
method_not_allowed | 405 | המתודה לא נתמכת בנקודת הקצה הזו. כותרת Allow מפרטת מה כן. |
rate_limited | 429 | חריגה מהמכסה. Retry-After אומר כמה שניות להמתין. |
invalid_request | 400 | שדה חסר או ערך לא תקין. |
unauthorized | 401 | נדרשת התחברות. רלוונטי רק לנקודות הקצה לכתיבה. |
forbidden | 403 | מחובר, אבל ללא הרשאה לפעולה הזו. |
server_error | 500 | תקלה אצלנו. בדרך כלל זמנית. |
גרסאות, מכסות ושינויים
גרסה
הגרסה הנוכחית היא 1, וכל תשובה מ-/api/* נושאת X-API-Version: 1. אפשר לנעול גרסה בשליחת אותה כותרת בבקשה. ערך לא נתמך מתעלמים ממנו ולא דוחים אותו, כדי שנעילת גרסה לא תוכל לשבור לקוח.
הוצאה משימוש
שינוי שובר בצורת תשובה מתועדת יוצא כגרסה חדשה, לא במקום הקיימת. לפני הסרה של נקודת קצה או של גרסה, התשובות שלה יישאו Deprecation: true וכותרת Sunset (RFC 8594) עם תאריך ההסרה, לפחות 90 יום מראש.
מכסות
GET /api/health ו-GET /api/suggestions מוגבלים ל-60 בקשות בדקה לכל כתובת IP, ומחזירים RateLimit-Limit, RateLimit-Remaining ו-RateLimit-Reset (בשניות), ובחריגה גם Retry-After. נקודות הקצה לכתיבה מחזירות את אותן כותרות.
GET /api/places אינו מוגבל — הוא מוגש מה-CDN ולא רץ בו קוד שיכול לספור בקשות. מאותה סיבה מתודה שגויה שם מקבלת 405 ריק ולא גוף JSON.
מה יש במאגר
- 🍽️ מקומות לאכול — מסעדות, בתי קפה, פוד טראקים, מאפיות ובָּרים — עם סינון כשרות, טבעוני, ללא גלוטן ופתוח עכשיו.
- 🌳 מקומות לטייל — מעיינות, נחלים, פארקים, תצפיות וחופים — כולל נגישות, צל, ומתאים לילדים.
- 🏨 מקומות לינה — צימרים, מלונות, גלמפינג, קמפינג ולינת לילה ברכב.
- 🎡 אטרקציות — פארקי שעשועים, אטרקציות טבע, מוזיאונים ואתרי תרבות.
- 🎨 סדנאות — סדנאות יצירה, בישול, קרמיקה ותכשיטים — לקבוצות ולמשפחות.
קבצים לקריאת מכונה
- llms.txt — מפת האתר לסוכני AI, כולל מתי כדאי להשתמש בבדרך ואיך לקרוא לו.
- OpenAPI 3.1 — תיאור ה-API הציבורי לקריאה — רשימת המקומות, בדיקת בריאות והצעות פיצ׳רים.
- תיעוד למפתחים ולסוכני AI — עמוד התיעוד: נקודות הקצה, משא ומתן על Markdown, מגבלות שימוש וייחוס.
- Sitemap — כל הדפים הציבוריים, כולל דף לכל מקום במאגר.
- robots.txt — כללי סריקה. /admin ו-/api חסומים, כל השאר פתוח.
- Web App Manifest — מטא-דאטה של ה-PWA (שם, אייקונים, צבעי מותג).
מגבלות שימוש וייחוס
- ללא מפתח API וללא הרשמה. אנא הגבילו את עצמכם לכ-60 בקשות בדקה.
- בשימוש בנתונים — ציינו את המקור: בדרך (On The Way), https://on-the-way-two.vercel.app.
- הנתונים נאספים ממקורות ציבוריים ומהצעות משתמשים ועוברים אישור אנושי. שעות פתיחה, כשרות ומחירים עשויים להשתנות ואינם התחייבות — לפני נסיעה כדאי לאמת מול העסק.
- הדירוגים מסונכרנים מ-Google מדי כמה חודשים ואינם בזמן אמת.
- נקודות הקצה לכתיבה (תגובות, הצעות מקום, תמונות, התראות) דורשות חשבון ואינן חלק מה-API הציבורי.
יצירת קשר
מצאתם טעות בנתונים, רוצים גישה רחבה יותר או שיתוף פעולה? כתבו לנו: outravel456@gmail.com או דרך טופס יצירת הקשר.