Integration of 1C-Bitrix with 2GIS

Integrating 1C-Bitrix with 2GIS

Yandex.Maps and Google Maps are more familiar, but 2GIS has clear advantages in several niches: detailed shopping mall maps, pedestrian routes through retail galleries, offline maps in mobile applications. For retail chains, car dealerships, and clinics with multiple branches — 2GIS is often the preferred choice in CIS countries due to data accuracy.

Integrating 1C-Bitrix with 2GIS

2GIS API: what is available

2GIS provides several API products:

• Maps API (MapGL) — JavaScript library for displaying maps, markers, and routes
• Places API — searching for organizations and retrieving information about them
• Geocoder API — address geocoding (address → coordinates and back)
• Routing API — route planning
• Tiles API — tile maps for custom rendering

For 1C-Bitrix integration, Maps API is most commonly used to display a map on a page, and Geocoder API is used to automatically determine coordinates when adding addresses in the administrative panel.

Connecting MapGL to 1C-Bitrix pages

Adding a map to a component template:

// result_modifier.php or template.php
\Bitrix\Main\Page\Asset::getInstance()->addJs(
    'https://mapgl.2gis.com/api/js/v1'
);

// Pass coordinates from iblock properties
$arResult['MAP_LAT'] = (float)$arResult['PROPERTIES']['LAT']['VALUE'];
$arResult['MAP_LNG'] = (float)$arResult['PROPERTIES']['LNG']['VALUE'];

// template.js
const map = new mapgl.Map('map-container', {
    center:  [<?= $arResult['MAP_LNG'] ?>, <?= $arResult['MAP_LAT'] ?>],
    zoom:    15,
    key:     '<?= DGIS_API_KEY ?>',
});

new mapgl.Marker(map, {
    coordinates: [<?= $arResult['MAP_LNG'] ?>, <?= $arResult['MAP_LAT'] ?>],
});

The API key is stored in a constant defined in /local/php_interface/dbconn.php or via \Bitrix\Main\Config\Option.

Geocoding when saving addresses

A common task: a manager enters a branch address in the administrative panel, and coordinates should be set automatically. Implemented via the OnAfterIBlockElementAdd / OnAfterIBlockElementUpdate event handler:

// /local/php_interface/init.php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'iblock',
    'OnAfterIBlockElementUpdate',
    'geocodeAddressOn2GIS'
);

function geocodeAddressOn2GIS(array &$arFields): void
{
    if ($arFields['IBLOCK_ID'] != BRANCHES_IBLOCK_ID) return;

    $address = $arFields['PROPERTY_VALUES'][BRANCH_ADDRESS_PROP_ID][0]['VALUE'] ?? '';
    if (!$address) return;

    $coords = Dgis\GeocoderClient::geocode($address);
    if (!$coords) return;

    \CIBlockElement::SetPropertyValuesEx($arFields['ID'], BRANCHES_IBLOCK_ID, [
        'LAT' => $coords['lat'],
        'LNG' => $coords['lng'],
    ]);
}

The Dgis\GeocoderClient class:

namespace Dgis;

class GeocoderClient
{
    private const API_URL = 'https://catalog.api.2gis.com/3.0/items/geocode';

    public static function geocode(string $address): ?array
    {
        $response = \Bitrix\Main\Web\HttpClient::query(
            'GET',
            self::API_URL . '?' . http_build_query([
                'q'      => $address,
                'fields' => 'items.point',
                'key'    => \Bitrix\Main\Config\Option::get('mymodule', 'dgis_api_key'),
            ])
        );

        $data = json_decode($response->getContent(), true);
        $point = $data['result']['items'][0]['point'] ?? null;

        if (!$point) return null;

        return ['lat' => $point['lat'], 'lng' => $point['lon']];
    }
}

Branch network map: marker clustering

For networks with a large number of locations (50+), individual markers on the map become an unreadable cluster. MapGL supports clustering via mapgl.ClusterLayer:

// Load all points via AJAX from the 1C-Bitrix REST endpoint
const response = await fetch('/local/ajax/branches.php');
const branches = await response.json();

const source = new mapgl.GeoJsonSource(map, {
    data: {
        type: 'FeatureCollection',
        features: branches.map(b => ({
            type: 'Feature',
            geometry: { type: 'Point', coordinates: [b.lng, b.lat] },
            properties: { name: b.name, address: b.address, id: b.id },
        })),
    },
    attributes: { cluster: true },
});

/local/ajax/branches.php returns JSON from a cached iblock query. The cache is invalidated by the iblock_id_N tag when iblock elements are updated.

Data synchronization: 1C-Bitrix ↔ 2GIS Business API

2GIS provides a Business API for managing your organization listings — updating contacts, photos, and opening hours directly via API without manually logging into the dashboard.

Synchronization scheme:

1C-Bitrix (Branches iblock) → Agent → 2GIS Business API → organization listings

A 1C-Bitrix agent checks the iblock for changes once a day (via the DATE_MODIFY field) and sends updates via the API. The main module is used; agents are stored in the b_agent table.

// Registering the agent
\CAgent::AddAgent(
    'DgisSyncAgent::run();',
    'mymodule',
    'N',  // non-one-time
    86400, // every 24 hours
);

Using Places API to search for organizations

If the site has a search by partners, dealers, or pickup points — Places API allows retrieving official 2GIS data about an organization by its 2GIS database ID:

$client = new \Bitrix\Main\Web\HttpClient();
$client->query('GET',
    'https://catalog.api.2gis.com/3.0/items?id=' . $dgisOrgId .
    '&fields=items.contact_groups,items.schedule,items.rubrics' .
    '&key=' . DGIS_API_KEY
);
$orgData = json_decode($client->getResult(), true);

The data is saved to iblock properties and displayed in the partner card.

Using 2GIS without a server key

In development mode or for non-commercial projects, MapGL can be used without a key with request count limitations. Commercial use requires a contract; pricing depends on the number of map loads per month.

Timelines