Рейтинги и игроки
Статистика сайта
Три настройки проекта site.statistics.online, site.statistics.accounts и site.statistics.characters независимо разрешают публикацию показателей. Все восемь сочетаний допустимы; отсутствующая настройка считается false. Публикация разрешена только при булевом true. Примеры каждого сочетания приведены в руководстве по проектам.
| Настройка | Текущий запрос | Тип результата |
|---|---|---|
online | serversOnline(gameServerIds: [Int!]) | [ServerOnline!] |
characters | serversCharacters(gameServerIds: [Int!]) | [ServerCharacterCount!] |
accounts | siteAccountCount | SiteAccountCount |
Внешние списки онлайна и персонажей допускают null. Если соответствующий показатель выключен, запрошенное поле целиком равно null, а не пустому списку или нулю.
Все операции используют существующий протокол проекта: POST /graphql, X-Project-Context из identity.contextToken и JSON с documentId и variables. Сессия игрока не требуется. GraphQL ниже показывает структуру именованной операции, а не заменяет формат HTTP-запроса.
serversCharacters
Число персонажей одного, нескольких или всех серверов текущего проекта. Это население серверов, а не число зарегистрированных пользователей кабинета.
| Входное поле | Тип | Описание |
|---|---|---|
gameServerIds | [Int!] | Без аргумента или с null выбираются все серверы проекта. Для выбора передайте от 1 до 100 уникальных положительных ID. |
Указывайте уникальные ID серверов выбранного проекта; пустой список недопустим. При включённой публикации проект без серверов возвращает []. При выключенной публикации результат равен null.
Элемент ServerCharacterCount содержит:
| Поле | Тип | Описание |
|---|---|---|
gameServerId | Int! | ID игрового сервера. |
state | ServerOnlineState! | FRESH, STALE, MISSING или UNAVAILABLE. |
count | UnsignedInt | Измеренное число персонажей: JSON-число от 0 до 4 294 967 295. |
observedAt | String | Время измерения в UTC RFC3339. |
staleAt | String | Время в UTC RFC3339, после которого измерение считается устаревшим. |
{
"documentId": "serversCharacters",
"variables": {
"gameServerIds": [
1,
2
]
}
}
{
"data": {
"serversCharacters": [
{
"gameServerId": 1,
"state": "FRESH",
"count": 0,
"observedAt": "2026-09-08T13:30:00Z",
"staleAt": "2026-09-08T13:40:00Z"
},
{
"gameServerId": 2,
"state": "MISSING",
"count": null,
"observedAt": null,
"staleAt": null
}
]
}
}
Измеренный 0 передаётся числом, не строкой. MISSING означает, что измерения нет; UNAVAILABLE означает временную недоступность данных. В обоих состояниях число и время измерения равны null. STALE сохраняет последнее число и время замера: его можно показать с пометкой об устаревании. Эти правила также применяются к текущему онлайну. Ошибка запроса не превращается в нулевой замер.
siteAccountCount
Число зарегистрированных пользователей кабинета текущего проекта. Запрос не принимает аргументов: ID команды, проекта или сервера передавать нельзя. Выбор игровых серверов не влияет на этот показатель. Здесь аккаунты означают пользователей кабинета, а не игровые аккаунты или сумму аккаунтов по серверам.
Результат SiteAccountCount допускает null и содержит только:
| Поле | Тип | Описание |
|---|---|---|
count | SiteAccountPopulation! | Целое JSON-число от 0 до 9 007 199 254 740 991 включительно. Диапазон не ограничен знаковым 32-битным Int. |
observedAt | String! | Время измерения в UTC RFC3339, не время открытия страницы. |
Email, IP и другие персональные поля не возвращаются. При site.statistics.accounts !== true результат равен null. При включённой публикации и отсутствии зарегистрированных пользователей возвращается честный числовой 0. Ошибка получения данных передаётся как ошибка, а не как пустое население. Полей state и staleAt у этого типа нет.
{
"documentId": "siteAccountCount",
"variables": {}
}
{
"data": {
"siteAccountCount": {
"count": 0,
"observedAt": "2026-09-08T13:30:00.000000Z"
}
}
}
siteStatistics
Одна именованная операция для показателей сайта:
query siteStatistics(
$gameServerIds: [Int!]
$includeServers: Boolean!
$includeAccounts: Boolean!
) {
serversOnline(gameServerIds: $gameServerIds) @include(if: $includeServers) {
gameServerId
state
current
peak
observedAt
staleAt
loginAvailable
gameAvailable
}
serversCharacters(gameServerIds: $gameServerIds) @include(if: $includeServers) {
gameServerId
state
count
observedAt
staleAt
}
siteAccountCount @include(if: $includeAccounts) {
count
observedAt
}
}
| Переменная | Тип | Когда передавать |
|---|---|---|
gameServerIds | [Int!] | Необязательный выбор серверов для онлайна и персонажей. На аккаунты не влияет. |
includeServers | Boolean! | true, если нужен онлайн или персонажи. Обязательна. |
includeAccounts | Boolean! | true, если нужны зарегистрированные пользователи кабинета. Обязательна. |
Пропущенное через @include(if: false) поле отсутствует в ответе; запрошенный, но выключенный показатель возвращается как null.
{
"documentId": "siteStatistics",
"variables": {
"gameServerIds": [
1
],
"includeServers": true,
"includeAccounts": true
}
}
{
"data": {
"serversOnline": [
{
"gameServerId": 1,
"state": "FRESH",
"current": 0,
"peak": 18,
"observedAt": "2026-09-08T13:30:00Z",
"staleAt": "2026-09-08T13:40:00Z",
"loginAvailable": true,
"gameAvailable": true
}
],
"serversCharacters": [
{
"gameServerId": 1,
"state": "FRESH",
"count": 12,
"observedAt": "2026-09-08T13:30:00Z",
"staleAt": "2026-09-08T13:40:00Z"
}
],
"siteAccountCount": {
"count": 24,
"observedAt": "2026-09-08T13:30:00.000000Z"
}
}
}
Для одних аккаунтов передайте includeServers: false и includeAccounts: true; список серверов не требуется. Если вызывающей стороне не нужен ни один из трёх показателей, оба флага можно передать как false, исключив все три поля из ответа. Нужные показатели следует запрашивать независимо от локально сохранённых флагов публикации; их текущую доступность определяет ответ API.
При частичной недоступности не подставляйте нули и не суммируйте неполный набор серверных замеров. Успешно полученное число пользователей кабинета можно показывать, даже если онлайн и персонажи временно недоступны.
Доступные Разделы
Операции используют выбранный проект. Отключённые инструменты возвращают ошибку, скрытые таблицы и группы отсутствуют в ответе. Для истории, поиска и сравнения применяются выбранные рейтинги и размер топа.
Архив гербов содержит изображения для строк ответа.
Переключатели публикации статистики сайта определяют и доступные исторические данные. При выключенном online поле serverOnlineHistory.points[].online равно null; при выключенном characters скрывается points[].characters. Выключенные characters также исключают count_char из top_statistic.summary, группы races и genders; распределение классов rankingClassDistribution становится недоступным. Таблицы рейтингов персонажей и кланов настраиваются независимо.
serverRatingVisibility
Текущий набор доступных разделов статистики. Используйте ответ для меню и инструментов. После изменения настроек запрашивайте его заново.
Входные данные
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
gameServerId | Int! | Да | Положительный ID сервера текущего проекта. |
Результат
ServerRatingVisibility!. Все поля имеют тип Boolean!.
| Поле | Раздел |
|---|---|
records | Рекорды онлайна. |
onlineChart | График истории; false, если выключены все ряды. |
generalSummary | Общая сводка. |
raceDistribution | Распределение по расам. |
genderDistribution | Распределение по полу. |
activityHeatmap | Активность по дням и часам. |
classPopularity | Популярность классов. |
risingStars | Быстро растущие игроки. |
serverTimeline | Хроника изменений рейтингов. |
search | Поиск и профиль персонажа в рейтингах. |
comparison | Сравнение персонажей. |
snapshot | Рейтинг на выбранную дату. |
Флаг разрешает показ, но не означает наличие данных. Сводка и распределения также требуют включённой общей статистики. Разрешённые таблицы с текущими ограничениями размера возвращает serverRankingSnapshot.
Ошибки
Некорректные параметры или выключенная функция возвращают ошибку. При изменении настроек обновите список доступных разделов.
Пример обмена
{
"documentId": "serverRatingVisibility",
"variables": {
"gameServerId": 1
}
}
{
"data": {
"serverRatingVisibility": {
"records": false,
"onlineChart": true,
"raceDistribution": false,
"genderDistribution": false,
"generalSummary": false,
"activityHeatmap": false,
"classPopularity": false,
"risingStars": false,
"serverTimeline": false,
"search": false,
"comparison": false,
"snapshot": false
}
}
}
Текущий Рейтинг И Снимок На Дату
serverRankingSnapshot
Описание
Текущие таблицы и рейтинг на выбранную дату используют одну операцию. Без at возвращается последнее доступное наблюдение каждого разрешённого типа. С at выбирается последнее наблюдение не позднее указанного времени; просмотр снимков должен быть включён администратором.
Каждая таблица имеет собственные ID и время сбора. Их нельзя заменять временем открытия страницы или считать, что все таблицы собраны одновременно. Изменение текущих настроек публикации применяется и к старым снимкам.
Входные данные
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
gameServerId | Int! | Да | Положительный ID сервера текущего проекта. |
type | String | Для продолжения | Один разрешённый тип. Без него возвращаются все разрешённые таблицы. |
at | String | Нет | RFC3339 с часовым поясом, не позднее текущего времени. Например, 2026-09-08T12:00:00Z. В ответе время нормализовано в UTC с миллисекундами. |
first | Int | Нет | От 1 до 100 строк на таблицу, по умолчанию 50. Текущий размер топа может ограничить результат сильнее. |
after | String | Нет | Непустой endCursor предыдущей страницы, до 4096 символов. Требует type. |
Типы рейтингов: top_pvp, top_pk, top_exp, top_clan, top_clan_pvp, top_ally, top_hero, top_hero_active, top_pkw, top_pkt, top_rank, rankings_glory, rankings_abyss, rankings_kills, rankings_legions. Типы статистики мира: top_castle, top_clanhols, top_raidboss, top_statistic. Доступный набор зависит от игры и настроек.
Результат
Тип ответа: RankingSnapshotReport!.
| Поле | Тип | Значение |
|---|---|---|
generatedAt | String | Время подготовки ответа. |
observedAt | String | Временная граница чтения, для снимка соответствует at. |
snapshots | [RankingSnapshot!]! | Только разрешённые таблицы. Если ни одна не включена, список пуст. |
crest | RankingSnapshotCrest | Необязательный архив гербов: gameServerId: Int!, file: String! (ZIP в Base64). Отсутствие архива не отменяет рейтинг. |
При недоступности отчёта generatedAt и observedAt равны null. Время в остальных ответах передаётся в UTC RFC3339.
Каждый RankingSnapshot содержит:
| Поле | Тип | Значение |
|---|---|---|
type | String! | Тип таблицы. |
state | RankingSnapshotState! | Состояние из таблицы ниже. |
snapshotId | String | Непрозрачный идентификатор наблюдения этой таблицы. |
capturedAt | String | Фактическое время её сбора. |
staleAt | String | Граница актуальности наблюдения. |
entries | JSON! | Массив строк текущей страницы, не JSON-строка. |
pageInfo.hasNextPage | Boolean! | Можно ли продолжить эту таблицу. |
pageInfo.endCursor | String | Курсор продолжения; null, когда продолжения нет. |
| Состояние | Строки и метаданные |
|---|---|
FRESH | Актуальное наблюдение. Пустой entries означает, что сбор выполнен, но участников нет. |
STALE | Наблюдение устарело; строки, ID и фактическое время сохраняются. Для исторического снимка актуальность оценивается на выбранное время. |
MISSING | В доступной истории нет наблюдения на запрошенный момент. Строки пусты, ID и время равны null. |
SOURCE_ERROR | Последний сбор этой таблицы завершился ошибкой. Время попытки и ID сохранены, строки пусты. |
UNAVAILABLE | Сейчас нельзя получить отчёт. Строки пусты, ID и время равны null. |
Строка содержит rank (целая позиция в полном снимке), value, positionChange и isNew, а также поля своей игры. Имена представлены как charName, clanName и allianceName, когда применимы. positionChange допускает null: без предыдущего сопоставимого наблюдения изменение неизвестно. isNew: true означает появление относительно предыдущего наблюдения, а не дату регистрации.
value рейтинга всегда точная десятичная строка, до 160 символов. Например, "9223372036854775808" нельзя преобразовывать в JavaScript Number: это потеряет точность. Для статистики мира value явно равно null, а не "0".
У top_statistic разрешённые показатели сгруппированы в summary, genders и races. Выключенные группы отсутствуют. Выключенная публикация персонажей исключает summary.count_char, genders и races; остальные разрешённые показатели сводки остаются. Гербы включаются только для видимых строк.
Продолжение Таблицы
Сохраните pageInfo.endCursor выбранной таблицы. В следующем запросе передайте его как after, укажите её type, оставьте прежние gameServerId и at. Размер first остаётся ограниченным 1..100.
Курсор удерживает исходное наблюдение: новый сбор данных не перемешивает страницы. Позиции не начинаются заново с единицы. Срок действия курсора составляет один час. Передавайте курсор без изменений; при выборе другого сервера, типа, даты или размера топа начните с первой страницы. Ошибка продолжения не означает конец списка: сохраняйте уже показанные строки и предлагайте обновить таблицу.
Ошибки
Неверные аргументы, неизвестный или выключенный тип и выключенный просмотр снимков возвращают ошибку GraphQL. Некорректный, просроченный или больше недоступный курсор также возвращает ошибку. Не заменяйте их пустым успешным списком. Временная недоступность самого отчёта обозначается UNAVAILABLE.
Пример обмена
{
"documentId": "serverRankingSnapshot",
"variables": {
"gameServerId": 1,
"type": "top_exp",
"at": "2026-09-08T12:00:00Z",
"first": 50
}
}
{
"data": {
"serverRankingSnapshot": {
"generatedAt": "2026-09-08T12:05:00.000Z",
"observedAt": "2026-09-08T12:00:00.000Z",
"snapshots": [
{
"type": "top_exp",
"state": "FRESH",
"snapshotId": "019927d0-1234-7000-8000-000000000001",
"capturedAt": "2026-09-08T11:59:00.000Z",
"staleAt": "2026-09-08T12:59:00.000Z",
"entries": [
{
"rank": 1,
"value": "9223372036854775808",
"charName": "Aeris",
"clanName": "Aether",
"positionChange": null,
"isNew": false
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": null
}
}
],
"crest": null
}
}
}
Для следующей страницы используется тот же documentId:
{
"documentId": "serverRankingSnapshot",
"variables": {
"gameServerId": 1,
"type": "top_pvp",
"first": 50,
"after": "<endCursor из предыдущего ответа с hasNextPage: true>"
}
}
Значение в угловых скобках иллюстративное: передавайте полученный курсор целиком. Для текущего рейтинга at отсутствует; для исторического повторяйте выбранное время.
Связанные типы
История персонажа
rankingCharacterHistory
Позиции одного персонажа в одном рейтинге за выбранный период. Имя сопоставляется целиком без учёта регистра. Кланы, альянсы и общая статистика не входят в эту операцию.
| Поле | Тип | Описание |
|---|---|---|
gameServerId | Int! | Положительный ID сервера текущего проекта. |
name | String! | Имя персонажа, от 1 до 128 символов, без управляющих символов и пробелов по краям. |
type | String! | Включённый рейтинг персонажей, например top_pvp. |
days | Int | От 1 до 90 дней; по умолчанию 30. |
first | Int | От 1 до 100 наблюдений; по умолчанию 50. |
after | String | pageInfo.endCursor предыдущего ответа; для первой страницы не передаётся. |
Результат RankingCharacterHistoryReport! содержит:
| Поле | Описание |
|---|---|
type, name | Запрошенные рейтинг и имя. |
state | READY, MISSING или UNAVAILABLE. |
generatedAt | Время формирования ответа в UTC RFC3339. |
observedAt, from | Верхняя и нижняя границы периода в UTC RFC3339. |
summary | Сводка за весь период, не только текущую страницу. |
entries | Наблюдения от новых к старым. |
pageInfo | hasNextPage: Boolean! и endCursor: String. |
В сводке observations означает число наблюдений, rankedObservations - число попаданий в разрешённый топ, sourceErrors - число ошибок сбора. sampledDays считает дни UTC с успешными наблюдениями, daysRanked - дни с попаданием в топ. bestRank и worstRank равны null, если попаданий не было.
Каждая строка содержит snapshotId, capturedAt, state, rank и value:
| Состояние строки | Значение |
|---|---|
RANKED | Есть место и точное значение очков строкой. |
NOT_RANKED | Наблюдение успешно собрано, но персонажа нет в разрешённом топе. Место и очки равны null. |
SOURCE_ERROR | Собрать рейтинг не удалось. Место и очки равны null; это не потеря места. |
MISSING означает отсутствие наблюдений за период: список пуст, счётчики сводки равны нулю. UNAVAILABLE означает временную недоступность отчёта: сводка и времена равны null, список пуст. Не заменяйте неизвестные места и очки нулём.
{
"documentId": "rankingCharacterHistory",
"variables": {
"gameServerId": 1,
"name": "AriaDawn",
"type": "top_exp",
"days": 7,
"first": 50
}
}
{
"data": {
"rankingCharacterHistory": {
"type": "top_exp",
"name": "AriaDawn",
"state": "READY",
"generatedAt": "2026-09-09T12:00:00.000Z",
"observedAt": "2026-09-09T12:00:00.000Z",
"from": "2026-09-02T12:00:00.000Z",
"summary": {
"observations": 3,
"rankedObservations": 1,
"sourceErrors": 1,
"sampledDays": 1,
"daysRanked": 1,
"bestRank": 1,
"worstRank": 1
},
"entries": [
{
"snapshotId": "01a083cd-f900-7000-8000-000000000003",
"capturedAt": "2026-09-09T11:55:00.000Z",
"state": "RANKED",
"rank": 1,
"value": "9223372036854775808"
},
{
"snapshotId": "01a083cd-f900-7000-8000-000000000002",
"capturedAt": "2026-09-09T11:50:00.000Z",
"state": "SOURCE_ERROR",
"rank": null,
"value": null
},
{
"snapshotId": "01a083cd-f900-7000-8000-000000000001",
"capturedAt": "2026-09-09T11:45:00.000Z",
"state": "NOT_RANKED",
"rank": null,
"value": null
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": null
}
}
}
}
При продолжении сохраняйте имя, рейтинг, сервер и период; передавайте полученный курсор без изменений. Границы периода и сводка сохраняются между страницами. Истёкший или неподходящий курсор отклоняется: начните с первой страницы. Изменение доступности, размера топа или состава сохранённых наблюдений также может потребовать обновления.
При выключенном поиске или рейтинге и некорректных аргументах возвращается ошибка. Текущий размер топа применяется ко всем историческим наблюдениям. Очень большой период с более чем 25 000 наблюдений необходимо сократить.
Поиск персонажей
searchRankingCharacters
Поиск только по именам персонажей в последних доступных рейтингах выбранного сервера. Возвращает имя каждого совпадения, его место, точные очки и изменение позиции.
| Поле | Тип | Описание |
|---|---|---|
gameServerId | Int! | Положительный ID сервера текущего проекта. |
name | String! | От 1 до 128 символов, без управляющих символов и пробелов по краям. |
matchMode | RankingCharacterMatchMode | CONTAINS для части имени (по умолчанию) или EXACT для полного имени. Регистр не учитывается. |
type | String | Один включённый рейтинг персонажей. Без него выбираются все доступные. |
first | Int | От 1 до 100 совпадений на рейтинг; по умолчанию 50. |
after | String | Курсор следующей страницы. Требует конкретный type. |
Результат RankingCharacterSearchReport!: generatedAt, observedAt и snapshots. Каждый снимок содержит type, state, snapshotId, capturedAt, staleAt, entries и pageInfo. Состояния и времена соответствуют снимку рейтинга.
Строка результата содержит name: String!, rank: Int!, value: String!, positionChange: Int и isNew: Boolean!. Значение очков нельзя преобразовывать в число с плавающей точкой: оно может превышать безопасный диапазон JavaScript. Положительное изменение означает подъём, отрицательное - снижение, 0 - сохранение места, null - отсутствие сопоставимого предыдущего наблюдения.
{
"documentId": "searchRankingCharacters",
"variables": {
"gameServerId": 1,
"name": "AriaDawn",
"matchMode": "EXACT",
"type": "top_exp",
"first": 50
}
}
{
"data": {
"searchRankingCharacters": {
"generatedAt": "2026-09-09T12:00:00.000Z",
"observedAt": "2026-09-09T12:00:00.000Z",
"snapshots": [
{
"type": "top_exp",
"state": "FRESH",
"snapshotId": "01a083cd-f900-7000-8000-000000000003",
"capturedAt": "2026-09-09T11:55:00.000Z",
"staleAt": "2026-09-09T12:55:00.000Z",
"entries": [
{
"name": "AriaDawn",
"rank": 1,
"value": "9223372036854775808",
"positionChange": null,
"isNew": true
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": null
}
}
]
}
}
}
Пустые entries в свежем или устаревшем снимке означают отсутствие совпадений в опубликованном топе. Ошибка сбора и недоступность отчёта имеют отдельные состояния. Для продолжения передавайте курсор соответствующего рейтинга с прежними именем и режимом поиска. Места остаются местами в полном рейтинге, а не номерами строк поиска.
Для профиля используйте точный поиск и отдельно rankingCharacterHistory выбранного рейтинга.
Быстро растущие игроки
rankingRisingCharacters
Возвращает новых участников и персонажей, поднявшихся в каждом включённом рейтинге. Сначала идут новые участники, затем положительные изменения по убыванию; при равенстве используется текущее место. «Новый» означает отсутствие в предыдущем опубликованном топе, а не создание нового персонажа в игре.
| Поле | Тип | Описание |
|---|---|---|
gameServerId | Int! | Положительный ID сервера текущего проекта. |
type | String | Один включённый рейтинг персонажей. Без него возвращаются все доступные рейтинги персонажей. Обязателен с after. |
first | Int | 1..100 строк на рейтинг; по умолчанию 50. |
after | String | Курсор продолжения соответствующего рейтинга, до 4096 символов. |
Результат RankingRisingCharactersReport! содержит generatedAt, observedAt и snapshots.
| Поле снимка | Значение |
|---|---|
type, state | Рейтинг и доступность: FRESH, STALE, MISSING, SOURCE_ERROR или UNAVAILABLE. |
snapshotId, capturedAt, staleAt | Идентификатор наблюдения и даты UTC; null, если наблюдение недоступно. |
movementAvailable | Текущее и предыдущее наблюдения позволяют определить изменение позиции. |
entries | Точное name, текущее rank, десятичная строка value, nullable positionChange и boolean isNew. |
pageInfo | hasNextPage и nullable endCursor. |
Для нового участника isNew=true, positionChange=null; остальные изменения строго положительны. Очки нельзя переводить в число с плавающей точкой. Успешный пустой список при movementAvailable=true означает отсутствие подъёмов; false означает недостаточность наблюдений, в том числе ошибку предыдущего сбора. Ошибка источника не выдаётся за успешно собранный пустой рейтинг.
{
"documentId": "rankingRisingCharacters",
"variables": {
"gameServerId": 1,
"type": "top_exp",
"first": 50
}
}
{
"data": {
"rankingRisingCharacters": {
"generatedAt": "2026-09-09T10:00:00.000Z",
"observedAt": "2026-09-09T10:00:00.000Z",
"snapshots": [
{
"type": "top_exp",
"state": "FRESH",
"snapshotId": "01a07fab-8130-7000-8000-000000000001",
"capturedAt": "2026-09-09T09:59:00.000Z",
"staleAt": "2026-09-09T10:59:00.000Z",
"movementAvailable": true,
"entries": [
{
"name": "KaelDawn",
"rank": 3,
"value": "8000000000",
"positionChange": null,
"isNew": true
},
{
"name": "Aria",
"rank": 1,
"value": "9223372036854775809",
"positionChange": 2,
"isNew": false
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": null
}
}
]
}
}
}
Продолжение сохраняет текущее и предыдущее наблюдения. Передавайте прежние сервер, рейтинг и размер страницы. При изменённых разрешениях или размере топа, неверном либо истёкшем курсоре запрос отклоняется; начните с первой страницы. Поиск может быть выключен независимо.
В обычном текущем результате клиенту не нужны плашки метаданных и даты. При задержке или недоступности достаточно короткого сообщения; API сохраняет метаданные для интеграций.
Сравнение персонажей
compareRankingCharacters
Сопоставляет двух персонажей по полным именам. Внутри каждого рейтинга оба результата относятся к одному наблюдению. Сравнение включается независимо от поиска; выключенный поиск не запрещает эту операцию.
| Поле | Тип | Описание |
|---|---|---|
gameServerId | Int! | Положительный ID сервера текущего проекта. |
firstName | String! | Полное имя первого персонажа, 1..128 символов. |
secondName | String! | Полное имя второго персонажа, 1..128 символов. |
type | String | Один включённый рейтинг персонажей. Без него возвращаются все доступные рейтинги персонажей. |
Имена не должны содержать управляющие символы или пробелы по краям. Сопоставление не учитывает регистр; два одинаковых имени с разным регистром отклоняются. Поиск по части имени не применяется.
Результат RankingCharacterComparisonReport! содержит firstName, secondName, generatedAt, observedAt и snapshots. Каждый снимок содержит:
| Поле | Значение |
|---|---|
type, state | Рейтинг и состояние: FRESH, STALE, MISSING, SOURCE_ERROR или UNAVAILABLE. |
snapshotId, capturedAt, staleAt | ID, время наблюдения и граница актуальности. У разных рейтингов свои наблюдения. При отсутствии соответствующих данных поля равны null. |
first, second | Результат соответствующего персонажа или null: имя, место, точные очки, изменение места и признак нового участника. |
value всегда строка: не преобразовывайте её в JavaScript Number. positionChange сравнивает место с предыдущим сопоставимым наблюдением: положительное число означает подъём, отрицательное снижение, ноль сохранение места, null отсутствие сопоставления. isNew означает появление в опубликованном топе.
{
"documentId": "compareRankingCharacters",
"variables": {
"gameServerId": 1,
"firstName": "AriaDawn",
"secondName": "KaelDawn",
"type": "top_exp"
}
}
{
"data": {
"compareRankingCharacters": {
"firstName": "AriaDawn",
"secondName": "KaelDawn",
"generatedAt": "2026-09-09T12:00:00.000Z",
"observedAt": "2026-09-09T12:00:00.000Z",
"snapshots": [
{
"type": "top_exp",
"state": "FRESH",
"snapshotId": "01a083cd-f900-7000-8000-000000000003",
"capturedAt": "2026-09-09T11:55:00.000Z",
"staleAt": "2026-09-09T12:55:00.000Z",
"first": {
"name": "AriaDawn",
"rank": 2,
"value": "9223372036854775808",
"positionChange": 0,
"isNew": false
},
"second": {
"name": "KaelDawn",
"rank": 1,
"value": "9223372036854775809",
"positionChange": 0,
"isNew": false
}
}
]
}
}
}
В FRESH или STALE значение null у одного участника означает отсутствие в опубликованном топе, а не отсутствие персонажа в игре. В MISSING, SOURCE_ERROR и UNAVAILABLE оба результата равны null; нельзя подставлять нулевые места или очки. При ошибке последнего сбора более старое успешное наблюдение не возвращается как текущее.
При выключенном сравнении, выключенном или неподходящем типе рейтинга и некорректных именах возвращается ошибка. Текущий размер опубликованного топа применяется к обоим результатам.
История сравнения
rankingCharacterComparisonHistory
Общая история двух персонажей для одного рейтинга. Одна строка соответствует одному наблюдению и содержит состояние, место и очки каждого участника. История связана с именами: переименование не объединяет записи автоматически.
| Поле | Тип | Описание |
|---|---|---|
gameServerId | Int! | Сервер текущего проекта. |
firstName, secondName | String! | Два разных полных имени с теми же ограничениями, что у сравнения. |
type | String! | Один включённый рейтинг персонажей. |
days | Int | Период 1..90 дней; по умолчанию 30. |
first | Int | 1..100 наблюдений на страницу; по умолчанию 50. |
after | String | Общий курсор продолжения обеих историй, полученный из pageInfo.endCursor. |
Результат RankingCharacterComparisonHistoryReport! содержит имена, type, state, generatedAt, observedAt, from, firstSummary, secondSummary, entries и pageInfo. Состояние отчёта: READY при наличии наблюдений, MISSING при их отсутствии за период, UNAVAILABLE при временной недоступности отчёта.
Каждая сводка содержит observations, rankedObservations, sourceErrors, sampledDays, daysRanked, bestRank и worstRank. Она относится ко всему выбранному периоду, а не к одной странице. Дни считаются по UTC. При недоступном отчёте сводки равны null.
Строка entries содержит общий snapshotId, capturedAt и два результата first / second:
state | rank и value |
|---|---|
RANKED | Измеренное место и точные очки строкой. |
NOT_RANKED | Оба поля null: персонажа нет среди опубликованных строк этого наблюдения. |
SOURCE_ERROR | Оба поля null: рейтинг не удалось собрать. Это состояние относится к обоим участникам. |
{
"documentId": "rankingCharacterComparisonHistory",
"variables": {
"gameServerId": 1,
"firstName": "AriaDawn",
"secondName": "KaelDawn",
"type": "top_exp",
"days": 7,
"first": 50
}
}
{
"data": {
"rankingCharacterComparisonHistory": {
"firstName": "AriaDawn",
"secondName": "KaelDawn",
"type": "top_exp",
"state": "READY",
"generatedAt": "2026-09-09T12:00:00.000Z",
"observedAt": "2026-09-09T12:00:00.000Z",
"from": "2026-09-02T12:00:00.000Z",
"firstSummary": {
"observations": 3,
"rankedObservations": 1,
"sourceErrors": 1,
"sampledDays": 1,
"daysRanked": 1,
"bestRank": 2,
"worstRank": 2
},
"secondSummary": {
"observations": 3,
"rankedObservations": 2,
"sourceErrors": 1,
"sampledDays": 1,
"daysRanked": 1,
"bestRank": 1,
"worstRank": 1
},
"entries": [
{
"snapshotId": "01a083cd-f900-7000-8000-000000000003",
"capturedAt": "2026-09-09T11:55:00.000Z",
"first": {
"state": "RANKED",
"rank": 2,
"value": "9223372036854775808"
},
"second": {
"state": "RANKED",
"rank": 1,
"value": "9223372036854775809"
}
},
{
"snapshotId": "01a083cd-f900-7000-8000-000000000002",
"capturedAt": "2026-09-09T11:50:00.000Z",
"first": {
"state": "SOURCE_ERROR",
"rank": null,
"value": null
},
"second": {
"state": "SOURCE_ERROR",
"rank": null,
"value": null
}
},
{
"snapshotId": "01a083cd-f900-7000-8000-000000000001",
"capturedAt": "2026-09-09T11:45:00.000Z",
"first": {
"state": "NOT_RANKED",
"rank": null,
"value": null
},
"second": {
"state": "RANKED",
"rank": 1,
"value": "9223372036854775809"
}
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": null
}
}
}
}
Наблюдения упорядочены от новых к старым. Для продолжения передавайте курсор без изменений, сохраняя сервер, имена и их порядок, рейтинг и период. Границы периода и обе сводки сохраняются. Если курсор недействителен или истёк, откройте первую страницу заново.
Изменение настроек, размера топа или состава сохранённых наблюдений может потребовать начать с первой страницы. Ограничение топа действует и на старые наблюдения. Период с более чем 25 000 наблюдений необходимо сократить.