[Гайд] API VimeWorld

Опубликовано: 29 декабря 20205 г

Что такое API?

API - переводится как программный интерфейс приложения, что в свою очередь обозначает интерфейс, с которым может взаимодействовать ваше приложение, чтобы получить какие-либо данные с этого веб-ресурса. Ответ АПИ возвращается в виде JSON, а поэтому его легко использовать.

Подключение

Для работы с API VimeWorld нужно отправить запрос на один из этих адресов:

https://api.vimeworld.ru/

https://api.vime.world/ (Из-за бана РКН может не работать)

В конце адреса нужно добавить имя метода, а также данные (например ID игрока/гильдии). По умолчанию без использования токена разработчика вы можете совершать 60 запросов минуту с одного IP. С использованием токена же (получить можно на сервере MiniGames при помощи команды /api dev) значение увеличивается до 300, но если вам и этого мало, то можете написать Дмитрию Манчинскому (@xtrafrancyz) в телеграмме или на почту.

Пример правильных запросов:

PHP cURL:

$ch = curl_init("https://api.vimeworld.ru/online");
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 4);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Access-Token: MY_TOKEN'
));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

print("Онлайн VimeWorld: {$response->total}");

NodeJS axios:

const axios = require('axios');
var response = ""
axios.get('https://api.vimeworld.ru/online', {
    params: {
      token: "MY_TOKEN"
    }
})
.then(function (response) {
    console.log(`Онлайн VimeWorld: ${response.data.total}`)
})

Python requests:

import requests

response = requests.get(
    'https://api.vimeworld.ru/online',
    params={'token': 'MY_TOKEN'},
).json()

print(f"Онлайн на VimeWorld: {response['total']}")

Возможные ошибки

Разумеется, при подключении что может пойти не так. Поэтому, главная администрация сделала ошибкам специальные коды для ошибок:

-3: Неизвестная ошибка в работе API, при её возникновении нужно сообщить куда-нибудь

-2: Внутренняя ошибка сервера. О ней тоже нужно куда-нибудь сообщить

-1: Отсутствие метода, к которому вы обращались

1: Неверный токен разработчика. Новый можно получить с помощью команды /api dev

2: Количество запросов исчерпано

3: Один из основных параметров не передан/указан неверно

4: Метод отключен, или не работает по каким-то другим причинам

Ошибки с кодом 10+ указывают на отсутствие запрошенного ресурса. Например: игрока, матча, гильдии.

Полезная информация

Ранги:

Ранг - Название - Префикс - Цвет

VIP - VIP - [V] - #00be00

PREMIUM - Premium - [P] - #00dada

HOLY - Holy - [H] - #ffba2d

IMMORTAL - Immortal - - #e800d5

BUILDER - Билдер - [Билдер] - #009c00

MAPLEAD - Главный билдер - [Гл. Билдер] - #009c00

YOUTUBE - YouTube - [YouTube] - #fe3f3f

ORGANIZER - Организатор - [Организатор] - #00bebe

MODER - Модератор - [Модер] - #1b00ff

WARDED - Проверенный модератор - [Пр. Модер] - #1b00ff

CHIEF - Главный модератор - [Гл. Модер] - #1b00ff

ADMIN - Главный админ - [Гл. Админ] - #00bebe

Цвета из майнкрафта в HTML:

Код цвета - цвет (и цвет в HTML)

