developer.hackerearth.com

API v2


The HackerEarth API

This is HackerEarth API resource documentation. If you have any problems or requests please contact the maintainer.


The API provides endpoints for compiling and running code in several languages. It can be accessed via a simple API key based authorization process. You need to register your web application in order to get a client specific client_secret which must be provided while communicating with the API. Currently, there is a cap on the number of clients a user can register and also on the number of free requests a user can make. The API receives all the data via POST and returns the data as JSON. You can register your own client here.


The API defines the following endpoints:

http://api.hackerearth.com/code/compile/
http://api.hackerearth.com/code/run/

Every JSON object returned by the API always consists of atleast two attributes, 'message' and 'errors'. 'message' contains the description of errors encountered while processing of a request and 'errors' may contain key-value pairs which were the cause of the errors.

{"message": "ArgumentMissingError: client_secret is needed!", "errors": {}}

In case of a successful compile request, the JSON object returned looks like:

{"errors": {}, 
"id": "7e5cfbe", 
"code_id": "7e5cfbe", 
"message": "OK", 
"compile_status": "OK",
"web_link": "http://code.hackerearth.com/7e5cfbe"}

In case of a successful run request, the JSON object returned might look like:

{"errors": {}, 
"id": "7e5cfbe", 
"code_id": "7e5cfbe", 
"message": "OK", 
"compile_status": "OK",
"run_status": {"status": "AC",
              "time_used": "0.1005",
              "memory_used": "64",
              "output": "Hello", 
              "output_html": "Hello",
              "signal": "OTHER",
              "status_detail": "N/A",
              "time_limit": 5,
              "memory_limit": 262144}
"web_link": "http://code.hackerearth.com/7e5cfbe"}

Each endpoint needs atleast three necessary parameters viz client_secret, source and lang.

client_secret

client_secret is a 40 character random key that serves as an identification for a particular client and must be provided when communicating with the API. You can create a client_secret on the API registration page. Failing to provide a client_secret returns the following 400 Bad Request response.

>> curl -i http://api.hackerearth.com/code/compile/
>>
HTTP/1.1 400 BAD REQUEST
Date: Wed, 23 Jan 2013 22:56:25 GMT
Server: Apache/2.2.22 (Ubuntu)
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{"message": "ArgumentMissingError: client_secret is needed!", "errors": {}} 

Providing an invalid client_secret returns the following 400 Bad Request response. The invalid client_secret is also returned in 'errors' attribute of the JSON response object.

>> curl -i --data "client_secret=adsafwqf5dcb5757e72c96d9" http://api.hackerearth.com/code/compile/
>>
HTTP/1.1 400 BAD REQUEST
Date: Wed, 23 Jan 2013 23:00:20 GMT
Server: Apache/2.2.22 (Ubuntu)
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{"message": "UnregisteredClientError: Client does not exist", "errors": {"client_secret": "adsafwqf5dcb5757e72c96d969a1a"}}

source

source is the actual text or the source code that you want to compile or run. Failing to provide the source parameter returns 400 response.

>> curl -i --data "client_secret=5db3f1c12c59caa1002d1cb5" http://api.hackerearth.com/code/compile/
>>
HTTP/1.1 400 BAD REQUEST
Date: Thu, 24 Jan 2013 16:38:09 GMT
Server: Apache/2.2.22 (Ubuntu)
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{"message": "ArgumentMissingError: source is needed!", "errors": {}}

lang

lang is a string representing the programming language in which the source is written. lang is a required parameter and a similar response as that of source is returned by the API if lang is missing in the POST requests.
Possible values of lang argument are C, CPP, CPP11, CLOJURE, CSHARP, JAVA, JAVASCRIPT, HASKELL, PERL, PHP, PYTHON, RUBY. The corresponding langauges are C, C++, C++11, Clojure, C#, Java, JavaScript, Haskell, Perl, PHP, Python and Ruby.


input

input is an optional parameter which represents the input to be fed to your program.


time_limit

time_limit is an optional parameter which is the max time for which program is allowed to run. Maximum value of time limit can be 5 seconds. Any value greater than 5 in the API request is set to 5. Exceeding the time limit returns the status as TLE in the response.


memory_limit

memory_limit is an optional paramer which is the max memory allowed to be used by the program. Maximum value of memory limit can be 262144 (256 MB). Any value greater than 262144 in the API request is set to 262144. Exceeding the memory limit returns the status as MLE in the response.


async

async is an optional parameter which is the API request mode used by the program. The value 1 turns it on. You should use async mode while writing applications so that you can avoid processes from hanging for response and reduce memory overhead and timeout.

Below is a sample python script which makes valid requests to the HackerEarth API.


Synchronous API request from raw string

#! -*- coding: utf-8 -*-

import requests

# constants
RUN_URL = u'http://api.hackerearth.com/code/run/'
CLIENT_SECRET = '5db3f1c12c59caa1002d1cb5757e72c96d969a1a'

source = "import sys;print(sys.path)"

data = {
    'client_secret': CLIENT_SECRET,
    'async': 0,
    'source': source,
    'lang': "PYTHON",
    'time_limit': 5,
    'memory_limit': 262144,
}

r = requests.post(RUN_URL, data=data)
print r.json()

Output from the above script is:

post_data: lang=PYTHON&time_limit=5&memory_limit=262144&source=import+sys%3Bprint%28sys.path%29&
async=0&client_secret=5db3f1c12c59caa1002d1cb5757e72c96d969a1a

