Формат HMP1 и HMP2
Бинарь тепловой карты байт за байтом — заголовок, кадры, коды объёма HMP2 и ряды цены, с декодером на Python.
GET /v1/heatmap?format=hmp1 или format=hmp2 отдаёт тепловую карту не таблицей, а бинарём: он во много раз короче таблицы, идёт потоком и кэшируется. Его удобно рисовать — разбирать можно кадр за кадром, не дожидаясь конца тела. Параметры запроса — те же, что у таблицы.
format |
Что внутри | Content-Type |
|---|---|---|
hmp1 |
объёмы точными целыми | application/octet-stream |
hmp2 |
объём кодом в 6–9 бит, короче HMP1; qbits — бит мантиссы (6–9, по умолчанию 6), layout — 0 кадры или 1 ряды |
application/x-hmp2 |
format=hmp1|hmp2 у других маршрутов — 400 bad_format; qbits или layout без format=hmp2 — 400 bad_request. Ошибки приходят JSON, как всегда.
Кэш и объём
Заголовок ставит источник тепловой карты, шлюз передаёт его как есть:
Cache-Control |
Когда |
|---|---|
no-store |
окно кончается в последней минуте — живой край |
public, max-age=600 |
конец окна не старше 50 часов: ремонт из архива ещё может залить дыры |
public, max-age=86400, immutable |
старше |
У закрытых диапазонов есть ETag. Повторный запрос с If-None-Match: <ETag> получает 304 Not Modified без тела — суточный объём он не расходует. Оборванная загрузка расходует столько байт, сколько успела получить.
Заголовок
Little-endian, 48 байт:
| Смещение | Размер | Поле |
|---|---|---|
| 0 | 4 | magic: HMP1 или HMP2 |
| 4 | 2 | version: 1 у HMP1, 2 у HMP2 |
| 6 | 2 | flags |
| 8 | 8 | bucket_size (i64) — высота ячейки в единицах price_scale |
| 16 | 1 | price_scale (u8) |
| 17 | 1 | qty_scale (u8) |
| 18 | 1 | HMP1: 0; HMP2: qty_bits (6–9) |
| 19 | 1 | HMP1: 0; HMP2: layout (0 — кадры, 1 — ряды) |
| 20 | 4 | time_step_ms (u32) |
| 24 | 8 | from_ms (i64) |
| 32 | 8 | to_ms (i64) |
| 40 | 4 | frame_count (u32) — число колонок времени |
| 44 | 4 | stream_id (u32), у REST 0 |
flags: бит 0 — значения агрегированы максимумом (иначе средним); бит 1 — ответ упёрся в потолок тела источника (16 МБ) и обрезан справа по времени. Продолжение — тот же запрос с from = время последнего кадра + time_step_ms.
Разбирайте ответ по заголовку (magic, version, layout), а не по своему запросу.
Цена и объём ячейки:
price = idx * bucket_size / 10^price_scale нижняя граница ячейки [price, price + шаг)
qty = q / 10^qty_scale в монетах
шаг = bucket_size / 10^price_scaleКадры — HMP1 и HMP2 с layout=0
После заголовка — frame_count кадров подряд:
varint ts_delta_ms от ts предыдущего кадра; у первого — от from_ms
u8 kind 1 = KEY (полное состояние), 0 = DELTA (изменения)
zigzag best_bid_d разность к best_bid предыдущего кадра; у первого — к 0
zigzag best_ask_d то же для best_ask
varint bid_count
bid_count раз:
zigzag idx_delta к idx предыдущей ячейки; у первой — к 0
varint qty АБСОЛЮТНЫЙ объём ячейки (в HMP2 — код); 0 = уровень исчез
varint ask_count
ask_count раз: то же самоеvarint — LEB128 без знака. zigzag — LEB128 поверх (n << 1) ^ (n >> 63), раскодируется как (u >> 1) ^ -(u & 1).
Держите два словаря idx → qty, для бидов и асков:
- KEY — словари замещаются содержимым кадра;
- DELTA — накладывается поверх:
qty > 0— присвоить,qty == 0— удалить ключ.
Первый кадр всегда KEY, дальше KEY повторяется каждые 512 кадров. Счётчики ts, best_bid, best_ask живут в пределах одного ответа. Состояние словарей после кадра — одна колонка тепловой карты.
import struct
def uvarint(b, p):
out = shift = 0
while True:
x = b[p]; p += 1
out |= (x & 0x7F) << shift
if x < 0x80:
return out, p
shift += 7
def svarint(b, p):
u, p = uvarint(b, p)
return (u >> 1) ^ -(u & 1), p
def columns(b):
"""HMP1 -> [(ts, {price: qty} биды, {price: qty} аски)]."""
assert b[:4] == b"HMP1"
bucket, ps, qs = struct.unpack_from("<qBB", b, 8)
step_ms, from_ms, _to, frames = struct.unpack_from("<IqqI", b, 20)
if frames == 0:
return []
bid, ask, out, p, ts = {}, {}, [], 48, from_ms
for _ in range(frames):
d, p = uvarint(b, p); ts += d
kind = b[p]; p += 1
_, p = svarint(b, p); _, p = svarint(b, p) # best_bid_d, best_ask_d
for book in (bid, ask):
n, p = uvarint(b, p)
cells, idx = [], 0
for _ in range(n):
di, p = svarint(b, p); idx += di
q, p = uvarint(b, p)
cells.append((idx, q))
if kind == 1:
book.clear()
book.update((i, q) for i, q in cells if q > 0)
else:
for i, q in cells:
if q: book[i] = q
else: book.pop(i, None)
price = lambda i: i * bucket / 10**ps
out.append((ts,
{price(i): q / 10**qs for i, q in sorted(bid.items())},
{price(i): q / 10**qs for i, q in sorted(ask.items())}))
assert p == len(b), "после кадров остались байты"
return outТаблица format=json — ровно этот разбор: строка на каждую ненулевую ячейку каждой колонки.
HMP2: объём кодом
Кадры с layout=0 — байт в байт как у HMP1, но вместо varint qty стоит varint code:
code = 0— уровня нет (в DELTA — «уровень исчез»);- иначе
code— объём ячейки в монетах в формате сm = qty_bitsбитами мантиссы.
DELTA сравнивает коды: ячейка, у которой код не сменился, в DELTA не попадает, даже если сырой объём чуть сдвинулся.
Раскодирование (d = 23 − m): code = 0 → 0, иначе v = from_bits(((code + (64 << m)) << d) as u32) как float32 — объём в монетах, qty_scale к нему уже не применяется. При m = 9 ошибка не больше 2⁻¹⁰, диапазон — от 2⁻⁶³ до 2⁶⁵ монет.
import struct
def hmp2_qty(code, m):
if code == 0:
return 0.0
bits = (code + (64 << m)) << (23 - m)
return struct.unpack("<f", struct.pack("<I", bits))[0]Векторы для проверки своей реализации:
| Объём | Код m=9 | Обратно | Код m=6 | Обратно |
|---|---|---|---|---|
| 1e-8 | 18607 | 9.997166e-9 | 2326 | 1.0011718e-8 |
| 0.001 | 27148 | 0.0009994507 | 3394 | 0.0010070801 |
| 0.5 | 31744 | 0.5 | 3968 | 0.5 |
| 1 | 32256 | 1 | 4032 | 1 |
| 1023 | 37375 | 1023 | 4672 | 1024 |
| 12345.678 | 39172 | 12352 | 4896 | 12288 |
HMP2, layout=1: ряды цены
Тот же заголовок с байтом 19 = 1. Тело — четыре потока подряд, без kind и счётчиков кадра:
- Время:
frame_countразvarint ts_delta,zigzag best_bid_d,zigzag best_ask_d— как у кадра. - Ряды: для бидов, затем асков —
varint R, потом R разzigzag idx_delta(первый — от 0, дальше — от idx прошлого ряда этой стороны, строго по возрастанию) иvarint run_count. - Длины: все ряды бидов, затем асков, по каждой серии
varint (len − 1). Сумма длин по ряду =frame_count. - Коды: в том же порядке по каждой серии
zigzag(code − prev),prev = 0в начале каждого ряда.code = 0— уровня нет в этих колонках.
Ряд без единого ненулевого кода не пишется. Колонку рядов нельзя прочитать отдельно от всего тела — для потоковой отрисовки берите layout=0.