Package com.github.rami_sabbagh.codeforces.api

Class CodeforcesClient

java.lang.Object
com.github.rami_sabbagh.codeforces.api.CodeforcesClient
public class CodeforcesClient
extends Object
A Codeforces API client.

A CodeforcesClient can be used to send API requests and retrieve their responses. There are 2 ways to create a Client, with by creating a one with default configuration using .newCodeforcesClient() Or by using .newBuilder(), changing the configuration and .build().

With Codeforces API you can get access to some of their data as objects. Each request call is an HTTP request to their API and thus requires an internet connection.

The requests my fail to connections issues, or due to invalid arguments or such.

The connection issues would result in an IOException, while API failures would result in a CFException.

API may be requested at most 5 times in one second. If you send more requests, the requests will throw a CFException with "Call limit exceeded" comment.

Simple Example 

    CodeforcesClient client = CodeforcesClient.newCodeforcesClient()
    User[] user = client.requestUsersInformation("my_username");
    System.out.println(user.toStringPretty());

Authorization Example 

    Codeforces client = CodeforcesClient.newBuilder()
                                        .authorization("api_key","api_secret")
                                        .build();
    String[] friends = client.requestUserFriends("my_username");
    System.out.println("Friends:");
    for (String friend : friends)
        System.out.println("- " + friend);