{u'errors': {}, u'code_id': u'26c372Q', u'web_link': u'http://code.hackerearth.com/26c372Q', u'compile_status': u'OK',
u'message': u'OK', u'run_status': {u'status': u'AC', u'time_limit': 5,
u'output_html': u"['/tmp', '/usr/lib/python2.7', '/usr/lib/python2.7/plat-linux2', 
    '/usr/lib/python2.7/lib-tk', '/usr/lib/python2.7/lib-old', '/usr/lib/python2.7/lib-dynload', 
    '/usr/local/lib/python2.7/dist-packages', '/usr/lib/python2.7/dist-packages', 
    '/usr/lib/pymodules/python2.7']
", u'memory_limit': 262144, u'time_used': u'0.1005', u'signal': u'OTHER', u'status_detail': u'N/A', u'async': 0, u'output': u"['/tmp', '/usr/lib/python2.7', '/usr/lib/python2.7/plat-linux2', '/usr/lib/python2.7/lib-tk', '/usr/lib/python2.7/lib-old', '/usr/lib/python2.7/lib-dynload', '/usr/local/lib/python2.7/dist-packages', '/usr/lib/python2.7/dist-packages', '/usr/lib/pymodules/python2.7']\n", u'memory_used': u'64'}}

Synchronous API request from file

#! -*- coding: utf-8 -*-

import requests

# constants
RUN_URL = u'http://api.hackerearth.com/code/run/'

CLIENT_SECRET = '5db3f1c12c59caa1002d1cb5757e72c96d969a1a'

source = open('test.py', 'r')
"""
test.py
#! -*- coding: utf-8 -*-

def square(no):
    return no * no

print(square(-23))
"""

data = {
    'client_secret': CLIENT_SECRET,
    'async': 0,
    'source': source.read(),
    'lang': "PYTHON",
    'time_limit': 5,
    'memory_limit': 262144,
}

r = requests.post(RUN_URL, data=data)
source.close()
print r.json()

Output from the above script is:

post_data: lang=PYTHON&time_limit=5&memory_limit=262144&
source=%23%21+-%2A-+coding%3A+utf-8+-%2A-%0A%0Adef+square%28no%29%3A%0A++++return+no+%2A+no%0A%0Aprint%28square%28-23%29%29%0A%0A&
async=0&client_secret=5db3f1c12c59caa1002d1cb5757e72c96d969a1a

{u'errors': {}, u'code_id': u'c93d09V', u'web_link': u'http://code.hackerearth.com/c93d09V', u'compile_status': u'OK',
u'message': u'OK', u'run_status': {u'status': u'AC', u'time_limit': 5, u'output_html': u'529
', u'memory_limit': 262144, u'time_used': u'0.1005', u'signal': u'OTHER', u'status_detail': u'N/A', u'async': 0, u'output': u'529\n', u'memory_used': u'64'}}

Asynchronous API request

import urllib

COMPILE_URL = 'http://api.hackerearth.com/code/compile/'
RUN_URL = 'http://api.hackerearth.com/code/run/'

CLIENT_SECRET = '5db3f1c12c59caa1002d1cb5757e72c96d969a1a'

source = open('sample.c').read()
lang = 'C'

post_data = {
    'client_secret': CLIENT_SECRET,
    
    # Asynchronous mode on
    'async': 1,

    'source': source,
    'lang': lang,
    'time_limit': 5,
    'memory_limit': 262144,

    # Id to keep track of request
    'id': 123,

    # Callback URL where processed response will later arrive
    # - this response is same as the response received in
    # synchronous API request.
    'callback': 'http://example.com/receive-hackerearth-response/'
}

post_data = urllib.urlencode(post_data)

response = urllib.urlopen(RUN_URL, post_data)
print "post_data: ",post_data
print
print response.read()

Output from the above script is:

post_data:  lang=C&source=%23include+%3Cstdio.h%3E%0A%0Aint+main%28%29+%7B%0A++++printf%28%22Hello%22%29%3B%0A++++int+n%3B%0A++++scanf%28%22%25d%22%2C+%26n%29%3B%0A++++printf%28%22%5Cn%25d%5Cn%22%2C+n%29%3B%0A++++return+0%3B%0A%7D%0A&callback=http%3A%2F%2Fexample.com%2Freceive-hackerearth-response%2F&async=1&time_limit=5&client_secret=4df77c2c2eb62f9adb20bd1127f6f44a4ce6cda4&id=123&memory_limit=262144

{"errors": {}, "code_id": "3d255bX", "id": 123, "message": "OK", "run_status": {"status": "NA", "time_limit": 5, "async": 1, "memory_limit": 262144}, "compile_status": "Compiling...", "web_link": "http://code.hackerearth.com/3d255bX"}

The response recieved at the callback url is in JSON format. You can process it as given in the example code below.

import json

def api_response(request):
    payload = request.POST.get('payload', '') 
    
    """
    This payload is in JSON format. You need to load it using
    native method to convert it into dictionary for easy operations
    later on.
    """
    payload = json.loads(payload)
    print payload

    """
    Payload Format:
    {u'errors': {}, u'code_id': u'4c384aM', u'web_link': u'http://code.hackerearth.com/4c384aM', u'compile_status': u'OK', u'id': u'123456', u'async': 1, u'run_status': {u'status': u'AC', u'memory_used': u'64', u'output_html': u'Hello
1
', u'time_used': u'0.1006', u'signal': u'OTHER', u'status_detail': u'N/A', u'output': u'Hello\\n1\\n'}, u'message': u'OK'} """ run_status = payload.get('run_status') o = run_status['output'] print o """ Output: Hello 1 """ return HttpResponse('API Response Recieved!')

All submissions are welcome. Sample code for API request in different languages are welcome. To submit a change, fork this repo, commit your changes, and send us a pull request.