From b938d44e47d04645d0a4a42313516043728dfad3 Mon Sep 17 00:00:00 2001 From: Adithya Samavedhi Date: Wed, 15 Apr 2026 16:26:35 -0700 Subject: [PATCH 1/3] add-OpenTTD-links-to-README --- README.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 9347a0f..a2f89fb 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Python SDK for integrating Databricks with The Trade Desk Data API. Supports Fir - [Initial Setup](#initial-setup) - [SDK Example Usage](#sdk-example-usage) - [Authentication](#authentication) -- [Available Resources and Operations](#available-resources-and-operations) +- [Supported Data API Endpoints](#supported-data-api-endpoints) - [Error Handling](#error-handling) - [Server Selection](#server-selection) - [Custom HTTP Client](#custom-http-client) @@ -212,9 +212,18 @@ client = TtdDatabricksClient( --- -## Available Resources and Operations +## Supported Data API Endpoints -Each endpoint is represented by a context dataclass that configures the API call. +Each Data API endpoint is represented by a context dataclass that configures the API call. The following table lists the supported Data API endpoints, their corresponding SDK contexts, and OpenTTD documentation. + +| Data API Endpoint | Context | OpenTTD API Documentation | +|---|---|---| +| `POST /data/advertiser` | `AdvertiserContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-advertiser-external) | +| `POST /data/thirdparty` | `ThirdPartyContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) | +| `POST /providerapi/offlineconversion` | `OfflineConversionContext` | [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) | +| `POST /data/deletion-optout/advertiser` | `DeletionOptOutAdvertiserContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-advertiser-external) | +| `POST /data/deletion-optout/thirdparty` | `DeletionOptOutThirdPartyContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) | +| `POST /data/deletion-optout/merchant` | `DeletionOptOutMerchantContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) | ### First-Party Data — `/data/advertiser` @@ -229,7 +238,7 @@ context = AdvertiserContext( ) ``` -The schema for `TTDEndpoint.ADVERTISER` is defined in [advertiser.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/advertiser.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.ADVERTISER` is defined in [advertiser.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/advertiser.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -246,7 +255,7 @@ context = ThirdPartyContext( ) ``` -The schema for `TTDEndpoint.THIRD_PARTY` is defined in [third_party.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/third_party.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.THIRD_PARTY` is defined in [third_party.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/third_party.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -261,7 +270,7 @@ context = OfflineConversionContext( ) ``` -The schema for `TTDEndpoint.OFFLINE_CONVERSION` is defined in [offline_conversion.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/offline_conversion.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.OFFLINE_CONVERSION` is defined in [offline_conversion.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/offline_conversion.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -282,7 +291,7 @@ context = DeletionOptOutAdvertiserContext( ) ``` -The schema for `TTDEndpoint.DELETION_OPTOUT_ADVERTISER` is defined in [deletion_optout_advertiser.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_advertiser.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.DELETION_OPTOUT_ADVERTISER` is defined in [deletion_optout_advertiser.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_advertiser.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -300,7 +309,7 @@ context = DeletionOptOutThirdPartyContext( ) ``` -The schema for `TTDEndpoint.DELETION_OPTOUT_THIRDPARTY` is defined in [deletion_optout_thirdparty.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_thirdparty.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.DELETION_OPTOUT_THIRDPARTY` is defined in [deletion_optout_thirdparty.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_thirdparty.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -317,7 +326,7 @@ context = DeletionOptOutMerchantContext( ) ``` -The schema for `TTDEndpoint.DELETION_OPTOUT_MERCHANT` is defined in [deletion_optout_merchant.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_merchant.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.DELETION_OPTOUT_MERCHANT` is defined in [deletion_optout_merchant.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_merchant.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -329,7 +338,9 @@ Retrieve the full input schema for an endpoint: from ttd_databricks_python.ttd_databricks import TTDEndpoint, get_ttd_input_schema schema = get_ttd_input_schema(TTDEndpoint.ADVERTISER) -print(schema.treeString()) + +for field in input_schema.fields: + print(f" {field.name}: {field.dataType.simpleString()} (nullable={field.nullable})") ``` Get just the required column names (useful for DataFrame preparation): From 05f2856f7c9533a1a92f3776d2dff00e39bd108d Mon Sep 17 00:00:00 2001 From: Adithya Samavedhi Date: Thu, 16 Apr 2026 16:04:57 -0700 Subject: [PATCH 2/3] Add-note-on-token-authentication-and-external-provider-links --- README.md | 14 ++++++++------ ...D Connector Data SDK Example Notebook.ipynb | 18 ++++++++++-------- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a2f89fb..a07eca1 100644 --- a/README.md +++ b/README.md @@ -177,6 +177,8 @@ client.batch_process( All API calls require a TTD auth token passed at client creation time. +> **Note:** The SDK does not support `TtdSignature` based authentication. Refer to [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/Foundations/resources/doc/PlatformAuthentication) for instructions on how to create your `TTD-Auth` API token. + ### Factory Method (recommended for notebooks) ```python @@ -218,12 +220,12 @@ Each Data API endpoint is represented by a context dataclass that configures the | Data API Endpoint | Context | OpenTTD API Documentation | |---|---|---| -| `POST /data/advertiser` | `AdvertiserContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-advertiser-external) | -| `POST /data/thirdparty` | `ThirdPartyContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) | -| `POST /providerapi/offlineconversion` | `OfflineConversionContext` | [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) | -| `POST /data/deletion-optout/advertiser` | `DeletionOptOutAdvertiserContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-advertiser-external) | -| `POST /data/deletion-optout/thirdparty` | `DeletionOptOutThirdPartyContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) | -| `POST /data/deletion-optout/merchant` | `DeletionOptOutMerchantContext` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) | +| `POST /data/advertiser` | `AdvertiserContext` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-advertiser-firstparty)
[OpenTTD Documentation (External Provider)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-advertiser-external) | +| `POST /data/thirdparty` | `ThirdPartyContext` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) | +| `POST /providerapi/offlineconversion` | `OfflineConversionContext` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) | +| `POST /data/deletion-optout/advertiser` | `DeletionOptOutAdvertiserContext` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-deletion-optout-advertiser)
[OpenTTD Documentation (External Provider)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-advertiser-external) | +| `POST /data/deletion-optout/thirdparty` | `DeletionOptOutThirdPartyContext` | [OpenTTD Documentation ](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) | +| `POST /data/deletion-optout/merchant` | `DeletionOptOutMerchantContext` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) | ### First-Party Data — `/data/advertiser` diff --git a/example_notebook/TTD Connector Data SDK Example Notebook.ipynb b/example_notebook/TTD Connector Data SDK Example Notebook.ipynb index 29b34a6..cf8abb2 100644 --- a/example_notebook/TTD Connector Data SDK Example Notebook.ipynb +++ b/example_notebook/TTD Connector Data SDK Example Notebook.ipynb @@ -37,7 +37,9 @@ "In production, retrieve secrets from Databricks Secrets:\n", "```python\n", "api_token = dbutils.secrets.get(scope=\"ttd\", key=\"api-token\")\n", - "```" + "```\n", + "\n", + "> **Note:** The SDK does not support `TtdSignature` based authentication. Refer to [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/Foundations/resources/doc/PlatformAuthentication) for instructions on how to create your `TTD-Auth` API token." ] }, { @@ -114,14 +116,14 @@ "\n", "For more information on the meaning of particular fields and supported data types supported per endpoint refer to the following table:\n", "\n", - "| Endpoint | Context | Data API | Documentation |\n", + "| Endpoint | Context | Data API | OpenTTD API Documentation |\n", "|---|---|---|---|\n", - "| Advertiser | `AdvertiserContext` | `POST /data/advertiser` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-advertiser-external) |\n", - "| Third Party | `ThirdPartyContext` | `POST /data/thirdparty` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) |\n", - "| Offline Conversion | `OfflineConversionContext` | `POST /providerapi/offlineconversion` | [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) |\n", - "| Deletion / Opt-Out — Advertiser | `DeletionOptOutAdvertiserContext` | `POST /data/deletion-optout/advertiser` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-advertiser-external) |\n", - "| Deletion / Opt-Out — Third Party | `DeletionOptOutThirdPartyContext` | `POST /data/deletion-optout/thirdparty` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) |\n", - "| Deletion / Opt-Out — Merchant | `DeletionOptOutMerchantContext` | `POST /data/deletion-optout/merchant` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) |" + "| Advertiser | `AdvertiserContext` | `POST /data/advertiser` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-advertiser-firstparty)
[OpenTTD Documentation (External Provider)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-advertiser-external) |\n", + "| Third Party | `ThirdPartyContext` | `POST /data/thirdparty` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) |\n", + "| Offline Conversion | `OfflineConversionContext` | `POST /providerapi/offlineconversion` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) |\n", + "| Deletion / Opt-Out — Advertiser | `DeletionOptOutAdvertiserContext` | `POST /data/deletion-optout/advertiser` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-deletion-optout-advertiser)
[OpenTTD Documentation (External Provider)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-advertiser-external) |\n", + "| Deletion / Opt-Out — Third Party | `DeletionOptOutThirdPartyContext` | `POST /data/deletion-optout/thirdparty` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) |\n", + "| Deletion / Opt-Out — Merchant | `DeletionOptOutMerchantContext` | `POST /data/deletion-optout/merchant` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) |" ] }, { From 858fff112e60912959f0f1d376ab7530ec8fa7be Mon Sep 17 00:00:00 2001 From: Adithya Samavedhi Date: Thu, 16 Apr 2026 16:40:59 -0700 Subject: [PATCH 3/3] mention-Data-API-as-application-for-token-creation --- README.md | 2 +- .../TTD Connector Data SDK Example Notebook.ipynb | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a07eca1..9334c49 100644 --- a/README.md +++ b/README.md @@ -177,7 +177,7 @@ client.batch_process( All API calls require a TTD auth token passed at client creation time. -> **Note:** The SDK does not support `TtdSignature` based authentication. Refer to [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/Foundations/resources/doc/PlatformAuthentication) for instructions on how to create your `TTD-Auth` API token. +> **Note:** The SDK does not support `TtdSignature` based authentication. Refer to [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/Foundations/resources/doc/PlatformAuthentication) for instructions on how to create your `TTD-Auth` API token (select `Data API` as the `Application`). ### Factory Method (recommended for notebooks) diff --git a/example_notebook/TTD Connector Data SDK Example Notebook.ipynb b/example_notebook/TTD Connector Data SDK Example Notebook.ipynb index cf8abb2..4f1c123 100644 --- a/example_notebook/TTD Connector Data SDK Example Notebook.ipynb +++ b/example_notebook/TTD Connector Data SDK Example Notebook.ipynb @@ -39,7 +39,7 @@ "api_token = dbutils.secrets.get(scope=\"ttd\", key=\"api-token\")\n", "```\n", "\n", - "> **Note:** The SDK does not support `TtdSignature` based authentication. Refer to [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/Foundations/resources/doc/PlatformAuthentication) for instructions on how to create your `TTD-Auth` API token." + "> **Note:** The SDK does not support `TtdSignature` based authentication. Refer to [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/Foundations/resources/doc/PlatformAuthentication) for instructions on how to create your `TTD-Auth` API token (select `Data API` as the `Application`)." ] }, { @@ -333,4 +333,4 @@ }, "nbformat": 4, "nbformat_minor": 4 -} +} \ No newline at end of file