Справочник API
API переписи только на чтение. Всё ниже — это GET, и ключ читает ровно то же, что читает вошедший человек, не больше.
Аутентификация
Отправляйте ключ в любом из двух заголовков. Ничто другое запрос не аутентифицирует, а ключ, отправленный на маршрут, которого здесь нет, отклоняется, а не обслуживается.
X-Api-Key: wos_YOUR_KEY
Либо как токен-предъявитель
Authorization: Bearer wos_YOUR_KEY
Быстрый старт
Замените ключ на свой.
curl -H "X-Api-Key: wos_YOUR_KEY" \ "https://api.wosatlas.com/v1/players/search?playerName=LordFrost"
Конечные точки
| Метод | Путь | Что возвращает | Считается как |
|---|---|---|---|
| GET | /v1/alliances/{aid}/members | Получить Альянс и его состав | Запрос |
| GET | /v1/alliances/leaderboard | Ранжировать Альянсы по суммарной Силе | Запрос |
| GET | /v1/alliances/recruiting | Перечислить Альянсы, принимающие заявки | Запрос |
| GET | /v1/alliances/search | Искать Альянсы по тегу или названию | Поиск |
| GET | /v1/players/{uid} | Получить Губернатора по внутреннему uid | Запрос |
| GET | /v1/players/search | Искать Губернаторов по имени или идентификатору | Поиск |
Тарифы и пределы
Текущие рабочие значения, а не закреплённое право. Они могут меняться.
Каждый предел действует на аккаунт. Лишние ключи не покупают лишнего бюджета.
Оба окна квоты СКОЛЬЗЯЩИЕ, а не календарные периоды: окно чтения смотрит на тридцать дней назад от текущего момента, окно поиска — на двадцать четыре часа. Квота и поиск считаются на АККАУНТ, а не на ключ: все ключи аккаунта черпают из одного бюджета.
Заголовки ответа
Обслуженный ответ несёт их все, и отказ по квоте тоже. Отказ по пику несёт только три заголовка с префиксом X-RateLimit, а запрос, отклонённый до учёта — 401 или 403 — не несёт ни одного.
| Заголовок | Значение |
|---|---|
| X-Quota-Limit | Норма чтений аккаунта на скользящее тридцатидневное окно. |
| X-Quota-Remaining | Сколько чтений осталось в этом окне. |
| X-Quota-Reset | Unix-секунды, когда самое старое чтение выпадет из окна. |
| X-Search-Limit | Норма поисков аккаунта на скользящее двадцатичетырёхчасовое окно. |
| X-Search-Remaining | Сколько поисков осталось в этом окне. |
| X-Search-Reset | Unix-секунды, когда самый старый поиск выпадет из окна. |
| X-RateLimit-Limit | Пиковая норма аккаунта на короткое окно. |
| X-RateLimit-Remaining | Сколько запросов осталось в пиковом окне. |
| X-RateLimit-Reset | Unix-секунды, когда пиковое окно прокручивается. |
| Retry-After | Сколько секунд подождать перед повтором. Отправляется при каждом 429 и относится к тому окну, которое отказало. |
Когда вам отказывают
Кодом 429 отвечают три разные вещи, и они не взаимозаменяемы.
| Код ошибки | Что произошло |
|---|---|
| QUOTA_EXCEEDED | Скользящая тридцатидневная квота чтения аккаунта израсходована. `X-Quota-Remaining` показывает ноль; `X-Search-Remaining` остаётся честным. |
| SEARCH_QUOTA_EXCEEDED | Скользящая двадцатичетырёхчасовая квота поиска аккаунта израсходована. `X-Search-Remaining` показывает ноль; `X-Quota-Remaining` остаётся честным. В неё засчитываются только два поисковых маршрута. |
| RATE_LIMIT_EXCEEDED | Короткое пиковое окно аккаунта заполнено. `X-RateLimit-Remaining` показывает ноль. Это потолок секундного масштаба, который освобождается сам; ни одно окно квоты не затронуто. |
Коды ошибок
| Код | Статус | Значение |
|---|---|---|
| INVALID_API_KEY | 401 | Ключ неизвестен, отозван, либо владеющий им аккаунт удалён. |
| ENDPOINT_NOT_ALLOWED | 403 | Маршрут не входит в поверхность для разработчиков. Ключ, предъявленный на маршруте вне этой поверхности, отклоняется, а не обслуживается, поэтому не отправляйте ключ на конечные точки, которых нет в этом документе. |
| QUOTA_EXCEEDED | 429 | Скользящая тридцатидневная квота чтения аккаунта израсходована. `X-Quota-Remaining` показывает ноль; `X-Search-Remaining` остаётся честным. |
| SEARCH_QUOTA_EXCEEDED | 429 | Скользящая двадцатичетырёхчасовая квота поиска аккаунта израсходована. `X-Search-Remaining` показывает ноль; `X-Quota-Remaining` остаётся честным. В неё засчитываются только два поисковых маршрута. |
| RATE_LIMIT_EXCEEDED | 429 | Короткое пиковое окно аккаунта заполнено. `X-RateLimit-Remaining` показывает ноль. Это потолок секундного масштаба, который освобождается сам; ни одно окно квоты не затронуто. |
Машиночитаемая спецификация
Документ OpenAPI ниже порождается работающим сервером и является тем же самым, который отображает эта страница.