Custom 1C-Bitrix Geolocation Module Development

Geolocation Module for 1C-Bitrix: Where the Logic Breaks

Region detection breaks not at the "get coordinates" stage, but at the junction of three layers: the geodata source, the cache, and the business rules that use the region to select a warehouse, a delivery zone, and available payment methods.

While the site is small, the desync goes unnoticed — a visitor from Minsk sees the Minsk warehouse, and everything adds up.

As soon as the number of points of sale and warehouses grows, and traffic comes from several countries, failures surface that cannot be reproduced on a test environment.

The first typical failure is that the geodata cache lives longer than the rules change.

The visitor's region is determined correctly, but the cached warehouse binding is left over from an old delivery zone configuration: the customer places an order for a pickup point that no longer serves their address.

The second is region detection by IP at zone boundaries: an address falls into a border range, the module picks the neighboring region, and the person sees someone else's assortment and lead times.

The third is mobile drop-offs: the request to the external region detection service is sent synchronously during page rendering, on a weak connection it fails to return in time, and the visitor gets a form without a city selection.

A separate category is the conflict between manual and automatic selection. The visitor selected a city manually once, but on the next visit the module overwrites the choice by IP, because the priority of sources is not set explicitly. The user sees a "jumping" region and leaves before reaching the cart.

What matters here is not the development of the geolocation module itself, but the order in which sources are resolved: manual selection, saved profile, cookie, then IP — and an explicit rule for when each subsequent source has the right to override the previous one.

Let's break down how this is closed: we separate region detection from point selection, set the geodata cache lifetime separately from the delivery zone cache, and move the request to the external service into a background call with a fallback default scenario. Next — how to build this logic so that it doesn't fall apart when a new warehouse is added.

What correct geolocation gives a business

Correct geolocation is not "determine the city by IP and substitute it into the header." It is a combination of several layers: determining the region by IP taking into account mobile carriers and corporate networks, the priority of the user's explicit choice, tying warehouses, prices, and delivery times to the region, and caching results so that selection does not slow down.

Each layer affects its own metric: region accuracy affects the share of orders without recalculation, selection speed affects the depth of catalog browsing, and the currency of the mappings affects the volume of manual edits in orders.

Let's break down what exactly is measured after implementation. The share of correctly determined regions is calculated based on fact: how many sessions received a region matching the delivery address in the order, without manual intervention by a manager.

Selection speed is the time from entering a query or opening the catalog to the results being displayed, taking into account regional stock and prices; if selection pulls data from an external system synchronously, response time grows by a multiple, and some users leave before waiting.

Selection conversion is the share of sessions where the user reached adding an item to the cart after seeing the correct conditions for their region.

The reduction in manual edits is the most underrated metric. When the region in an order is set automatically and matches the address, the manager does not need to recalculate delivery, change the warehouse, and reissue the invoice.

At a volume of several hundred orders per month, this frees up hours of work and eliminates a class of errors that cause the client to see one price but pay another.

There is also a downside: aggressive geolocation is annoying. If the region is substituted on every visit, while the user has already chosen their own manually, trust drops.

Therefore, in a correct implementation, the explicit choice always takes priority over the automatic one, is stored in the session and profile, and auto-detection works only as a suggestion with the ability to switch quickly.

This balance delivers growth in selection conversion without an increase in bounces on the first screen.

The effect can be checked before implementation using current analytics: the share of orders with a region different from the delivery address, catalog response time by region, and the number of edits in orders on the manager's side.

These three slices provide a baseline against which the result after launching the module is compared.

Methods of determining location and their limitations

Location accuracy is a trade-off between speed, precision, and privacy, and each method covers its own part of the task.

In practice, no single method delivers an acceptable result on its own: IP-based detection works instantly, but on mobile carriers it can miss by tens of kilometers, while device geocoordinates are accurate but require explicit user consent and browser permission.

Manual city selection and the hybrid method address different scenarios: the first — when predictability matters and the user fixes the region themselves, the second — when the automation needs a fallback.

Below is a comparison of the approaches by accuracy, speed, and limitations, to help choose a scheme for a specific module task.

The hybrid scheme is usually built like this: on the first visit, the city is determined by IP and substituted immediately, coordinates are requested only upon user action, and manual selection overrides the automation and is remembered in the session.

