Statistics integration guideline

2GIS is not able to obtain data about the user who uses a partner service to search in 2GIS data, as a search query (or, for example, a query to display a list from a category) is sent from a partner server.

So the partner should pass the user data to all the requests. 2GIS is interested in the following information:

  • user ID;
  • user session ID.

User IDs

The partner, on their side, should generate two cookies for their domain (the name may be different):

Name*ValidityFormat
_2gis_userUnlimitedRandom UUID
_2gis_sessionsession (until the browser is closed)Random UUID

* the partner is free to choose any name for cookie

** a library to generate UUID into PHP or a short snippet, as well as RFC by UUID

Cookies must have no http-only attribute so that there was an access from 2GIS apitracker.js JS library

Example of PHP code:

function randomUUID() {
    $data = mt_rand();
    return \Ramsey\Uuid\Uuid::uuid5(Uuid::NIL, $data)->toString();
}

function initCookie($name, $expire) {
    if (!isset($_COOKIE[$name])) {
        $value = randomUUID();
        setcookie($name, $value, $expire);
    } else {
        $value = $_COOKIE[$name];
    }
    return $value;
}

$dgisUserCookieName = '_2gis_user';
$dgisSessionCookieName = '_2gis_session';

$dgisUserCookieValue = initCookie($dgisUserCookieName, strtotime('+20 years'));
$dgisSessionCookieValue = initCookie($dgisSessionCookieName, 0);

Passing parameters

The partner should pass cookie values as GET parameters to API request on catalog.api.2gis.com from the server:

Cookie nameParameter
_2gis_userstat[user]
_2gis_sessionstat[sid]

Example in PHP using the API client, that does not support identifiers in the default implementation:

$apiClient = new \DGApiClient\ApiConnection('partner KEY');
$catalogClient = new \DGApiClient\Catalog($apiClient);
$results = $catalogClient->branchSearch('cafe', [
    'region_id' => 1,
    'stat[user]' => $dgisUserCookieValue,
    'stat[sid]' => $dgisSessionCookieValue
]);