{"id":3527,"library":"kagglesdk","title":"Kaggle API Client","description":"The `kagglesdk` is the official Python client library for interacting with Kaggle's external-facing APIs, allowing users to programmatically access competitions, datasets, kernels, and more. It is currently at version 0.1.18 and receives frequent updates.","status":"active","version":"0.1.18","language":"en","source_language":"en","source_url":"https://github.com/Kaggle/kagglesdk","tags":["data science","machine learning","kaggle","api client","competition","dataset"],"install":[{"cmd":"pip install kagglesdk","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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()`.","wrong":"from kagglesdk.api import KaggleApi","symbol":"kaggle","correct":"import kaggle"}],"quickstart":{"code":"import os\nimport kaggle\n\n# --- Kaggle API Authentication ---\n# The client expects credentials in one of two ways:\n# 1. A `kaggle.json` file in `~/.kaggle/` (recommended for local development)\n# 2. Environment variables: `KAGGLE_USERNAME` and `KAGGLE_KEY`\n# For example, in your shell:\n# export KAGGLE_USERNAME=\"your_username\"\n# export KAGGLE_KEY=\"your_api_key\"\n\n# Initialize and authenticate the API client\n# This call implicitly uses the `kaggle.json` file or environment variables.\nkaggle.api.authenticate()\n\nprint(\"Successfully authenticated to Kaggle API.\")\n\n# --- Example Usage: List active competitions ---\nprint(\"\\nActive Competitions:\")\ntry:\n    # competition_list returns a generator-like object\n    competitions = kaggle.api.competition_list(category='active', sort_by='recentlyStarted')\n    for competition in competitions:\n        print(f\"- {competition.ref}: {competition.title}\")\nexcept Exception as e:\n    print(f\"Error listing competitions: {e}\")\n\n# --- Example Usage: Download a dataset (uncomment to run) ---\n# dataset_name = 'titanic'\n# download_path = './data'\n# os.makedirs(download_path, exist_ok=True)\n# print(f\"\\nDownloading dataset '{dataset_name}' to '{download_path}'...\")\n# try:\n#     kaggle.api.dataset_download_files(dataset_name, path=download_path, unzip=True)\n#     print(f\"Dataset '{dataset_name}' downloaded and unzipped successfully.\")\n# except Exception as e:\n#     print(f\"Error downloading dataset '{dataset_name}': {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Always use `import kaggle` to access the client functionality, then interact via `kaggle.api`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Generate your Kaggle API token from your Kaggle account settings and place `kaggle.json` in `~/.kaggle/`, or set the corresponding environment variables.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement delays (e.g., `time.sleep()`) between successive API calls, particularly when performing bulk operations, to avoid hitting rate limits.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Familiarize yourself with the object structure by consulting the Kaggle API documentation or by inspecting objects using `dir()` or `type()`.","message":"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`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}