תיעוד API

אתה עוזר לי לעבוד עם Waze API (https://waze.botomat.co.il) — REST API שמחזיר זמני ומרחקי נסיעה בישראל מבוסס Waze בזמן אמת.

== אימות ==
כל קריאה ל-/api/* (פרט ל-/api/ping ו-/api/auth/*) דורשת API key בכותרת X-API-Key:
  curl -H "X-API-Key: wzk_live_..." https://waze.botomat.co.il/api/route?...

== פורמט קלט (from/to) ==
שני פורמטים נתמכים:
  1. שם בעברית: from=תל אביב | to=ירושלים | from=איתמר | to=אש קודש
  2. קואורדינטות: from=32.0853,34.7818 | to=31.7683,35.2137
תמיד URL-encode עברית עם encodeURIComponent.

== Endpoints ==

GET /api/ping
  בריאות + מטא, לא דורש מפתח. החזרה: {ok, service, placesCount, timestamp}

GET /api/places?limit=N&offset=N
  רשימת 1272 יישובים. החזרה: {total, count, places: [{name, lat, lon}, ...]}

GET /api/places/find?q=
  חיפוש מדויק במאגר מקומי (מהיר). 404 אם לא נמצא.

GET /api/places/search?q=&limit=10
  חיפוש חלקי (substring) במאגר מקומי.

GET /api/autocomplete?q=&limit=8
  השלמה אוטומטית כמו השדה באתר Waze. משלב DB מקומי + Waze.
  החזרה: {results: [{label, name, lat, lon, source: 'local'|'waze'}, ...]}

GET /api/geocode?q=
  המרת שם לקואורדינטות. החזרה: {name, lat, lon, city, type, provider}

GET /api/route?from=&to=[&alternatives=N&departAt=ISO&avoidTolls=1&includeInstructions=1&includeGeometry=1]
  מסלול מלא עם רמת עומס. החזרה:
  {
    from: {name, lat, lon}, to: {name, lat, lon}, region: 'IL',
    durationMinutes, durationSeconds,
    distanceKm, distanceMeters,
    freeFlowMinutes, trafficDelayMinutes,
    trafficLevel: 'free'|'light'|'moderate'|'heavy'|'standstill',
    trafficLevelHe: 'חופשי'|'קל'|'בינוני'|'כבד'|'עצירה',
    congestionRatio: 1.05,         // actual / freeFlow
    averageSpeedKmh: 72.3,
    routeName: '1 מזרח; 443 מזרח',
    departAt: ISO,                 // אם נשלח
    arrivalAt: ISO,                // אם נשלח departAt
    alternatives: [{routeName, durationMinutes, distanceKm, trafficLevel, congestionRatio, ...}],
    requestedAt: ISO
  }

GET /api/distance?from=&to=      → {distanceKm}
GET /api/duration?from=&to=      → {durationMinutes}

GET /api/eta?from=&to=[&departAt=ISO]
  כמו /route + departAt + arrivalAt מחושב.

GET /api/depart-by-arrival?from=&to=&arriveAt=ISO
  "אני רוצה להגיע ב-X, מתי לצאת?" — חישוב הפוך עם חיזוי תנועה.
  החזרה: {arriveAt, recommendedDepartAt, durationMinutes, distanceKm, expectedArrivalAt, overshootMinutes, scenarios: [...]}

GET /api/best-time?from=&to=&start=ISO&end=ISO&stepMinutes=30
  השוואת זמני נסיעה בחלון. מוצא את שעת היציאה הכי טובה.
  סוגרים: start..end ≤ 24 שעות, stepMinutes ≥ 15.
  החזרה: {fastest, slowest, averageMinutes, spreadMinutes, samples: [{departAt, durationMinutes, trafficLevel, arrivalAt}, ...]}

GET /api/matrix?origins=A|B|C&destinations=X|Y[&alternatives=1]
  מטריצת N×M זמני נסיעה (מקסימום 25 תאים). השמות מופרדים ב-|.
  החזרה: {rows: [{from, cells: [{to, durationMinutes, distanceKm, routeName}, ...]}, ...]}

== רמות עומס (trafficLevel) ==
ratio = durationActual / durationFreeFlow
  ratio < 1.10  → 'free'       חופשי
  ratio < 1.25  → 'light'      קל
  ratio < 1.50  → 'moderate'   בינוני
  ratio < 2.00  → 'heavy'      כבד
  ratio ≥ 2.00  → 'standstill' עצירה

== מגבלות ==
- Plan free: 1,000 קריאות/חודש, 60 קריאות/דקה
- Plan pro/enterprise: לפי חוזה
- Header X-RateLimit-Remaining מציג את הנותר בדקה
- Header X-Monthly-Remaining מציג את הנותר החודשי

== קודי שגיאה ==
400 invalid_input          חסר/לא תקין פרמטר
401 missing_api_key        אין X-API-Key
401 invalid_api_key        מפתח לא קיים/בוטל
403 email_not_verified     צריך לאמת מייל לפני שימוש
403 account_blocked        החשבון נחסם
404 not_found              המקום לא נמצא
429 monthly_limit_reached  עברת מכסה חודשית
429 rate_limit_reached     יותר מדי קריאות בדקה
500 internal_error         שגיאה בשרת/Waze upstream

== דוגמאות מהירות ==

# חישוב פשוט (שם)
GET /api/route?from=%D7%AA%D7%9C%20%D7%90%D7%91%D7%99%D7%91&to=%D7%99%D7%A8%D7%95%D7%A9%D7%9C%D7%99%D7%9D
# חישוב פשוט (קואורדינטות)
GET /api/route?from=32.0853,34.7818&to=31.7683,35.2137&alternatives=5
# "מתי לצאת בשביל להגיע ב-9 בבוקר?"
GET /api/depart-by-arrival?from=%D7%97%D7%99%D7%A4%D7%94&to=%D7%AA%D7%9C%20%D7%90%D7%91%D7%99%D7%91&arriveAt=2026-06-08T07:00:00Z
# "השווה זמני נסיעה בין 7:00 ל-11:00"
GET /api/best-time?from=%D7%9E%D7%95%D7%93%D7%99%D7%A2%D7%99%D7%9F&to=%D7%AA%D7%9C%20%D7%90%D7%91%D7%99%D7%91&start=2026-06-08T07:00:00Z&end=2026-06-08T11:00:00Z&stepMinutes=30
# מטריצה: 3 מקורות × 2 יעדים
GET /api/matrix?origins=%D7%97%D7%99%D7%A4%D7%94|%D7%AA%D7%9C%20%D7%90%D7%91%D7%99%D7%91|%D7%99%D7%A8%D7%95%D7%A9%D7%9C%D7%99%D7%9D&destinations=%D7%90%D7%99%D7%9C%D7%AA|%D7%91%D7%90%D7%A8%20%D7%A9%D7%91%D7%A2

== קוד JS לדוגמה ==
const API_KEY = 'wzk_live_...';
const BASE = 'https://waze.botomat.co.il';

async function route(from, to, opts = {}) {
  const p = new URLSearchParams({ from, to, ...opts });
  const r = await fetch(`${BASE}/api/route?${p}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  if (!r.ok) throw new Error((await r.json()).error);
  return r.json();
}

const trip = await route('תל אביב', 'ירושלים', { alternatives: 3 });
console.log(`${trip.durationMinutes} דק (${trip.trafficLevelHe}), ${trip.distanceKm} ק"מ`);

== המשימה שלי ==
[כאן כתוב את הבקשה — לדוגמה: "בנה לי React hook useRoute(from, to) שמחזיר זמן ומרחק", או "כתוב לי Node script שמחשב את שעת היציאה הטובה ביותר לפגישה ב-תל אביב ב-09:00 מירושלים".]