Version:
1.0.0
Author:
Rami Sabbagh (@Rami-Sabbagh)

  • Field Details

  • Method Details

    • newCodeforcesClient

      public static CodeforcesClient newCodeforcesClient()
      Returns a new CodeforcesClient with default settings.

      Equivalent to newBuilder.build();

      The default settings include: no authorization, no timeout and default proxy selector.

      Returns:
      a new CodeforcesClient.

    • newBuilder

      public static CodeforcesClient.Builder newBuilder()
      Create a new CodeforcesClient builder.
      Returns:
      a CodeforcesClient.Builder.

    • requestBlogEntryComments

      public Comment[] requestBlogEntryComments​(int blogEntryId) throws InterruptedException, CFException, IOException
      Returns a list of comments to the specified blog entry.
      Parameters:
      blogEntryId - Id of the blog entry. It can be seen in blog entry URL. For example: /blog/entry/79
      Returns:
      A list of Comment objects.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestBlogEntry

      public BlogEntry requestBlogEntry​(int blogEntryId) throws InterruptedException, CFException, IOException
      Returns blog entry.
      Parameters:
      blogEntryId - Id of the blog entry. It can be seen in blog entry URL. For example: /blog/entry/79
      Returns:
      A BlogEntry object in full version.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestContestHacks

      public Hack[] requestContestHacks​(int contestId) throws InterruptedException, CFException, IOException
      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 user can see only own hacks.
      Parameters:
      contestId - Id of the contest. It is not the round number. It can be seen in contest URL. For example: /contest/566/status
      Returns:
      A list of Hack objects.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestContestsList

      public Contest[] requestContestsList​(Boolean gym) throws InterruptedException, CFException, IOException
      Returns information about all available contests.
      Parameters:
      gym - If true then gym contests are returned. Otherwise, regular contests are returned.
      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.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestContestRatingChanges

      public RatingChange[] requestContestRatingChanges​(int contestId) throws InterruptedException, CFException, IOException
      Returns rating changes after the contest.
      Parameters:
      contestId - Id of the contest. It is not the round number. It can be seen in contest URL. For example: /contest/566/status
      Returns:
      A list of RatingChange objects.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestContestStandings

      public ContestStandings requestContestStandings​(int contestId, Integer from, Integer count, String handles, Integer room, Boolean showUnofficial) throws InterruptedException, CFException, IOException
      Returns the description of the contest and the requested part of the standings.
      Parameters:
      contestId - Id of the contest. It is not the round number. It can be seen in contest URL. For example: /contest/566/status
      from - (optional) (can be null) 1-based index of the standings row to start the ranklist.
      count - (optional) (can be null) Number of standing rows to return.
      handles - (optional) (can be null) Semicolon-separated list of handles. No more than 10000 handles is accepted.
      room - (optional) (can be null) If specified, than only participants from this room will be shown in the result. If not — all the participants will be shown.
      showUnofficial - (optional) (can be null) If true than all participants (virtual, out of competition) are shown. Otherwise, only official contestants are shown.
      Returns:
      The contest standings.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestContestStatus

      public Submission[] requestContestStatus​(int contestId, String handle, Integer from, Integer count) throws InterruptedException, CFException, IOException
      Returns submissions for specified contest. Optionally can return submissions of specified user.
      Parameters:
      contestId - Id of the contest. It is not the round number. It can be seen in contest URL. For example: /contest/566/status
      handle - (optional) (can be null) Codeforces user handle.
      from - (optional) (can be null) 1-based index of the first submission to return.
      count - (optional) (can be null) Number of returned submissions.
      Returns:
      A list of Submission objects, sorted in decreasing order of submission id.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestProblemSet

      public ProblemSet requestProblemSet​(String tags, String problemsetName) throws InterruptedException, CFException, IOException
      Returns all problems from problemset. Problems can be filtered by tags.
      Parameters:
      tags - (optional) (can be null) Semicolon-separated list of tags.
      problemsetName - (optional) (can be null) Custom problemset's short name, like 'acmsguru'
      Returns:
      The ProblemSet.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestProblemSetRecentStatus

      public Submission[] requestProblemSetRecentStatus​(int count, String problemsetName) throws InterruptedException, CFException, IOException
      Returns recent submissions.
      Parameters:
      count - Number of submissions to return. Can be up to 1000.
      problemsetName - (optional) (can be null) Custom problemset's short name, like 'acmsguru'
      Returns:
      A list of Submission objects, sorted in decreasing order of submission id.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestRecentActions

      public RecentAction[] requestRecentActions​(int maxCount) throws InterruptedException, CFException, IOException
      Returns recent actions.
      Parameters:
      maxCount - Number of recent actions to return. Can be up to 100.
      Returns:
      A list of RecentAction objects.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestUserBlogEntries

      public BlogEntry[] requestUserBlogEntries​(String handle) throws InterruptedException, CFException, IOException
      Returns a list of all user's blog entries.
      Parameters:
      handle - Codeforces user handle.
      Returns:
      A list of BlogEntry objects in short form.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestUserFriends

      public String[] requestUserFriends​(Boolean onlyOnline) throws InterruptedException, CFException, IOException
      Returns authorized user's friends. Using this method requires authorization.
      Parameters:
      onlyOnline - If true only online friends are returned. Otherwise, all friends are returned.
      Returns:
      Returns a list of strings — users' handles.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestUsersInformation

      public User[] requestUsersInformation​(String handles) throws InterruptedException, CFException, IOException
      Returns information about one or several users.
      Parameters:
      handles - Semicolon-separated list of handles. No more than 10000 handles is accepted.
      Returns:
      A list of User objects for requested handles.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestRatedUsersList

      public User[] requestRatedUsersList​(Boolean activeOnly) throws InterruptedException, CFException, IOException
      Returns the list users who have participated in at least one rated contest.
      Parameters:
      activeOnly - If true then only users, who participated in rated contest during the last month are returned. Otherwise, all users with at least one rated contest are returned.
      Returns:
      A list of User objects, sorted in decreasing order of rating.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestUserRating

      public RatingChange[] requestUserRating​(String handle) throws InterruptedException, CFException, IOException
      Returns rating history of the specified user.
      Parameters:
      handle - Codeforces user handle.
      Returns:
      A list of RatingChange objects for requested user.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.

    • requestUserStatus

      public Submission[] requestUserStatus​(String handle, Integer from, Integer count) throws InterruptedException, CFException, IOException
      Returns submissions of specified user.
      Parameters:
      handle - Codeforces user handle.
      from - (optional) (can be null) 1-based index of the first submission to return.
      count - (optional) (can be null) Number of returned submissions.
      Returns:
      A list of Submission objects, sorted in decreasing order of submission id.
      Throws:
      InterruptedException - When the thread is interrupted during the request.
      CFException - When the Codeforces API responses with a failure.
      IOException - When the HTTP API connection fails.