Numerai Python API

Automatically download and upload data for the Numerai machine learning competition.

This library is a Python client to the Numerai API. The interface is programmed in Python and allows downloading the training data, uploading predictions, and accessing user, submission and competitions information.

If you encounter a problem or have suggestions, feel free to open an issue.

Installation

pip install --upgrade numerapi

Usage

Numerapi can be used as a regular, importable Python module or from the command line.

Some actions (like uploading predictions or staking) require a token to verify that it is really you interacting with Numerai's API. These tokens consists of a public_id and secret_key. Both can be obtained by login in to Numer.ai and going to Account -> Custom API Keys. Tokens can be passed to the Python module as parameters or you can be set via environment variables (NUMERAI_PUBLIC_ID and NUMERAI_SECRET_KEY).

Python module

Usage example:

import numerapi
# some API calls do not require logging in
napi = numerapi.NumerAPI(verbosity="info")
# download current dataset
napi.download_current_dataset(unzip=True)
# get competitions
all_competitions = napi.get_competitions()
# get current leaderboard
leaderboard = napi.get_leaderboard()
# check if a new round has started
if napi.check_new_round():
    print("new round has started within the last 24hours!")
else:
    print("no new round within the last 24 hours")

# provide api tokens
example_public_id = "somepublicid"
example_secret_key = "somesecretkey"
napi = NumerAPI(example_public_id, example_secret_key)

# upload predictions
submission_id = napi.upload_predictions("preds.csv", tournament=1)
# check submission status
napi.submission_status()
# increase your stake by 1.2 NMR
napi.stake_increase(1.2)

# convert results to a pandas dataframe
import pandas as pd
df = pd.io.json.json_normalize(napi.daily_user_performances("uuazed"), sep="-")

Command line interface

To get started with the cli interface, let's take a look at the help page:

$ numerapi --help
Usage: numerapi [OPTIONS] COMMAND [ARGS]...

  Wrapper around the Numerai API

Options:
  --help  Show this message and exit.

Commands:
  check-new-round                 Check if a new round has started within...
  competitions                    Retrieves information about all...
  current-round                   Get number of the current active round.
  daily-submissions-performances  Fetch daily performance of a user's...
  daily-user-performances         Fetch daily performance of a user.
  dataset-url                     Fetch url of the current dataset.
  download-dataset                Download dataset for the current active...
  leaderboard                     Get the leaderboard.
  payments                        List all your payments
  profile                         Fetch the public profile of a user.
  rankings                        Get the overall rankings.
  stake-decrease                  Decrease your stake by `value` NMR.
  stake-drain                     Completely remove your stake.
  stake-get                       Get stake value of a user.
  stake-increase                  Increase your stake by `value` NMR.
  stakes                          List all your stakes.
  staking-leaderboard             Retrieves the staking competition...
  submission-filenames            Get filenames of your submissions
  submission-ids                  Get dict with username->submission_id...
  submission-status               checks the submission status
  submit                          Upload predictions from file.
  tournament-name2number          Translate tournament name to tournament...
  tournament-number2name          Translate tournament number to tournament...
  tournaments                     Get all tournaments.
  transactions                    List all your deposits and withdrawals.
  user                            Get all information about you!
  user-activities                 Get user activities (works for all users!)
  v1-leaderboard                  Retrieves the leaderboard for the given...
  version                         Installed numerapi version.

Each command has it's own help page, for example:

$ numerapi submit --help
Usage: numerapi submit [OPTIONS] PATH

  Upload predictions from file.

Options:
  --tournament INTEGER  The ID of the tournament, defaults to 1
  --help                Show this message and exit.

API Reference

Checkout the detailed API docs to learn about all available methods, parameters and returned values.