Exploring the CodeForces API


In this article, we will explore the Codeforces API. With codeforces API, one can get access to limited data from in machine-readable JSON format.

What is API?

API stands for Application Programming Interface. An API is a set of routines, protocols, and tools for building software applications. It is a software piece that can be used by another piece of software to allow applications to talk to each other.

What is JSON?

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is based on a subset of the JavaScript Programming Language Standard ECMA-262 3rd Edition - December 1999.

JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.

Getting Started with CodeForces API

To access the data, we need to send an HTTP-request to address
https://codeforces.com/api/{methodName} with method-specific parameters.

Each method call returns a JSON-object with three possible fields.

  1. Status
    It is either "OK" or "FAILED”. It refers to the status of our request.

  2. Comment
    If the status is "FAILED" then comment contains the reason why our request failed. If the status is "OK", then there is no comment.

  3. Result
    If the status is "OK" then the result contains method-dependent JSON-element, which will be described for each method separately. If the status is "FAILED", then there is no result.

Note:
From the codeforces website, API may be requested at most five times in one second. If more than five requests are sent, we will receive a response with "FAILED" status and "Call limit exceeded" comment.

Methods and Return Objects

The various methods that can be used anonymously to gain publicly available data.

Methods for information relating to a user.

  1. user.info
    Returns the information about one or more than one user, such as name, ranking, title, et cetera.
    Required handles: Semicolon-separated list of handles. No more than 10000 handles are accepted.
    Example:
https://codeforces.com/api/user.info?handles=DmitriyH;Fefer_Ivan
  1. user.rating
    Returns the list of Rating Change objects for the requested user.
    Required handle: Codeforces handle of the user.
    Example
https://codeforces.com/api/user.rating?handle=Fefer_Ivan
  1. user.status
    Returns the submissions of a specified user.
    Required handle: Codeforces handle of the user.
    Parameters from and count can be added to specify the index of the first submission to return and the number of submissions to return, respectively.
    Example
https://codeforces.com/api/user.status?handle=Fefer_Ivan&from=1&count=10
  1. user.blogEntries
    Returns a list of all the blog entries by the specified user.
    Required handle: Codeforces handle of the user.
    Example
https://codeforces.com/api/user.blogEntries?handle=Fefer_Ivan

Methods for Information relating to contests

  1. contest.list
    Returns a list of Contest objects. If this method is called not anonymously, then all available contests for a calling user will be returned, too, including mashups and private gyms.
    Parameter gym can be added. If it is true, then gym contests are returned. Otherwise, regular contests are given.
    Example
https://codeforces.com/api/contest.list?gym=true
  1. contest.hacks
    Returns list of hacks in the specified contests. Full information about hacks is available only after some time after the contest end. During the contest, the user can see only their hacks.
    Required contestId: Id of the contest. It is not the round number. It can be seen in the contest URL.
    For example: /contest/566/status
    Example
https://codeforces.com/api/contest.hacks?contestId=566
  1. contest.list
    Returns information about all available contests.
    Parameter gym can be added. If true, then gym contests are returned. Otherwise, regular contests are returned.
    Example
https://codeforces.com/api/contest.list?gym=true
  1. contest.ratingChanges
    Returns rating changes after the contest.
    Required contestId: Id of the contest.
    Example
https://codeforces.com/api/contest.ratingChanges?contestId=566
  1. contest.status
    Returns submissions for the specified contest. Optionally can return submissions of the specified user.
    Required contestId: Id of the contest.
    Additionally, parameters handle (Codeforces user handle), from and count can be added.
    Example
https://codeforces.com/api/contest.status?contestId=566&from=1&count=10

Methods for Information relating to problem sets

  1. problemset.problems
    Returns all problems from the problem set. Problems can be filtered by tags.
    Parameters tags, and problemsetName that are a semicolon-separated list of tags and custom problem set’s short name respectively can be added.
    Example
https://codeforces.com/api/problemset.problems?tags=implementation
  1. problemset.recentStatus
    Returns a list of recent submissions, sorted in decreasing order of submission id.
    Required count :Number of submissions to return. Can be up to 1000.
    The parameter problemsetName can be added.
    Example
https://codeforces.com/api/problemset.recentStatus?count=10

Apart from these methods, a few other methods can be seen from Codeforces API Methods.

How to use Codeforces API?

Let us try an example program to get a JSON string about the information of a user.

We will be using json and urlib.request library of python to print the json string.

First, import the required libraries.

import json
import urllib.request

Second, create an empty string to store the JSON object.

user_data = ""

Next, manipulate the URL to get the required information.

user_URL = "https://codeforces.com/api/user.info?handles=" + "smeke"

Finally, load the JSON object.

with urllib.request.urlopen(user_URL) as url:
		user_data = json.loads(url.read().decode())

This code returns a JSON string with information about the username provided, in our case user as "user_data".

print(user_data)

It prints the following JSON string:

{
   "status":"OK",
   "result":[
      {
         "country":"Japan",
         "lastOnlineTimeSeconds":1597605124,
         "rating":2624,
         "friendOfCount":382,
         "titlePhoto":"//userpic.codeforces.com/6559/title/a27a2f085d4cfda2.jpg",
         "handle":"smeke",
         "avatar":"//userpic.codeforces.com/6559/avatar/f62d05abd1c0eb44.jpg",
         "contribution":77,
         "organization":"Ildar Gainullin fun-club",
         "rank":"international grandmaster",
         "maxRating":2624,
         "registrationTimeSeconds":1285050079,
         "maxRank":"international grandmaster"
      }
   ]
}

To get information about another user, we need to replace the username in the code file, in place of the given “smeke”.
For other kinds of information, we need to choose the appropriate method from the ones given above.

In this way, with this article at OpenGenus, you have learned methods to get information using Codeforces API. We hope this article helped you understand how Codeforces API works.