Kaggle API Client

Warnings

• gotcha The PyPI package name is `kagglesdk`, but it is imported as the `kaggle` module (e.g., `import kaggle`). Attempting to import directly from `kagglesdk` (e.g., `from kagglesdk import api`) will result in an `ImportError` or unexpected behavior.
  Fix: Always use `import kaggle` to access the client functionality, then interact via `kaggle.api`.
• gotcha Authentication is typically managed by `kaggle.api.authenticate()`, which looks for a `kaggle.json` file in `~/.kaggle/` or the `KAGGLE_USERNAME` and `KAGGLE_KEY` environment variables. If credentials are not found, an `ApiException` will be raised.
  Fix: Generate your Kaggle API token from your Kaggle account settings and place `kaggle.json` in `~/.kaggle/`, or set the corresponding environment variables.
• gotcha When downloading files (e.g., `dataset_download_files`, `competition_download_files`), the `path` argument specifies the destination directory. If a relative path is provided, it's relative to the current working directory. Files are often downloaded as ZIP archives, and `unzip=True` is commonly used.
  Fix: Always provide an absolute path for `path` using `os.path.abspath()` or `os.path.join(os.getcwd(), 'your_dir')` for predictable file locations, and set `unzip=True` if you expect archive files.
• gotcha The Kaggle API client does not automatically handle rate limiting. Frequent or rapid requests, especially in loops or automated scripts, can lead to your IP being temporarily blocked by Kaggle's servers.
  Fix: Implement delays (e.g., `time.sleep()`) between successive API calls, particularly when performing bulk operations, to avoid hitting rate limits.
• gotcha API methods typically return custom objects (e.g., `Competition`, `Dataset`) or lists of these objects, not raw Python dictionaries. Access data using dot notation (e.g., `competition.ref`, `competition.title`).
  Fix: Familiarize yourself with the object structure by consulting the Kaggle API documentation or by inspecting objects using `dir()` or `type()`.

Install

• pip install kagglesdk Install latest version

Imports

• kaggle

  import kaggle

  The PyPI package `kagglesdk` is imported into your Python code as the `kaggle` module. While `KaggleApi` exists, the idiomatic way to use the client is through `kaggle.api` after calling `kaggle.api.authenticate()`.

Quickstart

This quickstart demonstrates how to authenticate with the Kaggle API client and then use it to list active competitions. It also includes a commented-out example for downloading a dataset. Ensure your Kaggle API credentials (`kaggle.json` file or `KAGGLE_USERNAME`, `KAGGLE_KEY` environment variables) are correctly configured before running.

import os
import kaggle

# --- Kaggle API Authentication ---
# The client expects credentials in one of two ways:
# 1. A `kaggle.json` file in `~/.kaggle/` (recommended for local development)
# 2. Environment variables: `KAGGLE_USERNAME` and `KAGGLE_KEY`
# For example, in your shell:
# export KAGGLE_USERNAME="your_username"
# export KAGGLE_KEY="your_api_key"

# Initialize and authenticate the API client
# This call implicitly uses the `kaggle.json` file or environment variables.
kaggle.api.authenticate()

print("Successfully authenticated to Kaggle API.")

# --- Example Usage: List active competitions ---
print("\nActive Competitions:")
try:
    # competition_list returns a generator-like object
    competitions = kaggle.api.competition_list(category='active', sort_by='recentlyStarted')
    for competition in competitions:
        print(f"- {competition.ref}: {competition.title}")
except Exception as e:
    print(f"Error listing competitions: {e}")

# --- Example Usage: Download a dataset (uncomment to run) ---
# dataset_name = 'titanic'
# download_path = './data'
# os.makedirs(download_path, exist_ok=True)
# print(f"\nDownloading dataset '{dataset_name}' to '{download_path}'...")
# try:
#     kaggle.api.dataset_download_files(dataset_name, path=download_path, unzip=True)
#     print(f"Dataset '{dataset_name}' downloaded and unzipped successfully.")
# except Exception as e:
#     print(f"Error downloading dataset '{dataset_name}': {e}")