&0 - черный (#000000)

&2 - тёмно-зелёный (#009c00)

&3 - бирюзовый (#00bebe)

&4 - бордовый (#aa0000)

&5 - фиолетовый (#aa00aa)

&6 - оранжевый (#ffba2d)

&7 - серый (#aaaaaa)

&8 - темно-серый (#555555)

&9 - синий (#1b00ff)

&a - салатовый (#00be00)

&b - голубой (#00dada)

&c - красный (#fe3f3f)

&d - розовый (#e800d5)

&e - желтый (#ffff55)

&f - белый (#ffffff)

Всего на VimeWorld существует 3 вида токенов:

DEV - используется для выполнения запросов к апи с увеличенным лимитом запросов. Можно получить по команде /api dev на сервере MiniGames.

AUTH - используется для авторизации игрока на вашем сайте или в любом другом месте. Токен действует в течение часа до первого использования. Можно получить по команде /api auth на сервере MiniGames.

LEGACY - Имеет свойства и DEV и AUTH, его можно было получить до 4-го марта 2018 года

В зависимости от отправленного токена, могут появиться/исчезнуть некоторые поля.

Ссылка на метод: https://api.vimeworld.ru/misc/token/xxx

Пример ответа:

Существующий токен:


{
  "token": "xxx",
  "valid": true,
  "type": "LEGACY",
  "limit": 300,
  "owner": {
    "id": 2113516,
    "username": "ItzRubick",
    "level": 31,
    "levelPercentage": 0.58894,
    "rank": "PLAYER",
    "playedSeconds": 3345895,
    "guild": {
      "id": 5161,
      "name": "Neon",
      "tag": null,
      "color": "&f",
      "level": 6,
      "levelPercentage": 0.97677
    }
  }
}

Несуществующий:


{
  "token": "notExists",
  "valid": false
}

Методы

Связанные с игроками

/user/name/:names^get

Просмотр информации по типу уровня, ранга, гильдии по никнейму

Параметры:

name* - Ник игрока, или ники игроков через запятую. Они могут содержать только латинские буквы, цифры и знак подчеркивания _.

Дополнительная информация:

Максимальное количество никнеймов в запросе - 50

/user/:ids^get

Аналогичен предыдущему методу, но только получение с помощью ID

/user/:id/friends^get

Список друзей любого игрока

Параметры:

id* - ID игрока

/user/:id/session^get

Получение онлайн статуса игрока

Параметры:

id* - ID игрока

/user/:id/stats^get

Получение статистики игрока

Параметры:

id* - ID игрока

games - Выводит только статистику указанных игр. Если не нужна полная статистика игрока, то укажите только нужные игры (по ID)

Дополнительная информация:

В ответе у любой игры будет статистика за всё время (global) и сезон (season).

/user/:id/achievements^get

Получение достижений игрока

Параметры:

id* - ID игрока

Дополнительная информация:

time в ответе содержит метку времени Unix Timestamp, когда игрок получил достижение.

/user/:id/leaderboards^get

Получение мест игрока в топах

Параметры:

id* - ID игрока

/user/:id/matches^get

Получение последних матчей игрока

Параметры:

id* - ID игрока

count - количество возвращаемых записей. По умолчанию - 20, максимум - 50

offset - количество пропущенных записей. По умолчанию - 0, максимум - 2000

Дополнительная информация:

В matches->state имеется 3 статуса: 0 - поражение, 1 - победа, 2 - ничья.

/user/session/:ids^get

Массовое получение статуса

Параметры:

ids* - ID игрока/игроков

Дополнительная информация:

Максимальное количество ID в запросе - 50

/user/session^post

Супер массовое получение статуса

Параметры:

ids* - ID игрока/игроков

Дополнительная информация:

Максимальное количество ID в запросе - 1000

Связанные с гильдиями

/guild/search^get

Поиск гильдии по тегу или названию

Параметры:

query* - запрос для поиска (2+ символов)

Дополнительная информация:

Индекс гильдий обновляется раз в 10 минут.

/guild/get^get

Получение информации о гильдии

Параметры:

id / name / tag* - получение гильдии по ID/имени/тегу

unsafe - отключение проксирования картинок

Связанные с топами

/leaderboard/list^get

Список всех возможных рекордов

Параметры:

отсутствуют

Дополнительная информация:

type - тип таблицы рекордов, он используется для получения конкретной таблицы рекордов в методе leaderboard/get.

description - краткое описание таблицы рекордов.

sort - список доступных вариантов таблицы рекордов.

/leaderboard/get/:type[/:sort]^get

Получение таблицы рекордов

Параметры:

type* - Тип таблицы рекордов

sort - Вариант таблицы рекордов

size - количество возвращаемых записей. По умолчанию - 100, максимум - 1000

offset - количество пропущенных записей. По умолчанию - 0, максимум - 2000

Дополнительная информация:

Обновление информации происходит раз в час

Связанные с онлайном

/online^get

Количество игроков онлайн

Параметры:

отсутствуют

Дополнительная информация:

Список всех полных названий игр можно посмотреть с помощью метода misc/games.

/online/streams^get

Список стримов, проходящих на сервере

Параметры:

отсутствуют

Дополнительная информация:

title - Заголовок стрима. Может содержать символы юникода.

owner - Ник ютубера, который добавил (ведет) стрим.

viewers - Количество зрителей стрима.

duration - Длительность стрима в секундах (время с начала стрима).

platform - Платформа, на которой идет стрим. Поддерживается YouTube, ВКонтакте, Twitch, GoodGame.

/online/staff^get

Список модераторов, находящихся на сервере

Параметры:

отсутствуют

Дополнительная информация:

Информация обновляется раз в 10 сек.

Связанные с матчами

/match/:id^get

Информация о матче

Параметры:

id - айди матча

Дополнительная информация:

В зависимости от игры, в ответе могут содержаться совершенно разные значения, так как в каждой игре считается разная статистика и используются разные дополнительные “характеристики”. Так, на Дуэлях присутствуют поля ranked и kit, а на BedWars у каждого игрока есть количество сломанных им кроватей - brokenBeds.

Есть и общие для всех игр поля: version, game, server, start, end, mapName (может быть пустым), mapId (может быть пустым).

Объект в поле winner может изменяться в зависимости от вида игры, а может быть null в случае ничьи:

winner: {
"team": "teamId" // в случае командной игры
"player": 123 // в случае игры без команд и одним победителем
"players": [123, 456] // в случае игры без команд и с несколькими победителями
}

Список игроков players всегда содержит в себе всех играющих и каждый из игроков обязательно имеет свой id, остальные поля могут меняться в зависимости от игры.

Список команд teams присутствует только в командных играх и обязательно имеет id и members (id игроков в команде).

Список событий events содержит в себе список некоторых внутриигровых событий. Каждое событие обязательно имеет type и time (время в секундах относительно начала игры). Типы событий в разных играх могут отличаться, плюс к тому одно и то же событие в разных играх может содержать разные поля, но это больше исключение, чем правило.

/match/latest^get

Последние матчи на сервере

Параметры:

count - Количество последних матчей, которые вернет сервер. По умолчанию - 20, максимально - 100.

Дополнительная информация:

Список обновляется раз в 10 секунд.

/match/list^get

Список матчей на сервере

Параметры:

before - будут выведены все матчи, которые произошли до матча с этим ID.

after - будут выведены все матчи, которые произошли после матча с этим ID.

count - количество матчей, которые вернет сервер. По умолчанию - 20, максимально - 100.

Дополнительная информация:

При выполнении запроса, обязательно нужно указать или before, или after, иначе сервер вернет ошибку.

ID матча это не случайное число, а Snowflake ID (по мотивам Twitter и Discord, можете загуглить). Используя это знание, можно смотреть матчи, которые происходили в определенное время.

ID матча (64 бита) состоит из:

42 бита - время в миллисекундах, начиная от 01.01.2019 (1546300800 unix timestamp).
10 бит - внутренний ID генератора, не используется в данный момент.
12 бит - счетчик, сбрасывающийся каждую миллисекунду.

Таким образом, если нужно узнать самый первый матч 29.05.2019, то запрос будет следующим:

var vime_epoch = 1546300800; // 01.01.2019 в unix timestamp
var timestamp = 1559088000; // 29.05.2019 в unix timestamp
var id = ((timestamp - vime_epoch) * 1000) << 22 // 1000 - делаем миллисекунды из секунд
= 53633404108800000;
var url = "https://api.vimeworld.ru/match/list?count=1&after=" + id;

Изменено 30 августа 20215 г пользователем Charkos0ff
Исправления для IPS 4

Опубликовано: 29 декабря 20205 г

sorry, but so useless.......

Опубликовано: 29 декабря 20205 г

Так, ты же это вроде публиковал когда-то, не-а?

Опубликовано: 29 декабря 20205 г

Автор

Так, ты же это вроде публиковал когда-то, не-а?

Там был больше гайд по созданию ботов для вк, нежели чем апи.

Опубликовано: 5 мая 20215 г

29.12.2020 в 18:24, Charkos0ff сказал:
API - переводится как программный интерфейс приложения, что в свою очередь обозначает интерфейс, с которым может взаимодействовать ваше приложение, чтобы получить какие-либо данные с этого веб-ресурса. Ответ АПИ возвращается в виде JSON, а поэтому его легко использовать.

Для работы с API VimeWorld нужно отправить запрос на один из этих адресов:

https://api.vimeworld.ru/

https://api.vime.world/ (Из-за бана РКН может не работать)

В конце адреса нужно добавить имя метода, а также данные (например ID игрока/гильдии). По умолчанию без использования токена разработчика вы можете совершать 60 запросов минуту с одного IP. С использованием токена же (получить можно на сервере MiniGames при помощи команды /api dev) значение увеличивается до 300, но если вам и этого мало, то можете написать Дмитрию Манчинскому (@xtrafrancyz) в телеграмме или на почту.

Пример правильных запросов:

PHP cURL:
$ch = curl_init("https://api.vimeworld.ru/online");
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 4);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Access-Token: MY_TOKEN'
));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

print("Онлайн VimeWorld: {$response->total}"); 
NodeJS axios:
const axios = require('axios');
var response = ""
axios.get('https://api.vimeworld.ru/online', {
    params: {
      token: "MY_TOKEN"
    }
})
.then(function (response) {
    console.log(`Онлайн VimeWorld: ${response.data.total}`)
})
Python requests:
import requests

response = requests.get(
    'https://api.vimeworld.ru/online',
    params={'token': 'MY_TOKEN'},
).json()

print(f"Онлайн на VimeWorld: {response['total']}")
Разумеется, при подключении что может пойти не так. Поэтому, главная администрация сделала ошибкам специальные коды для ошибок:

-3: Неизвестная ошибка в работе API, при её возникновении нужно сообщить куда-нибудь

-2: Внутренняя ошибка сервера. О ней тоже нужно куда-нибудь сообщить

-1: Отсутствие метода, к которому вы обращались

1: Неверный токен разработчика. Новый можно получить с помощью команды /api dev

2: Количество запросов исчерпано

3: Один из основных параметров не передан/указан неверно

4: Метод отключен, или не работает по каким-то другим причинам

Ошибки с кодом 10+ указывают на отсутствие запрошенного ресурса. Например: игрока, матча, гильдии.

Ранги:

Ранг - Название - Префикс - Цвет

VIP - VIP - [V] - #00be00

PREMIUM - Premium - [P] - #00dada

HOLY - Holy - [H] - #ffba2d

IMMORTAL - Immortal - - #e800d5

BUILDER - Билдер - [Билдер] - #009c00

MAPLEAD - Главный билдер - [Гл. Билдер] - #009c00

YOUTUBE - YouTube - [YouTube] - #fe3f3f

ORGANIZER - Организатор - [Организатор] - #00bebe

MODER - Модератор - [Модер] - #1b00ff

WARDED - Проверенный модератор - [Пр. Модер] - #1b00ff

CHIEF - Главный модератор - [Гл. Модер] - #1b00ff

ADMIN - Главный админ - [Гл. Админ] - #00bebe

Цвета из майнкрафта в HTML:

Код цвета - цвет (и цвет в HTML)

&0 - черный (#000000)

&2 - тёмно-зелёный (#009c00)

&3 - бирюзовый (#00bebe)

&4 - бордовый (#aa0000)

&5 - фиолетовый (#aa00aa)

&6 - оранжевый (#ffba2d)

&7 - серый (#aaaaaa)

&8 - темно-серый (#555555)

&9 - синий (#1b00ff)

&a - салатовый (#00be00)

&b - голубой (#00dada)

&c - красный (#fe3f3f)

&d - розовый (#e800d5)

&e - желтый (#ffff55)

&f - белый (#ffffff)

Всего на VimeWorld существует 3 вида токенов:

DEV - используется для выполнения запросов к апи с увеличенным лимитом запросов. Можно получить по команде /api dev на сервере MiniGames.

AUTH - используется для авторизации игрока на вашем сайте или в любом другом месте. Токен действует в течение часа до первого использования. Можно получить по команде /api auth на сервере MiniGames.

LEGACY - Имеет свойства и DEV и AUTH, его можно было получить до 4-го марта 2018 года

В зависимости от отправленного токена, могут появиться/исчезнуть некоторые поля.

Ссылка на метод: https://api.vimeworld.ru/misc/token/xxx

Пример ответа:
Скрыть содержимое
Существующий токен:
{
  "token": "xxx",
  "valid": true,
  "type": "LEGACY",
  "limit": 300,
  "owner": {
    "id": 2113516,
    "username": "ItzRubick",
    "level": 31,
    "levelPercentage": 0.58894,
    "rank": "PLAYER",
    "playedSeconds": 3345895,
    "guild": {
      "id": 5161,
      "name": "Neon",
      "tag": null,
      "color": "&f",
      "level": 6,
      "levelPercentage": 0.97677
    }
  }
}  
Несуществующий:
{
  "token": "notExists",
  "valid": false
}  
Связанные с игроками

/user/name/:names^get

Просмотр информации по типу уровня, ранга, гильдии по никнейму

Параметры:

name* - Ник игрока, или ники игроков через запятую. Они могут содержать только латинские буквы, цифры и знак подчеркивания _.

Дополнительная информация:

Максимальное количество никнеймов в запросе - 50

/user/:ids^get

Аналогично предыдущему методу, но только получение с помощью ID

/user/:id/friends^get

Список друзей любого игрока

Параметры:

id* - ID игрока

/user/:id/session^get

Получение онлайн статуса игрока

Параметры:

id* - ID игрока

/user/:id/stats^get

Получение статистики игрока

Параметры:

id* - ID игрока

games - Выводит только статистику указанных игр. Если не нужна полная статистика игрока, то укажите только нужные игры (по ID)

Дополнительная информация:

В ответе у любой игры будет статистика за всё время (global) и сезон (season).

/user/:id/achievements^get

Получение достижений игрока

Параметры:

id* - ID игрока

Дополнительная информация:

time в ответе содержит метку времени Unix Timestamp, когда игрок получил достижение.

/user/:id/leaderboards^get

Получение мест игрока в топах

Параметры:

id* - ID игрока

/user/:id/matches^get

Получение последних матчей игрока

Параметры:

id* - ID игрока

count - количество возвращаемых записей. По умолчанию - 20, максимум - 50

offset - количество пропущенных записей. По умолчанию - 0, максимум - 2000

Дополнительная информация:

В matches->state имеется 3 статуса: 0 - поражение, 1 - победа, 2 - ничья.

/user/session/:ids^get

Массовое получение статуса

Параметры:

ids* - ID игрока/игроков

Дополнительная информация:

Максимальное количество ID в запросе - 50

/user/session^post

Супер массовое получение статуса

Параметры:

ids* - ID игрока/игроков

Дополнительная информация:

Максимальное количество ID в запросе - 1000

Связанные с гильдиями

/guild/search^get

Поиск гильдии по тегу или названию

Параметры:

query* - запрос для поиска (2+ символов)

Дополнительная информация:

Индекс гильдий обновляется раз в 10 минут.

/guild/get^get

Получение информации о гильдии

Параметры:

id / name / tag* - получение гильдии по ID/имени/тегу

unsafe - отключение проксирования картинок

Связанные с топами

/leaderboard/list^get

Список всех возможных рекордов

Параметры:

отсутствуют

Дополнительная информация:

type - тип таблицы рекордов, он используется для получения конкретной таблицы рекордов в методе leaderboard/get.

description - краткое описание таблицы рекордов.

sort - список доступных вариантов таблицы рекордов.

/leaderboard/get/:type[/:sort]^get

Получение таблицы рекордов

Параметры:

type* - Тип таблицы рекордов

sort - Вариант таблицы рекордов

size - количество возвращаемых записей. По умолчанию - 100, максимум - 1000

offset - количество пропущенных записей. По умолчанию - 0, максимум - 2000

Дополнительная информация:

Обновление информации происходит раз в час

Связанные с онлайном

/online^get

Количество игроков онлайн

Параметры:

отсутствуют

Дополнительная информация:

Список всех полных названий игр можно посмотреть с помощью метода misc/games.

/online/streams^get

Список стримов, проходящих на сервере

Параметры:

отсутствуют

Дополнительная информация:

title - Заголовок стрима. Может содержать символы юникода.

owner - Ник ютубера, который добавил (ведет) стрим.

viewers - Количество зрителей стрима.

duration - Длительность стрима в секундах (время с начала стрима).

platform - Платформа, на которой идет стрим. Поддерживается YouTube, ВКонтакте, Twitch, GoodGame.

/online/staff^get

Список модераторов, находящихся на сервере

Параметры:

отсутствуют

Дополнительная информация:

Информация обновляется раз в 10 сек.

Связанные с матчами

/match/:id^get

Информация о матче

Параметры:

отсутствуют

Дополнительная информация:
Показать содержимое
В зависимости от игры, в ответе могут содержаться совершенно разные значения, так как в каждой игре считается разная статистика и используются разные дополнительные “характеристики”. Так, на Дуэлях присутствуют поля ranked и kit, а на BedWars у каждого игрока есть количество сломанных им кроватей - brokenBeds.

Есть и общие для всех игр поля: version, game, server, start, end, mapName (может быть пустым), mapId (может быть пустым).

Объект в поле winner может изменяться в зависимости от вида игры, а может быть null в случае ничьи:
winner: {
"team": "teamId" // в случае командной игры
"player": 123 // в случае игры без команд и одним победителем
"players": [123, 456] // в случае игры без команд и с несколькими победителями
} 
Список игроков players всегда содержит в себе всех играющих и каждый из игроков обязательно имеет свой id, остальные поля могут меняться в зависимости от игры.

Список команд teams присутствует только в командных играх и обязательно имеет id и members (id игроков в команде).

Список событий events содержит в себе список некоторых внутриигровых событий. Каждое событие обязательно имеет type и time (время в секундах относительно начала игры). Типы событий в разных играх могут отличаться, плюс к тому одно и то же событие в разных играх может содержать разные поля, но это больше исключение, чем правило.
/match/latest^get

Последние матчи на сервере

Параметры:

count - Количество последних матчей, которые вернет сервер. По умолчанию - 20, максимально - 100.

Дополнительная информация:

Список обновляется раз в 10 секунд.

/match/list^get

Список матчей на сервере

Параметры:

before - будут выведены все матчи, которые произошли до матча с этим ID.

after - будут выведены все матчи, которые произошли после матча с этим ID.

count - количество матчей, которые вернет сервер. По умолчанию - 20, максимально - 100.

Дополнительная информация:
Показать содержимое

При выполнении запроса, обязательно нужно указать или before, или after, иначе сервер вернет ошибку.

ID матча это не случайное число, а Snowflake ID (по мотивам Twitter и Discord, можете загуглить). Используя это знание, можно смотреть матчи, которые происходили в определенное время.

ID матча (64 бита) состоит из:

42 бита - время в миллисекундах, начиная от 01.01.2019 (1546300800 unix timestamp).

10 бит - внутренний ID генератора, не используется в данный момент.

12 бит - счетчик, сбрасывающийся каждую миллисекунду.

Таким образом, если нужно узнать самый первый матч 29.05.2019, то запрос будет следующим:
var vime_epoch = 1546300800; // 01.01.2019 в unix timestamp
var timestamp = 1559088000; // 29.05.2019 в unix timestamp
var id = ((timestamp - vime_epoch) * 1000) << 22 // 1000 - делаем миллисекунды из секунд
= 53633404108800000;
var url = "https://api.vimeworld.ru/match/list?count=1&after=" + id;