GdeBenz Client API Documentation

Reverse-engineered, client-side behavior specification of https://gdebenz.ru — a real-time fuel-station availability map.

Based on DevTools inspection, network tracing and frontend bundle analysis.

⚠️ Disclaimer

This project is not affiliated with GdeBenz. It documents observed frontend behavior, not the backend implementation. All endpoints were inferred from browser network traffic and may change without notice. Intended for educational, interoperability and reverse-engineering purposes only.

---

Table of Contents

• System Overview
• Architecture
• Authentication Model
• Core Endpoints
• Polling Behavior
• Failure Modes
• Rate Limiting
• Storage Model
• Technologies
• Documentation Index
• Repository Structure

---

System Overview

The application is a polling-based real-time map for fuel-station availability.

Key properties:

• No WebSockets
• No server push
• Heavy polling of /api/nearby
• Token-based, anonymous voting system
• Multiple unstable runtime token endpoints

---

Architecture

Frontend (SPA)
    │  polling loop
    ├─ /api/nearby    (high frequency)
    ├─ /api/stations  (viewport-based)
    ├─ /api/comments  (votes + reports)
    └─ /api/vt, /api/rt (runtime tokens)
    │
    ▼
Backend (stateless REST + cache layer + DDoS protection)

---

Authentication Model (Anonymous)

There is no user authentication. The system relies on the following:

1. Visitor Fingerprint

• Stored in localStorage.gas_cid
• Generated via getFingerprint()
• Sent on every mutation endpoint as fp: "<fingerprint>"

2. Runtime Token — VT

GET /api/vt

Property	Value
Response time	0.5s – 9s
Reliability	intermittent 504 Gateway Timeout
Frontend	retries implicitly
Required for	voting

Response:

{
  "vt": "string",
  "ttl": 1800
}

❌ Not reliable under load. ❌ Can block the voting flow if not cached. ✔ Must be reused, not re-fetched per request.

3. Runtime Token — RT

GET /api/rt

• Fast (<100ms typical), occasional slow spikes
• Used as a request header:

X-RT: <token>

4. Cloudflare Turnstile (optional)

Used only for selected mutation flows:

{ "cf": "<turnstile-token>" }

---

Core Endpoints

GET /api/nearby

Returns nearby gas stations.

Param	Description
lat	Latitude
lon	Longitude
radius_km	Search radius

Example:

GET /api/nearby?lat=55.75&lon=38.70&radius_km=20

Observed behavior:

• High-frequency polling (map drag / state updates)
• Duplicate requests are common
• No request deduplication
• _= cache-buster often appended

Characteristics: ✔ fast (10–200 ms) · ❌ heavily spammed · ❌ no debounce.

GET /api/stations

Viewport-based station loader.

Param	Description
lat1, lon1	Bounding box corner
lat2, lon2	Bounding box corner

Observed behavior: slow (1–4 s), occasional 504 under load, triggered on viewport changes.

GET /api/search

Search stations by query.

GET /api/search?q=lukoil

GET /api/views

Aggregated view counters for stations.

GET /api/comments/:osm_id

Returns station votes / comments.

POST /api/comments

Vote submission endpoint.

{
  "osm_id": "string",
  "name": "string",
  "lat": 0,
  "lon": 0,
  "status": "yes|no|queue|low",
  "text": "",
  "fp": "fingerprint",
  "vt": "vt-token",
  "cf": "turnstile-token"
}

Status meanings:

Value	Meaning
yes	Fuel available
no	No fuel
queue	Queue
low	Low fuel

Known issues: requires a valid VT token, may fail if VT expired, subject to a duplicate-vote cooldown (409).

POST /api/share-snapshot

Generates a station map snapshot image. Slow (2–5 s), used by the sharing UI.

GET /api/thanks

User engagement tracking endpoint.

A full endpoint reference is available in docs/endpoints.md.

---

Polling Behavior

The frontend aggressively re-fetches data.

Observed loop:

• /api/nearby → repeated calls on every UI update
• /api/stations → triggered on viewport change
• /api/comments → triggered on station focus
• /api/vt → retry-based token fetch

Issues observed:

• Duplicate identical requests
• Parallel overlapping requests
• No AbortController usage
• No request deduplication
• Cache-busting parameter _= frequently used

---

Failure Modes

/api/vt

Issue	Behavior
Timeout	504
Slow response	up to 9 s
Retry	implicit frontend retry

/api/stations

Issue	Behavior
Overload	504
Heavy query	1–4 s latency

---

Rate Limiting (Observed)

• No explicit client-side limit
• Backend likely protected by DDoS-Guard
• Bursts tolerated but throttled server-side

---

Storage Model

Key	Purpose
gas_cid	Fingerprint
gas_votes	Cached votes
gas_votes_t	Timestamps
gas_theme	UI theme
gas_impact	User score

---

Technologies (Observed)

• Vanilla JS SPA
• Leaflet map engine
• Marker clustering
• DDoS-Guard protection layer
• Yandex Metrica tracking
• Cloudflare Turnstile
• Service Worker caching
• Heavy polling architecture (no push channel)

Key Behavioral Summary

This system is best described as:

A polling-heavy real-time map frontend with an unstable, token-protected mutation layer.

Not:

• ❌ a pure REST API
• ❌ a stable backend contract
• ❌ an event-driven system

---

Documentation Index

Document	Description
api.md	API overview and endpoint reference
architecture.md	System and layer architecture
authentication.md	Anonymous auth and token flow
changelog.md	Version history
client-behavior.md	Observed client runtime behavior
constants.md	Frontend constants and enums
data-models.md	Payload and data model reference
endpoints.md	Full endpoint reference
endpoints-table.md	Endpoint / auth quick-reference tables
errors.md	Error codes and details
examples.md	Request / response examples
functions.md	Important frontend functions
headers.md	HTTP headers used by the client
network-flow.md	Request lifecycle and sequencing
objects.md	Domain object reference
polling-behavior.md	Polling loop characteristics
reliability.md	Failure modes and stability notes
requests.md	Request payload reference
responses.md	Response format reference
reverse-engineering.md	Methodology and findings
security.md	Protection mechanisms
state.md	Runtime state variables
storage.md	Browser storage keys
tokens.md	Token reference

---

Repository Structure

.
├── README.md
├── LICENSE
└── docs/
    ├── api.md
    ├── architecture.md
    ├── authentication.md
    ├── changelog.md
    ├── client-behavior.md
    ├── constants.md
    ├── data-models.md
    ├── endpoints.md
    ├── endpoints-table.md
    ├── errors.md
    ├── examples.md
    ├── functions.md
    ├── headers.md
    ├── network-flow.md
    ├── objects.md
    ├── polling-behavior.md
    ├── reliability.md
    ├── requests.md
    ├── responses.md
    ├── reverse-engineering.md
    ├── security.md
    ├── state.md
    ├── storage.md
    └── tokens.md

---

Notes

This document describes observed runtime behavior only. Backend validation rules, ranking algorithms and moderation logic are not exposed and remain server-side.