This order provides accuracy where it is needed and does not block the interface with a permission request at startup.

Caching deserves separate consideration: the IP-based detection result is reasonable to keep in the session so as not to hit the external service on every request, while manual selection should be stored longer — it reflects the user's intent rather than a technical guess.

How we develop a geolocation module

Development of a geolocation module begins not with code, but with an analysis of how the site determines the region today.

We look at where the user's binding is stored, how it survives cookie clearing, what happens when a user arrives via search and via a direct link, and how the cart behaves when the city changes.

An audit of the logic uncovers conflicts between subdomains, the session, and the cache — these are exactly what produce a "jumping" region, causing the client to see someone else's prices and delivery times.

Next, we design the region scheme: the hierarchy "country — region — city — delivery zone," inheritance rules, and source priorities.

We determine what takes precedence — the user's explicit choice, network geodata, or profile data — and how to resolve discrepancies between them.

1. Audit of the current logic: we analyze region determination, storage of the binding, behavior when the city changes and the session is cleared.
2. Design of the region scheme: hierarchy, source priorities, inheritance rules, and delivery zones.
3. Configuration of data sources: connecting reference directories, geoservices, and rules for matching addresses to regions.
4. Implementation of the module: region determination, switching, remembering the choice, and synchronization with the cart, prices, and inventory.
5. Testing of scenarios: arrival from search, direct navigation, changing the city in the cart, a returning user, and operation under load.
6. Handover: documentation on the scheme, instructions for adding regions and editing rules.

Scenario testing follows real user paths, not test stubs: we substitute geodata, emulate transitions between cities, and verify that prices, availability, and delivery terms are recalculated consistently.

As a result, the client receives a module that does not conflict with the cache and subdomains, and a clear scheme by which regions can be added without modifying the core.

Delivery package: configurations, schemas, regulations

Based on the results of the implementation, you receive not a "working module on a server," but a package that your team can use to develop geolocation without us: configurations, zone maps, priority rules, and documentation. Below is exactly what is included in the delivery and why each element is needed.

• Region configuration — a file with a list of regions, mapping to domains and subdomains, language versions, and time zones. Edits are made without a release: adding a city or switching a region to another domain can be done in minutes.
• Coverage zone map — a schema showing which region is represented by which addresses and service points, where the boundaries of neighboring zones are, and how disputed addresses at the junction are handled. It shows where to add new points without breaking neighboring ones.
• Priority rules — a matrix by which the module selects a region when signals conflict: delivery address versus time zone, manual selection versus auto-detection, city from the profile versus the current session. Each rule is described with an example of when it triggers.
• Data update regulation — how and how often address directories and zone boundaries are updated, who is responsible for the export, and what happens if the source is unavailable.
• Module documentation — a description of extension points, input data formats, and behavior when there is no match: which region is served by default and how this can be changed.
• Instructions for content managers — how to add a region, change a coverage zone or priority through the admin panel, without contacting a developer.
• Rollback scheme — which settings are saved before a change and how to return the previous region configuration if the new zone map produced an incorrect result.

We hand over the package in your repository along with the change history — you can see what changed and when in the priority rules. Describe the task: we will come back with an estimate and a delivery plan for your environment.

Case study: selecting locations by region without manual edits

The task was typical for retail with several hundred locations: a nearest-store selector was running on a 1C-Bitrix site, but the region was determined crudely by IP — using the provider's federal range.

As a result, a resident of a border district was shown a store from a neighboring region, and the courier zone was calculated incorrectly. Managers fixed the bindings by hand: 40-60 requests per week, each one an edit in the information block and a re-publication.

What was changed

We traced the chain all the way through. Instead of a single IP request, we assembled a cascade: precise coordinates from the browser, and if those are unavailable — IP with city-level refinement, and in ambiguous cases — the user's choice with memorization in a cookie.

The location binding logic was moved into a separate module with configurable rules: radius, region priority, and an exception list for border addresses. The geoservice response cache is kept server-side — repeated requests from the same city don't hit the external API.

Metrics before and after

Manual edits didn't disappear entirely — real relocations and new locations remained, but these are now planned changes rather than firefighting errors.

