Протоколы участковых комиссий по одному запросу

Как устроены данные

У каждой УИК два протокола: candidates — голосование по одномандатному округу, и parties — по партийным спискам. В протоколе: число избирателей, бюллетеней в ящиках, недействительных бюллетеней и голоса за каждого кандидата или партию.

Номер УИК не уникален. Нумерация комиссий своя в каждом регионе, поэтому УИК №15 есть в десятках округов. Однозначно комиссию задаёт пара округ:УИК или commission_id — UUID комиссии в системе ЦИК.

Протокол может иметь несколько версий. Данные собраны из нескольких выгрузок; если за это время протокол переписали, в базе есть обе версии. По умолчанию API отдаёт последнюю увиденную. Параметр download показывает данные на момент конкретной выгрузки, а метод истории — все версии с разницей между ними.

Даты — в UTC. Явка — это бюллетени в ящиках, делённые на число избирателей. Процент голосов считается от числа бюллетеней в ящиках.

Получить УИК

Основной метод — GET /api/v1/uiks. Он всегда возвращает список, поэтому одинаково подходит для одной комиссии и для тысячи.

Для одной комиссии есть короткие адреса: /api/v1/okrugs/{округ}/uiks/{УИК} и /api/v1/uiks/{commission_id}.

Если список УИК длинный, передайте его телом запроса в POST /api/v1/uiks/query:

curl -X POST https://uik.animevpn.ru/api/v1/uiks/query \
  -H 'Content-Type: application/json' \
  -d '{"pairs": [{"okrug": 1, "uik": 15}, "171:74"], "type": "parties"}'

Если какие-то пары или ID не нашлись, они перечислены в поле not_found ответа.

{
  "meta": {"total": 1, "page": 1, "per_page": 100, "pages": 1},
  "items": [{
    "commission_id": "7c0e12f5-ed9c-4a14-8784-ccfa7aa5f1cc",
    "okrug": 1, "uik": 1,
    "protocols": {
      "parties": {
        "voters": 2216, "ballots": 2106, "invalid": 0, "valid": 2106,
        "turnout": 95.04,
        "cik_created_at": "2026-09-21T03:41:47.338289Z",
        "versions": 1, "content_versions": 1, "changed": false,
        "leader": "Всероссийская политическая партия \"ЕДИНАЯ РОССИЯ\"",
        "votes": [{"subject_id": 1486, "name": "…", "votes": 1411, "percent": 67.0}, …]
      },
      "candidates": { … }
    }
  }]
}

Фильтры

Эти параметры работают в /uiks, /results и /subjects/{id}/uiks. Списки пишутся через запятую, диапазоны — через дефис: 1,2,10-20. Параметр можно повторять.

Пример: УИК округов 1–10 с явкой от 95%, сначала самые высокие — /api/v1/uiks?okrug=1-10&turnout_min=95&sort=-turnout&votes=false

Итоги по выборке

GET /api/v1/results складывает протоколы всех УИК, подходящих под фильтры, и возвращает общие цифры и голоса. Так можно посчитать итог по любому набору комиссий.

У кандидатов процент и место считаются внутри их округа. Сводки по округам с лидерами — /api/v1/okrugs и /api/v1/okrugs/{округ}.

Кандидаты и партии

• /api/v1/parties — партии с итогами.
• /api/v1/candidates?okrug=1 — кандидаты округа; поиск по ФИО: ?q=Иванов.
• /api/v1/subjects/{subject_id} — итоги кандидата или партии, у партии — по каждому округу.
• /api/v1/subjects/{subject_id}/uiks?sort=-percent — результат на каждой УИК: где больше всего, где меньше. Принимает все фильтры.

История протоколов

GET /api/v1/uiks/{commission_id}/history отдаёт все версии протоколов УИК: когда каждую видели, в какой выгрузке, и что поменялось по сравнению с предыдущей версией.

/api/v1/changes — список всех протоколов, где менялись цифры, с первой и текущей версией и разницей. С numbers_only=false туда попадут и перевыпуски без изменения цифр.

"diff": {
  "voters": [12903, 1293],
  "cik_created_at": ["2026-09-21T02:19:25Z", "2026-09-22T04:42:00Z"]
}

Выгрузка в CSV

Добавьте format=csv к /uiks, /results или /subjects/{id}/uiks — вернётся файл со всей выборкой без пагинации. Разделитель — точка с запятой, кодировка UTF-8 с BOM, поэтому файл открывается в Excel без настроек.

У /uiks два вида таблицы: layout=wide (по умолчанию) — одна строка на протокол, голоса в колонках; layout=long — одна строка на каждого кандидата или партию.

/api/v1/uiks?okrug=1&type=parties&format=csv

Лимиты

Ключ не нужен. Чтобы сервис оставался доступен всем, у каждого IP есть бюджет 120 очков в минуту, который восстанавливается постепенно.

Тяжёлые запросы — CSV, POST и итоги по фильтрам — с одного IP выполняются по одному. Остаток бюджета приходит в заголовках X-RateLimit-Remaining, X-RateLimit-Reset и X-RateLimit-Cost. Когда бюджет кончился, API отвечает 429 с заголовком Retry-After — подождите указанное число секунд.

Ответы кэшируются до следующего обновления данных. Если нужна вся база — один запрос с format=csv выгоднее сотни страниц.

Ошибки

Ошибка всегда приходит как JSON с полем detail, где по-русски написано, что не так.

Примеры кода

Python

import time, requests

BASE = "https://uik.animevpn.ru/api/v1"

def get(path, **params):
    while True:
        r = requests.get(f"{BASE}{path}", params=params, timeout=60)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", 5)))
            continue
        r.raise_for_status()
        return r.json()

# все УИК округа 171 с голосами, постранично
page = 1
while True:
    data = get("/uiks", okrug=171, type="candidates", per_page=200, page=page)
    for uik in data["items"]:
        p = uik["protocols"]["candidates"]
        print(uik["uik"], p["turnout"], p["leader"])
    if page >= data["meta"]["pages"]:
        break
    page += 1

JavaScript

const res = await fetch("https://uik.animevpn.ru/api/v1/uiks?pair=1:15,171:74&type=parties");
const { items, not_found } = await res.json();
for (const u of items) console.log(u.okrug, u.uik, u.protocols.parties.leader);

curl

curl -o okrug1.csv 'https://uik.animevpn.ru/api/v1/uiks?okrug=1&format=csv'

Все методы

Полное описание параметров и схем ответов с кнопкой «Try it out» — в Swagger и ReDoc. Машиночитаемая спецификация — openapi.json.