{"id":6907,"library":"td-client","title":"Treasure Data API Library for Python","description":"The `td-client` Python library provides a wrapper for the Treasure Data API (REST API), allowing users to programmatically interact with Treasure Data services. It enables tasks such as managing databases and tables, issuing queries (including asynchronous execution), and performing bulk data imports. The library is currently at version 1.7.0 and is actively maintained with consistent updates.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/treasure-data/td-client-python","tags":["treasure data","api client","data platform","cloud","rest api"],"install":[{"cmd":"pip install td-client","lang":"bash","label":"Install core library"},{"cmd":"pip install certifi","lang":"bash","label":"Recommended for SSL certificate verification"}],"dependencies":[{"reason":"Recommended for robust SSL certificate verification when connecting to Treasure Data API endpoints.","package":"certifi","optional":true}],"imports":[{"note":"The primary client class for interacting with the Treasure Data API.","symbol":"Client","correct":"from tdclient import Client"},{"note":"Commonly imported as a module to access its components, e.g., `tdclient.Client`.","symbol":"tdclient","correct":"import tdclient"}],"quickstart":{"code":"import os\nimport tdclient\n\n# Ensure TD_API_KEY environment variable is set with your Treasure Data API key.\n# Optionally, set TD_API_SERVER to override the default endpoint (https://api.treasuredata.com).\n# Example: export TD_API_KEY=\"YOUR_TREASURE_DATA_API_KEY\"\n# Example: export TD_API_SERVER=\"https://api.us01.treasuredata.com\"\n\napi_key = os.environ.get(\"TD_API_KEY\", \"\")\napi_server = os.environ.get(\"TD_API_SERVER\", \"https://api.treasuredata.com\")\n\nif not api_key:\n    raise ValueError(\"TD_API_KEY environment variable not set. Please set it to your Treasure Data API key.\")\n\ntry:\n    with tdclient.Client(apikey=api_key, endpoint=api_server) as client:\n        print(\"Listing recent jobs:\")\n        # Retrieve and print details of the 20 most recent jobs\n        for job in client.jobs():\n            print(f\"  Job ID: {job.job_id}, Type: {job.type}, Status: {job.status}, Created At: {job.created_at}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart initializes the `td-client` with an API key (preferably from an environment variable) and then lists the 20 most recent jobs in your Treasure Data account. It demonstrates basic client setup and interaction."},"warnings":[{"fix":"Verify that `td-client` is the correct library for your needs, especially if you intend to interact with the Treasure Data REST API. For pandas integration or direct database access, consider `pytd`.","message":"Confusing `td-client` with other Python libraries or tools named 'TDClient'. Be aware that 'td-client' (this library) is specifically for the Treasure Data REST API. Other packages like `pytd` offer different functionalities (e.g., pandas integration, direct Trino/Presto access), and 'TDClient' may also refer to a non-Python Student Aid Internet Gateway (SAIG) client.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use environment variables (`TD_API_KEY`, `TD_API_SERVER`) for sensitive information and flexible configuration. Ensure the API key is valid and the endpoint matches your Treasure Data region (e.g., `https://api.us01.treasuredata.com`).","message":"Incorrect API key or endpoint configuration can lead to authentication or connection errors. The client expects the API key to be passed via the `apikey` argument or read from the `TD_API_KEY` environment variable. The endpoint can be configured via the `endpoint` argument or `TD_API_SERVER` environment variable.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly define `dtypes` (e.g., `{'col1': 'int'}`) or `converters` (e.g., `{'col2': int}`) when dealing with CSV/TSV data to ensure correct type conversion and prevent data integrity issues.","message":"When importing CSV or TSV data, proper parsing of column types is crucial. The `upload_file` and `create_bulk_import` methods accept `dtypes` and `converters` parameters to specify how individual columns should be interpreted. The default behavior is 'guess', which might not always be accurate.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `certifi` is installed (`pip install certifi`) to enable proper SSL certificate verification. If encountering SSL errors in a controlled environment, consult documentation for trusted certificate configurations rather than disabling verification outright.","message":"SSL certificate verification is important for secure communication but can sometimes cause issues in certain environments. The library documentation recommends installing `certifi` for more robust SSL verification.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}