Введение

С помощью Codeforces API вы можете получить доступ к нашим данным в удобном машинно-читаемом формате JSON.

Для доступа к данным вы просто посылаете HTTP-запрос по адресу https://codeforces.me/api/{methodName}. Параметры запроса зависят от метода. Под описанием каждого метода можно увитель пример запроса.

Ответом на каждый запрос является JSON-объект с тремя возможными полями: status, comment и result.

  • Статус может быть "OK" или "FAILED".
  • Если status равен "FAILED", то поле comment содержит причину, по которой запрос не получилось выполнить. Если status равен "OK", то поле comment отсутствует.
  • Если status равен "OK", то поле result содержит результат запроса в формате JSON, который зависит от метода и для каждого метода описан отдельно. Если status равен "FAILED", то поле result отсутствует.

Запросы к API можно отправлять не чаще, чем 1 раз в две секунды. Если вы отправите больше запросов, то получите ответ со статусом "FAILED" и комментарием "Call limit exceeded".

Поля, зависящие от языка, будут возвращаться с использованием языка по умолчанию. Вы можете передать дополнительный параметр lang с значениями en и ru для того, чтобы явно указать язык результата.

Aвторизация

Ко всем методам можно обращаться анонимно. Таким образом только публичные данные будут доступны через API. Для того, чтобы получить данные, приватные для пользователя (например, взломы во время соревнования), необходимо сгенерировать ключ API на странице https://codeforces.me/settings/api. Каждый ключ API имеет два параметра: key and secret. Для того, чтобы воспользоваться ключом необходимо передать следующие дополнительные параметры у запроса:

  1. apiKey — должен быть равен key
  2. time — текущее время в формате unix (например, System.currentTimeMillis()/1000). Если разница между временем на сервере и временем в параметре будет больше 5 минут, то запрос не будет выполнен.
  3. apiSig — подпись для того, чтобы убедиться, что вы знаете и key, и secret. Первые 6 символов параметра apiSig могут быть произвольными. Мы советуем выбирать их случайно при каждом запросе. Обозначим их как rand. Остальное содержимое параметра — это шестнадцатеричное представление хэш-кода SHA-512 от следующей строки: <rand>/<methodName>?param_1=value_1&param_2=value_2...&param_n=value_n#<secret> где (param_1, value_1), (param_2, value_2),..., (param_n, value_n) — это все параметра запроса (включая apiKey и time, но исключая apiSig) с соответствующими значениями отсортированные лексикографически в первую очередь по param_i, во вторую очередь по value_i.

Например:

Если ваш key равен xxx, secret равен yyy, выбранный rand равен 123456, и вы хотите отправить запрос методу contest.hacks для соревнования 566, то вам надо составить запрос следующим образом: https://codeforces.me/api/contest.hacks?contestId=566&apiKey=xxx&time=1732258189&apiSig=123456<hash>, где <hash> равен sha512Hex(123456/contest.hacks?apiKey=xxx&contestId=566&time=1732258189#yyy)

JSONP

Возможно запросить ответ в виде JSONP. Добавьте пареметр jsonp к вашему запросу и результат будет возвращен в виде вызова функции JavaScript.

Например, если параметр jsonp равен parseResponse, и метод вернул объект {"status":"OK","response":"..."}, то финальные результат равен parseResponse({"status":"OK","response":"..."});.