API — различия между версиями

Материал из Энциклобогии
Перейти к: навигация, поиск
(изменения в API)
Строка 1: Строка 1:
Сервер Годвилля предоставляет программный доступ к большинству данных героя, который можно использовать для написания сторонних программ.
+
Сервер Годвилля предоставляет программный доступ к некоторым данных героя, который можно использовать для написания своих программ-следилок.
  
API доступен в двух форматах (JSON и XML):
+
API доступен в двух видах:
  
godville.net/gods/api/<username>.json
+
* '''Открытый''' (базовый набор сведений о герое, похожий на его персональную страницу):
или (менее предпочтительно)
 
godville.net/gods/api/<username>.xml
 
  
По умолчанию в нем доступен только базовый набор сведений о герое, примерно совпадающий с содержимым персональной страницы. Если за героем хочется наблюдать в реальном времени, то необходимо включить в профиле игры галочку "Оперативные данные в API", добавляющую десять с лишним часто меняющихся полей наподобие инвентаря. При этом нужно учитывать, что любой желающий тоже сможет подглядывать за личной жизнью вашего героя.
+
godville.net/gods/api/<godname>.json
  
Данные обновляются раз в минуту, поэтому дергать сервер чаще смысла нет. При слишком частых запросах (существует ограничение “не больше 30 запросов за 10 минут в связке (бог+ip)”) данные героя перестают возвращаться, выводя соответствующее уведомление.
+
* '''Приватный''' (оперативный набор данных героя, известных только хозяину; работает с 15.03.2017):
  
