שילוב השלמת כתובות FIAS לאתרי אינטרנט

כל הזמנה עשירית בחנות מקוונת אובדת עקב כתובת שהוזנה בצורה שגויה. לפי מחקר DataInsight, עד 15% מהמשלוחים לא מגיעים לנמען בניסיון הראשון — לרוב עקב שגיאות בכתובת. המשתמש לא יודע את הרחוב המדויק, מתבלבל בין אזורים, או משמיט את מספר הבניין. אנו פותרים זאת עם השלמה אוטומטית של כתובות המבוססת על FIAS. הניסיון שלנו כולל 5+ שנים ו-20+ פרויקטים מוצלחים, עם הפחתה ממוצעת של 50% בשגיאות כתובת. אנו מציעים שתי גישות: שירות הענן DaData או תשתית משלך על PostgreSQL. שרת מותאם אישית משתלם בעומס של 5,000 בקשות ביום ויכול להיות זול פי 3 מ-DaData בנפחים גבוהים. בואו נצלול לפרטים הטכניים: מטעינת קבצי dump ועד לפרונטאנד. אנו משתמשים בעדכוני דלתא, אינדקסי GIN וקאשינג.

איך לשלב FIAS ללא מתווכים?

אינטגרציה ישירה מוצדקת בשלושה מקרים: דרישות אבטחה מונעות שליחת כתובות ל-API חיצוניים, צפוי עומס גבוה (עשרות אלפי בקשות ביום), או שנדרשת לוגיקת חיפוש מותאמת אישית. אחרת, פשוט וזול יותר להשתמש ב-DaData.

קבלת וטעינת קבצי Dump

קבצי dump עדכניים מתפרסמים באתר הרשמי של FIAS. מסד הנתונים המלא (XML, כמה עשרות ארכיונים, גודל דחוס כולל של כ-2 GB) ועדכוני דלתא (שבועיים) זמינים. פורמט GAR שונה מעט, אך העקרונות זהים.

קבוצת טבלאות מינימלית להשלמה אוטומטית של כתובות:

• AS_ADDR_OBJ — אזורים, מחוזות, ערים, רחובות
• AS_HOUSES — מבנים, בניינים, בלוקים
• AS_HIERARCHY — יחסים היררכיים בין אובייקטים
• AS_ADDR_OBJ_PARAMS — פרמטרים נוספים (מיקוד)

הטעינה הראשונה של ה-dump המלא לתוך PostgreSQL דרך סקריפט PHP או מפענח Python אורכת 3–6 שעות. עדכוני דלתא אורכים 10–30 דקות.

מבנה הטבלאות ואינדקסים

CREATE TABLE addr_obj (
    id UUID PRIMARY KEY,
    object_id BIGINT,
    name TEXT NOT NULL,
    type_name TEXT,
    level SMALLINT,
    is_active BOOLEAN DEFAULT true
);

CREATE TABLE houses (
    id UUID PRIMARY KEY,
    object_id BIGINT,
    addr_obj_id BIGINT,
    house_num TEXT,
    build_num TEXT,
    struct_num TEXT,
    is_active BOOLEAN DEFAULT true
);

CREATE INDEX idx_addr_obj_name_fts ON addr_obj USING GIN (to_tsvector('russian', name));
CREATE INDEX idx_hierarchy_parent ON hierarchy(parent_obj_id);
CREATE INDEX idx_hierarchy_child ON hierarchy(object_id);

ללא אינדקס GIN, חיפוש בין 30+ מיליון רשומות יהיה איטי בצורה בלתי נסבלת. התיעוד של PostgreSQL על אינדקסי GIN ממליץ על גישה זו לחיפוש טקסט מלא ברוסית.

FIAS API להצעות

נקודת קצה פשוטה ב-PHP/Laravel שמקבלת מחרוזת ומחזירה רשימת אפשרויות — היישום שלנו ל-FIAS API:

