Delivery via the KAD: calculation by kilometers

What this solution does

Ring Road Delivery: Kilometer-based Calculation

A delivery service module for the "Online Store" where the cost depends on the road distance from the city's ring road to the buyer's address. Addresses located inside the ring road contour are calculated as 0 km. For addresses outside the contour, the distance is calculated along the actual route rather than as a straight line.

The contour of the KAD (Ring Road) in Saint Petersburg is built into the module by default. The contour of any other ring road (such as MKAD, TsKAD, or ring roads in Kazan, Yekaterinburg, etc.) is loaded from an external file.

This module is suitable for stores with courier delivery beyond ring roads where the price increases with each kilometer. It is ideal for selling building materials, furniture, appliances, water, and pet food. The solution is also effective for food and flower delivery, allowing the configuration of a separate "center" zone with its own pricing, free delivery conditions based on order total, and delivery timeframes. For stores operating in multiple cities, the module supports different contours and tariffs for each delivery service.

The cost calculation process works as follows: the address from the order and the city from the buyer's location are converted into geographic coordinates using the Yandex Geocoder. If the system finds only a street or a settlement rather than a specific building, the buyer is asked to clarify the address. If the address point falls within the contour of the ring road, the distance is set to 0 km.

The module calculates delivery costs beyond the MKAD by querying the OSRM routing server using OpenStreetMap data. The system identifies several nearest points on the ring road, constructs routes to them, and selects the shortest path.

Cost calculation is based on the delivery service tariff and a set of conditions: base price, price per kilometer, weight surcharge, free delivery threshold, minimum order value, and rounding rules.

The tariff supports three calculation modes: price per kilometer, fixed price for distance ranges (e.g., up to 10 km — 500 rubles, up to 30 km — 900 rubles), or a unique price per kilometer for each range, ensuring that longer deliveries never cost less than shorter ones.

Tariff settings include the base price, number of free kilometers, maximum delivery distance, and rounding of distance to whole kilometers or tenths.

Additional conditions allow setting a minimum order value, rounding the price up to 10 or 50 rubles, free delivery upon reaching a specific order sum (only within the specified radius), and a surcharge for each kilogram of weight exceeding the limit included in the base price.

Delivery time can be uniform for all orders or specific to each distance range, displayed to the buyer alongside delivery information.

The module supports zoning: a unique base price can be set for different city districts, for example, making delivery to the city center more expensive or cheaper than to other areas.

The Xlogic module 'Ring Road Delivery: Kilometer Calculation' extends standard delivery service restrictions by adding control over location, order total, weight, and payment system.

Multiple Cities Support

All geographic contours are stored in a single table on the 'Contours' tab within the module settings. This supports ring roads of any city or zones within a city. A contour can be created manually, imported from a GeoJSON or KML file (drawn in Yandex Map Constructor or on geojson.io), or added using the built-in button for the Saint Petersburg Ring Road (KAD) contour.

Each delivery service calculates distance from its own contour. For operation in two cities, two separate services are created, each with its own contour and location restrictions.

Order Checkout

The buyer sees the distance, total price, and delivery time. If the order total does not reach the free delivery threshold, the system displays the remaining amount needed.

The address can be entered as text or selected via a marker on the Yandex Map during checkout (sale.order.ajax). Upon selection, the address is automatically inserted into the order, and the cost is recalculated.

If the address is not found, is inaccurate, or lies beyond the maximum distance, the buyer is shown the reason, and the order cannot be placed.

In case of external service failure, the order is accepted with a 'Problematic' status to prevent sales interruption. This behavior is configurable.

Control

Verify delivery calculations for any address within module settings: displays the found location, geolocation accuracy, distance, cost, and estimated time for each delivery service, along with any tariff configuration errors.

The calculation log records the buyer's address, the mapped coordinates, the distance, and the specific error reason if one occurs. This functionality allows support staff to explain exactly why a delivery cost is set at a particular level. The retention period for log entries is configurable.

The system notifies administrators if the geocoder or routing server stops responding or is misconfigured. This notification is automatically cleared once the services resume normal operation.

Address-based calculation caching and a limit on the number of new addresses per visitor are implemented. This prevents the geocoder quota from being consumed by duplicate requests or address variations.

All module settings, delivery zones, and the calculation log are accessible on a single page. Tariffs are configured directly within the delivery service card.

Required components:

The "Online Store" (sale) module and the standard order checkout component sale.order.ajax.

A Yandex API key with access to the HTTP geocoder. Terms of use for the free key, including for online stores, must be verified with Yandex.

An OSRM routing server. The public server router.project-osrm.org is suitable for low traffic. For high traffic, a dedicated server is recommended; a Docker deployment guide is available in the module settings.

Routes are generated using OpenStreetMap data and may differ from Yandex Maps, especially in rural areas.

Delivery cost calculation occurs during order checkout. If external services respond slowly, the checkout process may be delayed.

For each delivery route contour, a new customer address requires a separate request to the geocoder.

The calculation log stores customer addresses, which are personal data. The retention period for this data is configurable in system settings, and the log can be disabled entirely.

General iT can take care of implementing “Delivery via the KAD: calculation by kilometers”, including installation, configuration and result verification.