Codeforces.API

Documentation

module Codeforces.Types

data ResponseError

An error that could occur during the retrieval and inital parsing of data from the Codeforces API.

Constructors

ApiFail String

Corresponds to a ResponseFail from the Codeforces API with the fail comment.

JsonError JSONException

Wrapper around JSONException, used if the successful JSON response could not be parsed.

HttpError HttpException

Wrapper around HttpException, used for situations like a failed connection.

Instances

Show ResponseError

Defined in Codeforces.Response

Methods

showsPrec :: Int -> ResponseError -> ShowS

show :: ResponseError -> String

showList :: [ResponseError] -> ShowS

handleAPI :: IO (Either ResponseError a) -> ExceptT CodeforcesError IO a

Contests

getContests :: Bool -> IO (Either ResponseError [Contest])

getContests isGym returns a list of contests that may or may not be gym contests.

getContestStandings :: StandingsParams -> IO (Either ResponseError Standings)

getContestStandings standingsParams returns information about the contest and a part of the standings list.

getContestStandings' :: StandingsParams -> IO (Either ResponseError (Standings, Map Handle RatingChange))

Like getContestStandings but returns the standings and the RatingChanges for each user participating.

data StandingsParams

Query parameters for retrieving contest standings.

Constructors

StandingsParams

Fields

• paramContestId :: ContestId

  ID of the contest

• paramFrom :: Maybe Int

  The starting index of the ranklist (1-based)

• paramRowCount :: Maybe Int

  The number of standing rows to return

• paramRoom :: Maybe Int

  If specified, only standings of this room are returned

• paramUnofficial :: Bool

  If true, all participations are included. Otherwise only Contestant participations are included.

• paramHandles :: Maybe [Handle]

  If specified, the standings includes only these users.

Instances

Show StandingsParams

Defined in Codeforces.API

Methods

showsPrec :: Int -> StandingsParams -> ShowS

show :: StandingsParams -> String

showList :: [StandingsParams] -> ShowS

Problems

getAllProblemData :: [ProblemTag] -> IO (Either ResponseError ProblemsResponse)

getAllProblemData tags returns a ProblemsResponse filtered by the tags, if supplied.

getProblems :: [ProblemTag] -> IO (Either ResponseError [Problem])

getProblems tags returns a list of Problems containing the tags, if provided.

getProblemStats :: [ProblemTag] -> IO (Either ResponseError [ProblemStats])

Like getProblems but returns a list of ProblemStats.

getContestProblems :: ContestId -> IO (Either ResponseError [Problem])

getContestProblems contestId returns the list of problems for the given contest.

This should be used instead of filtering results from getProblems for two main reasons:

1. problemContestId can only refer to one contest, so problems appearing in multiple contests may not be filtered correctly.
2. getProblems returns larger output potentially affecting performance

Ratings and ranks

getContestRatingChanges :: ContestId -> IO (Either ResponseError [RatingChange])

getContestRatingChanges contestId returns a list of RatingChanges for the contest.

getUserRatingHistory :: Handle -> IO (Either ResponseError [RatingChange])

getUserRatingHistory handle returns a list of RatingChanges for the requested user

Problem submissions

getContestSubmissions :: ContestId -> Handle -> IO (Either ResponseError [Submission])

getContestSubmissions contestId handle returns the submissions made by the user in the contest given by contestId

getUserStatus :: Handle -> Int -> Int -> IO (Either ResponseError [Submission])

getUserStatus handle from count returns the count most recent submissions by the user, starting from the from-th one.

User details

getUser :: Handle -> IO (Either ResponseError User)

getUser handle returns the User with the given handle

getUsers :: [Handle] -> IO (Either ResponseError [User])

getUsers handles returns a list of Users with the given handles

getFriends :: UserConfig -> IO (Either ResponseError [Handle])

Virtual rating calculation

calculateVirtualResult :: ContestId -> Handle -> Points -> Int -> IO (Either ResponseError (User, Maybe VirtualResult))

calculateVirtualResult contestId handle points penalty computes the rating change the user would gain had they competed in the contest live, and their expected ranking for the contest.

type Delta = Int

Difference in rating between a user's current rating, and their rating following this contest.

type Seed = Float

The seed is the expected ranking for each participant before the contest begins.

A contestant's rating increases should they perform better than their seed, and decreases should they perform worse.

data VirtualResult

A virtual participation result

Constructors

VirtualResult

Fields

• virtualRank :: Int
• virtualDelta :: Delta
• virtualSeed :: Seed

Instances

Show VirtualResult

Defined in Codeforces.Virtual.Types

Methods

showsPrec :: Int -> VirtualResult -> ShowS

show :: VirtualResult -> String

showList :: [VirtualResult] -> ShowS

Configuration options

data UserConfig

Represents the user's configuration settings.

The API key must first be generated on the Codeforces API page. An API key consists of two parameters: key and secret.

To use the API key in a request, some parameters need to be generated from this configuration.

Constructors

UserConfig

Fields

• cfgHandle :: Handle

  Codeforces handle of the user

• cfgKey :: Text

  First part of the API key

• cfgSecret :: Text

  Second part of the API key

Instances

Show UserConfig

Defined in Codeforces.Config

Methods

showsPrec :: Int -> UserConfig -> ShowS

show :: UserConfig -> String

showList :: [UserConfig] -> ShowS

ToJSON UserConfig

Defined in Codeforces.Config

Methods

toJSON :: UserConfig -> Value

toEncoding :: UserConfig -> Encoding

toJSONList :: [UserConfig] -> Value

toEncodingList :: [UserConfig] -> Encoding

FromJSON UserConfig

Defined in Codeforces.Config

Methods

parseJSON :: Value -> Parser UserConfig

parseJSONList :: Value -> Parser [UserConfig]