public function suggest(Request $request): JsonResponse
{
    $query = trim($request->input('q', ''));
    if (mb_strlen($query) < 2) {
        return response()->json([]);
    }
    $results = DB::select("
        SELECT ao.name, ao.type_name, ao.level, h.path_name
        FROM addr_obj ao
        JOIN addr_hierarchy h ON h.object_id = ao.object_id
        WHERE to_tsvector('russian', ao.name) @@ plainto_tsquery('russian', ?)
        AND ao.is_active = true
        ORDER BY ao.level, ao.name
        LIMIT 10
    ", [$query]);
    return response()->json($results);
}

להזנת בית, השאילתה מורכבת יותר — קודם צריך למצוא את הרחוב לפי CREATE TABLE addr_obj ( id UUID PRIMARY KEY, object_id BIGINT, name TEXT NOT NULL, type_name TEXT, level SMALLINT, is_active BOOLEAN DEFAULT true ); CREATE TABLE houses ( id UUID PRIMARY KEY, object_id BIGINT, addr_obj_id BIGINT, house_num TEXT, build_num TEXT, struct_num TEXT, is_active BOOLEAN DEFAULT true ); CREATE INDEX idx_addr_obj_name_fts ON addr_obj USING GIN (to_tsvector('russian', name)); CREATE INDEX idx_hierarchy_parent ON hierarchy(parent_obj_id); CREATE INDEX idx_hierarchy_child ON hierarchy(object_id); , ואז לחפש בתים לפי public function suggest(Request $request): JsonResponse { $query = trim($request->input('q', '')); if (mb_strlen($query) < 2) { return response()->json([]); } $results = DB::select(" SELECT ao.name, ao.type_name, ao.level, h.path_name FROM addr_obj ao JOIN addr_hierarchy h ON h.object_id = ao.object_id WHERE to_tsvector('russian', ao.name) @@ plainto_tsquery('russian', ?) AND ao.is_active = true ORDER BY ao.level, ao.name LIMIT 10 ", [$query]); return response()->json($results); } . בניסיון שלנו, זמן הביצוע הממוצע לשאילתה מורכבת כזו אינו עולה על 80 אלפיות השנייה לאחר חימום הקאש.

פרונטאנד: חיבור השלמה אוטומטית למילוי אוטומטי של טופס כתובת

בצד הדפדפן, לוגיקת debounce + fetch סטנדרטית:

let timer;
input.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(async () => {
    const q = input.value.trim();
    if (q.length < 2) return;
    const res = await fetch(`/api/fias/suggest?q=${encodeURIComponent(q)}`);
    const data = await res.json();
    renderDropdown(data);
  }, 250);
});

השהיה של 250 אלפיות השנייה מונעת שליחת בקשה על כל הקלדה. כדי לשפר את חוויית המשתמש, אנו מוסיפים מחוון טעינה ומטפלים בשגיאות — המשתמש לעולם לא צריך לראות תפריט נפתח ריק במקרה של תקלת רשת.

מתי תשתית משלך מוצדקת?

בואו נשווה בין הגישות:

אם נפח הבקשות גבוה, שרת משלך זול יותר בטווח הארוך — שרת FIAS מותאם אישית זול עד פי 3 מ-DaData ב-10,000 בקשות/יום.

ביצועי API

תהליך העבודה

1. ניתוח דרישות — קביעת עומס, צורך ברשת סגורה, בחירת גישה.
2. הכנת תשתית — הגדרת שרת (Linux, PostgreSQL, Docker) או חיבור ל-DaData.
3. טעינת dump ויצירת אינדקסים — טעינת dump מלא של FIAS/GAR, יצירת אינדקסי GIN.
4. פיתוח REST API — יישום נקודת קצה להצעות עם היררכיה.
5. אינטגרציית פרונטאנד — חיבור בקשות AJAX ל-FIAS API, הגדרת debounce ורינדור.
6. עדכון אוטומטי — הגדרת cron להורדה והחלה יומית של דלתא.
7. בדיקות ותיעוד — אימות נכונות ההצעות, כתיבת תיעוד API.

מה כלול בעבודה

• תיעוד אינטגרציה (מפרט API, תיאורי טבלאות)
• גישה ל-API (אם נפרס על השרת שלך) או הוראות לחיבור ל-DaData
• סקריפטים לעדכון אוטומטי
• תמיכה טכנית למשך שבועיים לאחר ההשקה
• הדרכת מפתחים על עבודה עם הפתרון

טעויות נפוצות באינטגרציה עצמית