FIAS Address Autocomplete Integration for Websites

Every tenth order in an online store is lost due to an incorrectly entered address. According to DataInsight research, up to 15% of shipments fail to reach the recipient on the first attempt — most often due to address errors. The user doesn't know the exact street, confuses the district, or omits the building number. We solve this with address autocomplete based on FIAS. Our experience includes 5+ years and 20+ successful projects, with an average 50% reduction in address errors. We offer two approaches: the cloud service DaData or your own infrastructure on PostgreSQL. A custom server pays off at a load of 5,000 requests per day and can be 3x cheaper than DaData at high volumes. Let's dive into the technical details: from loading dumps to frontend. We use delta updates, GIN indexes, and caching.

How to Integrate FIAS Without Intermediaries?

Direct integration is justified in three cases: security requirements prevent sending addresses to external APIs, high load is expected (tens of thousands of requests per day), or custom search logic is needed. Otherwise, it's simpler and cheaper to use DaData.

Obtaining and Loading Dumps

Current dumps are published on the official FIAS website. The full database (XML, several dozen archives, total compressed size about 2 GB) and delta updates (weekly) are available. The GAR format differs slightly, but the principles are the same.

Minimum set of tables for address autocomplete:

• AS_ADDR_OBJ — regions, districts, cities, streets
• AS_HOUSES — buildings, structures, blocks
• AS_HIERARCHY — hierarchical relationships of objects
• AS_ADDR_OBJ_PARAMS — additional parameters (postal index)

The first load of the full dump into PostgreSQL via a PHP script or Python parser takes 3–6 hours. Delta updates take 10–30 minutes.

Table Structure and Indexes

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

Without a GIN index, searching through 30+ million records would be unbearably slow. The PostgreSQL documentation on GIN indexes recommends this approach for full-text search in Russian.

FIAS API for Suggestions

A simple endpoint in PHP/Laravel that accepts a string and returns a list of options — our FIAS API implementation:

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

For house input, the query is more complex — you first need to find the street by its object_id, then search for houses by addr_obj_id. In our practice, the average execution time for such a compound query does not exceed 80 ms after cache warm-up.

Frontend: Connecting Autocomplete for Address Form Autofill

On the browser side, standard debounce + fetch logic:

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

The 250 ms delay prevents a request on every keystroke. To improve UX, we add a loading indicator and handle errors — the user should never see an empty dropdown on network failure.

When Is Your Own Infrastructure Justified?

Let's compare the approaches:

If the request volume is high, your own server is cheaper in the long run — a custom FIAS server is up to 3x cheaper than DaData at 10,000 requests/day.

API Performance

Process

1. Requirements analysis — determine load, need for closed network, choose approach.
2. Infrastructure preparation — set up server (Linux, PostgreSQL, Docker) or connect to DaData.
3. Dump loading and indexing — load full FIAS/GAR dump, create GIN indexes.
4. REST API development — implement endpoint for suggestions with hierarchy.
5. Frontend integration — connect AJAX requests to FIAS API, set up debounce and rendering.
6. Auto-update — configure cron for daily download and application of deltas.
7. Testing and documentation — verify correctness of suggestions, write API documentation.

What's Included in the Work

• Integration documentation (API spec, table descriptions)
• API access (if deployed on your server) or instructions for connecting to DaData
• Auto-update scripts
• Technical support for 2 weeks after launch
• Developer training on working with the solution

Typical Mistakes in Self-Integration