Region accuracy grew thanks to the cascade: even when the browser doesn't provide coordinates, the city by IP is refined down to the settlement rather than the region.

We also separately handled rollback: binding rules are stored in versions, and reverting to a previous configuration takes minutes without deploying code. This is the same geolocation case that scales to any network — from a dozen locations to thousands.

How is IP geolocation different from device coordinates?

IP geolocation works on the server side: the visitor's address is matched against a database of provider ranges, and the module immediately receives the region, city, and time zone.

No permissions need to be requested, and the scenario runs on the very first request — this is a key advantage for selecting the delivery city, currency, interface language, and the nearest warehouse.

The accuracy of determination is limited, however: it holds up confidently at the city and district level, but within a large populated area the coordinates are blurred to the provider's aggregation center, and corporate networks and mobile operators often return the address of the head office or the region of internet access.

Device coordinates are requested through the browser and provide location accuracy down to the building if the visitor has confirmed access.

This is where the data privacy fork appears: the user sees a system prompt and decides for themselves whether to share their location, and a refusal is a normal scenario that the module must handle.

If access is not granted or the request is declined, we substitute IP geolocation as a fallback, and offer to select the point on the map manually.

The practical takeaway for scenarios is simple: where speed and invisibility matter — determining the city, time zone, regional conditions — we rely on IP.

Where precision is needed — route calculation, delivery zone, the nearest pickup point — we request device coordinates and always leave manual input as a third level.

The development of a geolocation module is structured so that both sources work in a single chain: first precise coordinates, on refusal — IP, on doubt — the user's choice.

We think through storage separately: we do not write device coordinates to the database without consent, we process IP within the stated purposes, and we cache the determination result for the session so as not to trigger requests repeatedly.

This way the scenario stays fast, and the handling of personal data stays predictable and verifiable.

Common technical concerns

Geolocation in Bitrix is not a single call, but a combination: determining the region, substituting data into the template, caching the result, and behavior when an external service fails. Below are the things most often checked before starting development of a geolocation module.

Will the module break existing solutions on the site?

Conflicts usually arise not with the core, but with other modules that also override the region or intercept the same handler.

Therefore, before starting work we map out the installed modules and their intervention points, and we hook in the logic through standard events without touching third-party code.

If an overlap is unavoidable, we separate handler priorities and document the order — updating third-party modules does not break geolocation.

What happens if the region detection service is unavailable?

An external source is not the only point of failure: a backup source and a local IP-region mapping database run alongside it.

If the primary service is unavailable, the request goes to the backup, and if that one is silent too — the visitor gets the default region specified in the settings, and the site keeps serving content.

Timeouts are short, errors are logged, and automatic failover to the backup happens without manual intervention.

Can the module be rolled back without site downtime?

Yes. The module is installed as a separate package, and changes to templates are made through standard mechanisms, so disabling it restores the previous behavior without modifying the core.

Before deployment we make a backup of the database and files, and the migration itself proceeds in stages with verification on a test environment.

Describe your task — we will get back to you with an estimate and a work plan.

Let's discuss your geolocation task

To come back with an estimate and an implementation plan, we need to understand your current logic: where the addresses of your facilities are stored, who enters them and how, whether you already have a reference list of regions, and how the nearest point is currently determined.

Describe the task in free form — that is enough for us to ask clarifying questions and propose a workable option.

From there, the work proceeds step by step:

• We analyze the current logic: address sources, reference lists, user scenarios, and bottlenecks.
• We agree on what we consider the result: matching accuracy, response speed, behavior with incomplete data.
• We prepare an estimate of the work and an implementation plan with stages and checkpoints.
• We build a prototype on real data — we check how the module behaves on your database.
• We move the logic into the production environment, set up caching and access control.
• We train your team and hand over documentation on the settings.
• We stay on module support: we monitor stability and refine it for new tasks.

To make the estimate accurate rather than "based on gut feeling," send us access to a test environment or an export of your reference lists and examples of the addresses the module will work with.

That way we will see the real data formats and take into account discrepancies in the spelling of streets and regions in advance — this is most often what determines how accurately geolocation works.

Describe the task — we will come back with an estimate, an implementation plan, and options for module support after launch.