uHunt API
real-time statistics service

Mailing List

Please subscribe to uhunt-api mailing list to receive updates and discuss about the API.

How to use

You can call any of the service URL in the next sections directly from a client browser (it allows AJAX requests from any origin). It will return a JSON formatted results. Only the Live Events API uses long polling (i.e., it will wait for a while until new data arrives or it will return empty result if no new data arrives within 1 minute), the rest of the APIs returns immediately.

With uHunt API, you can re-create the entire uHunt website. See the uHunt component.

Change Log

Convert Username to UserID

URL : /api/uname2uid/{uname}.

The {uname} is the username to be converted. The service will return the user ID of that username.

Problem List

URL : /api/p.

Returns the list of problems at UVa in Javascript array format. Each problem is defined as an array of 21 values:

  1. Problem ID
  2. Problem Number
  3. Problem Title
  4. Number of Distinct Accepted User (DACU)
  5. Best Runtime of an Accepted Submission
  6. Best Memory used of an Accepted Submission
  7. Number of No Verdict Given (can be ignored)
  8. Number of Submission Error
  9. Number of Can't be Judged
  10. Number of In Queue
  11. Number of Compilation Error
  12. Number of Restricted Function
  13. Number of Runtime Error
  14. Number of Output Limit Exceeded
  15. Number of Time Limit Exceeded
  16. Number of Memory Limit Exceeded
  17. Number of Wrong Answer
  18. Number of Presentation Error
  19. Number of Accepted
  20. Problem Run-Time Limit (milliseconds)
  21. Problem Status (0 = unavailable, 1 = normal, 2 = special judge)

Specific Problem

URL : /api/p/id/{problem-id}.

To view specific problem by {problem-id}.

URL : /api/p/num/{problem-number}.

To view specific problem by {problem-number}.

Submissions to Specific Problems

URL : /api/p/subs/{pids-csv}/{start-sbt}/{end-sbt}.

To view submissions to specific problems on a given submission date range. {pids-csv} is a list of problem ids encoded in comma separated values. {start-sbt} and {end-sbt} are the date range in unix timestamp. Note that the submissions are returned in no particular order. This API is suitable for virtual contests that run for a specific date range on a number of problems.

Problem Ranklist

URL : /api/p/rank/{pid}/{rank}/{count}.

Returns submissions to a problem {pid} ranked from {rank} to {rank} + {count} - 1.

User Problem Ranklist

URL : /api/p/ranklist/{pid}/{uid}/{nabove}/{nbelow}.

Returns nearby submissions (by runtime) for a particular user submission to a problem. {pid} is the problem id. {uid} is the UVa user id. {nabove} is the number of (faster) submissions ranked above the user to be shown. {nbelow} is the number of (slower) submissions ranked below the user to be shown.

Live Events

This service is using long polling. It can hold the request for at most 1 minute for a new event. It will return immediately if there are at least one new event. The server will only keep track the last 100 submissions events. Thus, if the client is not polling after a while, it may lose some events.

URL : /api/poll/{poll-id}.

The {poll-id} is the minimum requested id. For the first call, you can use value 0 (zero) to get the last 100 events. After receiving the events, keep track of the latest "id" of the events returned and use it to call the service again with {poll-id} = the_last_id to get the next, etc.

User Submissions

Returns all of the submissions of a particular user.

DEPRECATED URL : /api/subs/{user-id}.

URL : /api/subs-user/{user-id}.

URL : /api/subs-user/{user-id}/{min-sid}.

The {user-id} is the user id of the user. The {min-sid} is optional (i.e., if specified, it will return submissions with submission id greater than {min-sid}). The service return a JSON formatted object with 3 attributes:

URL : /api/subs-user-last/{user-id}/{count}.

The service return the last {count} submissions from user {user-id} in the same format as subs-user above.

The subs array length is the same as the number of submissions of the user. Each element is one submission with values:

  1. Submission ID
  2. Problem ID
  3. Verdict ID
  4. Runtime
  5. Submission Time (unix timestamp)
  6. Language ID (1=ANSI C, 2=Java, 3=C++, 4=Pascal, 5=C++11)
  7. Submission Rank

Verdict ID can be one of the following values:

Specific Users' Submissions on Specific Problems

Returns all the submissions of the users on specific problems.

URL : /api/subs-pids/{user-ids-csv}/{pids-csv}/{min-subs-id}.

The {user-ids-csv} is the user ids presented as comma-separated-values. Similarly, the {pids-csv} is the problem ids presented in comma-separated-values. The numbers in the both csvs are limited to 100 numbers. The {min-subs-id} is the minimum submission id to be returned (that is, to show all submissions set this value to zero, to see latest submissions, set it higher as appropriate).

The result is a hash map with the key is the user id and the value is the submissions of that user that associated with one of the specified problem ids. The format of the submissions is identical with the above description.

URL : /api/subs-nums/{user-ids-csv}/{nums-csv}/{min-subs-id}.

This is exactly the same as before, except that the problems is given in problem numbers, not problem ids.

Get The Bit-Encoded-Problem IDs that Has Been Solved by Some Authors

URL : /api/solved-bits/{user-ids-csv}.

Returns an array each contains: { uid:the-user-id, solved:[bit-encoded-solved-pids] }.

The bit-encoded-solved-pids is an array where the ith bit of the jth element (0-based) represents whether the particular user has solved the problem with pid = (j*32)+i.

User Ranklist

Returns the user's ranklist and their neighbors.

URL : /api/ranklist/{user-id}/{nabove}/{nbelow}.

The {nabove} is the number of users above the {user-id} that you want to display. Similarly for the {nbelow}. Both {nabove} and {nbelow} is capped to 100. The result is a JSON formatted array where each element is a single user's rank with attributes:

Returns the user ranklist from a certain position.

URL : /api/rank/{pos}/{count}.

Returns the users ranked from {pos} to {pos} + {count} - 1.

Competitive Programming Exercises

URL : /api/cpbook/{edition}.

The {edition} is the book edition (e.g., 1, 2, or 3). The exercises is an array of chapter. Each chapter has a title and arr attribute which contains the sub-chapters. Each sub-chapter also has a title and arr attribute which contains the sub-sub-chapters. Each sub-sub-chapter is formatted as an array where the first element is the title of the sub-sub-chapter and the second element onwards are the problem numbers associated with it. The negative problem number signify that it is a starred problem.

UVa OJ Past Contests

URL : /api/contests.

List down all past UVa contests as an array of:

URL : /api/contests/id/{contest-id}.

List all submissions of a particular contest {contest-id}. It has a "subs" field containing an array of submission, each formatted as:

  1. Problem Number
  2. Verdict
  3. Runtime
  4. User ID
  5. Submission Time
  6. Language
  7. User Full Name
  8. Username

What Else?

Contact me : felix.halim at gmail if you want something new.

© Felix Halim 2013