{| class="wikitable collapsible collapsed"  
+
godville.net/gods/api/<godname>/<token>
 +
 
 +
Для доступа ко второму API хозяину героя нужно получить ключ (token) в [https://godville.net/user/profile профиле] игры. Изредка ключ может сбрасываться (в этом случае приватный API превратится в открытый) - разработчикам стоит предвидеть такую ситуацию и предлагать пользователю сходить в профиль за новым.
 +
 
 +
Общие моменты:
 +
 
 +
* Данные обновляются '''раз в минуту''', поэтому дергать сервер чаще смысла нет. При слишком частых запросах данные героя перестают возвращаться, выводя соответствующее уведомление.
 +
* Массовое или частое сканирование страниц игры (в том числе API различных героев) запрещено правилами игры и может привести к блокировкам.
 +
 
 +
{| class="wikitable collapsible sortable"  
 
|-
 
|-
!colspan="4" align="left" |Список ключей JSON<ref>Список неофициальный, а значит может быть неполным или ошибочным. Уточнения приветствуются.</ref>
+
!colspan="4" align="left" |Список ключей JSON<ref>Уточнения приветствуются.</ref>
 
|-
 
|-
!Ключ || Тип || Описание || Только с галочкой<br>"Оперативные данные"
+
!Ключ || Тип || Описание || Только с ключом?
 
|-
 
|-
|arena_fight || Bool || Находится ли герой на арене, в заплыве или под землёй. (см. fight_type) || Да
+
|''activatables'' || Объект || Массив с перечнем активируемых трофеев в инвентаре || '''Да'''
 
|-
 
|-
|ark_completed_at || Строка || Время окончания ковчега (Есть только у тех, кто достроил ковчег) || Нет
+
|''ark_f'' || Число || Число собранных тварей женского пола (только у ковчеговладельцев) || Нет
 +
|-
 +
|''ark_m'' || Число || Число собранных тварей мужского пола (только у ковчеговладельцев) || Нет
 +
|-
 +
|''savings'' || Строка || Примерное число сбережений (только у храмовладельцев) || Нет
 +
|-
 +
|''t_level'' || Число || Уровень героя-торгоца (только у лавочников) || Нет
 +
|-
 +
|''arena_won'' || Число || Счетчик побед на арене || Нет
 +
|-
 +
|''arena_lose'' || Число || Счетчик поражений на арене || Нет
 +
|-
 +
|<strike>inventory</strike> || Объект || Удален, вместо него теперь 'activatables' || '''Да'''
 +
|-
 +
|arena_fight || Bool || Находится ли герой на арене/в бою с боссом/в заплыве/ или в подземелье (см. fight_type) || '''Да'''
 +
|-
 +
|ark_completed_at || Строка || Дата постройки ковчега (есть только у тех, кто достроил ковчег) || Нет
 
|-
 
|-
 
|alignment || Строка || Характер героя || Нет
 
|alignment || Строка || Характер героя || Нет
 
|-
 
|-
|aura || Строка || Название ауры на герое, без времени(Если ауры нет, то ключа тоже нет) || Да
+
|aura || Строка || Аура героя (без времени; отсутствует без ауры) || '''Да'''
 
|-
 
|-
|bricks_cnt || Число || Количество кирпичей (не в процентах, показывается даже если храм окончен или ещё не начат) || Нет
+
|bricks_cnt || Число || Количество кирпичей (в штуках, не в процентах; есть всегда) || Нет
 
|-
 
|-
|clan || Строка || Название гильдии героя, пустая строка если её нет || Нет
+
|clan || Строка || Название гильдии героя (пустая строка, если её нет) || Нет
 
|-
 
|-
 
|clan_position || Строка || Звание в гильдии (если гильдии нет, то пустая строка) || Нет
 
|clan_position || Строка || Звание в гильдии (если гильдии нет, то пустая строка) || Нет
 
|-
 
|-
|diary_last || Строка || Последняя запись в дневнике || Да
+
|diary_last || Строка || Последняя запись в дневнике || '''Да'''
 
|-
 
|-
|distance || Число || Расстояние до столицы (при нахождении в любом городе 0)  || Да
+
|distance || Число || Расстояние до столицы (при нахождении в любом городе 0)  || '''Да'''
 
|-
 
|-
|exp_progress || Число || Количество опыта  || Да
+
|exp_progress || Число || Прогресс опыта  || '''Да'''
 
|-
 
|-
|expired || Bool || показатель неактуальности данных (ключ есть только если данные неактуальны)<ref>Для того, чтобы данные подавались в реальном времени, требуется периодическое (раз в час) посещение страницы героя, любая активность пользователя на ней или посещение героя одним из полноценных клиентов. Если ''expired = true'', то герой не посещался слишком давно и остальные данные уже не актуальны ''(знаем, что неудобно, но пока только так)''.</ref> || Да
+
|expired || Bool || показатель неактуальности данных (ключ появляется, когда данные неактуальны)<ref>Чтобы данные стали актуальными, требуется периодическое (раз в час) посещение страницы героя в браузере или одним из [[Клиент_для_Android|полноценных клиентов]]. Если ''expired = true'', то герой не посещался слишком давно и остальные данные уже не актуальны.</ref> || '''Да'''
 
|-
 
|-
|fight_type || Строка || Тип боя (sail - морской поход, arena - арена (ЗПГ в том числе), challenge - тренировка, dungeon - подземелье)  || Да
+
|fight_type || Строка || Тип боя (sail - морской поход, arena - арена (ЗПГ в том числе), challenge - тренировка, dungeon - подземелье)  || '''Да'''
 
|-
 
|-
|godpower || Число || Количество праны (для пенсионеров 0-200)  || Да
+
|godpower || Число || Количество праны (для пенсионеров 0-200)  || '''Да'''
 
|-
 
|-
|gold_approx || Строка || Приблизительное количество золота  || Нет
+
|gold_approx || Строка || Приблизительное количество золота  || '''Да'''
 
|-
 
|-
 
|gender || Строка || Пол героя  || Нет
 
|gender || Строка || Пол героя  || Нет
Строка 49: Строка 72:
 
|godname || Строка || Имя бога  || Нет
 
|godname || Строка || Имя бога  || Нет
 
|-
 
|-
|health || Число || Здоровье героя  || Да
+
|health || Число || Здоровье героя  || '''Да'''
 
|-
 
|-
 
|inventory_max_num || Число || Максимальный размер инвентаря || Нет
 
|inventory_max_num || Число || Максимальный размер инвентаря || Нет
 
|-
 
|-
|inventory_num || Число || Количество вещей в инвентаре || Да
+
|inventory_num || Число || Количество вещей в инвентаре || '''Да'''
|-
 
|inventory || Объект || Объект, содержащий список вещей в инвентаре (подробности ниже) || Да<ref>Формально, данный ключ есть всегда, но без галочки он всегда пустой</ref>
 
 
|-
 
|-
 
|level || Число || Уровень героя || Нет
 
|level || Число || Уровень героя || Нет
Строка 67: Строка 88:
 
|pet || Объект || Объект, содержащий описание питомца (подробности ниже) || Нет
 
|pet || Объект || Объект, содержащий описание питомца (подробности ниже) || Нет
 
|-
 
|-
|quest_progress || Число || % выполнения квеста || Да
+
|quest_progress || Число || Процент выполнения задания || '''Да'''
 
|-
 
|-
|quest || Строка || Квест || Да
+
|quest || Строка || Текст текущего задания || '''Да'''
 
|-
 
|-
 
|savings_completed_at || Строка || Дата окончания сбора пенсии (только у пенсионеров) || Нет
 
|savings_completed_at || Строка || Дата окончания сбора пенсии (только у пенсионеров) || Нет
Строка 75: Строка 96:
 
|temple_completed_at || Строка || Дата окончания храма (только у храмовладельцев) || Нет
 
|temple_completed_at || Строка || Дата окончания храма (только у храмовладельцев) || Нет
 
|-
 
|-
|town_name || Строка || Город, в котором герой (пустая строка, если в поле и нет ключа если в бою) || Да
+
|town_name || Строка || Город, в котором герой (пустая строка, если в поле, и нет ключа, если в бою) || '''Да'''
 
|-
 
|-
 
|wood_cnt || Число || Количество поленьев (пока нет храма, ключ отсутствует) || Нет
 
|wood_cnt || Число || Количество поленьев (пока нет храма, ключ отсутствует) || Нет
Строка 81: Строка 102:
 
|}
 
|}
  
{| class="wikitable collapsible collapsed"  
+
{| class="wikitable collapsible collapsed sortable"  
 
|-
 
|-
!colspan="3" align="left" |Состояние питомца
+
!colspan="3" align="left" |Объект pet (питомец)
 
|-
 
|-
 
!Ключ || Тип || Описание  
 
!Ключ || Тип || Описание  
 
|-
 
|-
|pet_class || Строка || Вид, к которому относится животное
+
|pet_class || Строка || Вид питомца
|-
 
|pet_level || Число || Уровень животного (пустая строка если питомец лишился уровня)
 
|-
 
|pet_name || Строка || Имя животного (Например, 'Пуха «Беспечный»')<ref>У контуженного питомца имя содержит "❌".</ref>
 
|-
 
|wounded || Bool || Контужен ли питомец (Есть только у контуженого)
 
|-
 
|}
 
 
 
{| class="wikitable collapsible collapsed"
 
|-
 
!colspan="3" align="left" |Описание предметов
 
|-
 
!Ключ || Тип || Описание
 
|-
 
|cnt || Число || Количество экземпляров данного предмета
 
|-
 
|pos || Число || Позиция в инвентаре
 
|-
 
|price || Число || "Цена" (0 для простых трофеев, 101 для жирных)
 
|-
 
|type || Строка || Тип (есть только у лечилок, всегда 'heal_potion')
 
 
|-
 
|-
|activate_by_user || Bool || Активируемый (Есть только у активируемых)
+
|pet_level || Число || Уровень питомца (пустая строка, если питомец лишился уровня)
 
|-
 
|-
|needs_godpower || Число || Стоимость активации (Есть только у активируемых)
+
|pet_name || Строка || Имя питомца (например, 'Пуха «Беспечный»; у контуженного питомца имя содержит "❌")</ref>
 
|-
 
|-
|description || Строка || Описание эффекта предмета (Есть только у активируемых)
+
|wounded || Bool || Флаг контузии питомеца (есть только у контуженого)
 
|-
 
|-
 
|}
 
|}
  
Кроме того, существует [[расширенное API]], позволяющее писать полноценные клиенты с возможностью влияния на героя.
 
 
===Примечания===
 
===Примечания===
 
<references />
 
<references />
  
 
[[Категория:Техническое]]
 
[[Категория:Техническое]]

Версия 10:38, 15 марта 2017

Сервер Годвилля предоставляет программный доступ к некоторым данных героя, который можно использовать для написания своих программ-следилок.

API доступен в двух видах:

  • Открытый (базовый набор сведений о герое, похожий на его персональную страницу):
godville.net/gods/api/<godname>.json 
  • Приватный (оперативный набор данных героя, известных только хозяину; работает с 15.03.2017):
godville.net/gods/api/<godname>/<token>

Для доступа ко второму API хозяину героя нужно получить ключ (token) в профиле игры. Изредка ключ может сбрасываться (в этом случае приватный API превратится в открытый) - разработчикам стоит предвидеть такую ситуацию и предлагать пользователю сходить в профиль за новым.

Общие моменты:

  • Данные обновляются раз в минуту, поэтому дергать сервер чаще смысла нет. При слишком частых запросах данные героя перестают возвращаться, выводя соответствующее уведомление.
  • Массовое или частое сканирование страниц игры (в том числе API различных героев) запрещено правилами игры и может привести к блокировкам.
Список ключей JSON[1]
Ключ Тип Описание Только с ключом?
activatables Объект Массив с перечнем активируемых трофеев в инвентаре Да
ark_f Число Число собранных тварей женского пола (только у ковчеговладельцев) Нет
ark_m Число Число собранных тварей мужского пола (только у ковчеговладельцев) Нет
savings Строка Примерное число сбережений (только у храмовладельцев) Нет
t_level Число Уровень героя-торгоца (только у лавочников) Нет
arena_won Число Счетчик побед на арене Нет
arena_lose Число Счетчик поражений на арене Нет
inventory Объект Удален, вместо него теперь 'activatables' Да
arena_fight Bool Находится ли герой на арене/в бою с боссом/в заплыве/ или в подземелье (см. fight_type) Да
ark_completed_at Строка Дата постройки ковчега (есть только у тех, кто достроил ковчег) Нет
alignment Строка Характер героя Нет
aura Строка Аура героя (без времени; отсутствует без ауры) Да
bricks_cnt Число Количество кирпичей (в штуках, не в процентах; есть всегда) Нет
clan Строка Название гильдии героя (пустая строка, если её нет) Нет
clan_position Строка Звание в гильдии (если гильдии нет, то пустая строка) Нет
diary_last Строка Последняя запись в дневнике Да
distance Число Расстояние до столицы (при нахождении в любом городе 0) Да
exp_progress Число Прогресс опыта Да
expired Bool показатель неактуальности данных (ключ появляется, когда данные неактуальны)[2] Да
fight_type Строка Тип боя (sail - морской поход, arena - арена (ЗПГ в том числе), challenge - тренировка, dungeon - подземелье) Да
godpower Число Количество праны (для пенсионеров 0-200) Да
gold_approx Строка Приблизительное количество золота Да
gender Строка Пол героя Нет
godname Строка Имя бога Нет
health Число Здоровье героя Да
inventory_max_num Число Максимальный размер инвентаря Нет
inventory_num Число Количество вещей в инвентаре Да
level Число Уровень героя Нет
max_health Число Максимальный запас здоровья Нет
motto Строка Девиз (может быть пустой строкой) Нет
name Строка Имя героя Нет
pet Объект Объект, содержащий описание питомца (подробности ниже) Нет
quest_progress Число Процент выполнения задания Да
quest Строка Текст текущего задания Да
savings_completed_at Строка Дата окончания сбора пенсии (только у пенсионеров) Нет
temple_completed_at Строка Дата окончания храма (только у храмовладельцев) Нет
town_name Строка Город, в котором герой (пустая строка, если в поле, и нет ключа, если в бою) Да
wood_cnt Число Количество поленьев (пока нет храма, ключ отсутствует) Нет

Примечания

  1. Уточнения приветствуются.
  2. Чтобы данные стали актуальными, требуется периодическое (раз в час) посещение страницы героя в браузере или одним из полноценных клиентов. Если expired = true, то герой не посещался слишком давно и остальные данные уже не актуальны.