The Trade Desk Integration for Nodus
1. Introduction to The Trade Desk Integration
What Is This Integration?
The Trade Desk integration connects your Trade Desk advertising platform with Nodus, allowing you to extract, analyze, and transform campaign data, performance metrics, and audience insights. This integration functions as a source connector, bringing your Trade Desk data into the Nodus ecosystem for advanced analytics and business intelligence.
Prerequisites:
- An active Trade Desk account
- API credentials (username and password)
- Advertiser ID for the account you want to extract data from
- Optional: Long-lived API Access Token for more secure authentication
Connection Overview:
The integration uses The Trade Desk's API to extract advertising data and performance metrics. Authentication is handled through standard API credentials or Long-lived Access Token, and data is extracted based on predefined report templates.
2. Platform Setup Documentation (Setup Form for The Trade Desk)
Purpose & Scope
This section covers how to set up the initial connection between Nodus and The Trade Desk by providing the necessary authentication credentials and account details.
Field-by-Field Breakdown:
Integration Name
- Field Name & Label: Integration Name
- Description & Purpose: A descriptive name to identify this Trade Desk integration within your Nodus account.
- Validation Rules & Format: Text string, required field.
- Examples: "Trade Desk - Agency Account", "Performance Marketing Data"
- Troubleshooting Tips: Use a descriptive name that clearly identifies the specific Trade Desk account or purpose.
Advertiser ID
- Field Name & Label: Advertiser ID
- Description & Purpose: The unique identifier for your Trade Desk advertiser account.
- Validation Rules & Format: Alphanumeric string, required field.
- Examples: "a1b2c3d4"
- Troubleshooting Tips: This is the alpha-numeric ID generated for each of your Trade Desk Advertiser Seats. You can find this in your Trade Desk account settings or from your account manager.
API Username
- Field Name & Label: API Username
- Description & Purpose: The username used for API authentication.
- Validation Rules & Format: Email address, required field.
- Examples: "api.user@company.com"
- Troubleshooting Tips: This is the email address associated with your advertiser's API Login Email, not your personal Trade Desk login email. Contact your Trade Desk account manager if you're unsure which email to use.
API Password
- Field Name & Label: API Password
- Description & Purpose: The password used for API authentication.
- Validation Rules & Format: Text string, required field.
- Troubleshooting Tips: This is the password associated with your advertiser's API login, not your personal Trade Desk login password.
Long-Lived API Access Token
- Field Name & Label: Long-Lived API Access Token (Optional)
- Description & Purpose: An alternative authentication method that provides more secure, long-term access.
- Validation Rules & Format: Text string, optional field.
- Troubleshooting Tips: You can generate a long-lived token in the Trade Desk Partner Portal. This is recommended for production environments as it's more secure than username/password authentication.
External Link
- Link Label: "Locate Your API Information"
- URL: https://docs.nodus.io/the-trade-desk/
- Purpose: Provides access to Nodus documentation for finding your Trade Desk API information.
Step-by-Step Guide:
- Gather your Trade Desk credentials:
- Obtain your Advertiser ID from your Trade Desk account dashboard or from your account manager
- Ensure you have API username and password credentials
- Optionally, generate a Long-Lived API Access Token in the Partner Portal for enhanced security
- Enter your integration details in the Nodus setup form:
- Provide a meaningful Integration Name
- Enter your Advertiser ID
- Enter your API Username
- Enter your API Password
- Optionally, enter your Long-Lived API Access Token
- Save the configuration and test the connection
Reference Links:
3. Extraction/Query Configuration (Extraction Form for The Trade Desk)
Purpose & Overview
This section explains how to configure data extraction from The Trade Desk. The form allows you to select specific report templates and define date ranges for data extraction.
Template & Field Documentation:
Template Selection
- Field Name & Label: Select a template
- Description & Purpose: Defines which type of Trade Desk data to extract
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- Trade Desk Ad Dimensions - Metadata and attributes for ads/creatives
- Trade Desk Ad Group Dimensions - Metadata and attributes for ad groups
- Trade Desk Campaign Dimensions - Metadata and attributes for campaigns
- Trade Desk Ad Group Performance - Performance metrics at the ad group level
- Trade Desk All Metric Performance - Comprehensive performance metrics across all levels
- Troubleshooting Tips: Select the template that best aligns with your analytics goals.
Lookback Range
- Field Name & Label: Lookback Range
- Description & Purpose: Specifies how many days back to extract data
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- 3-day Range
- 7-day Range
- 28-day Range (recommended)
- 90-day Range (Optimal if 90-day DDA is used)
- Custom Range
- Troubleshooting Tips: Larger date ranges will result in more data being extracted but may take longer to process. The recommended range is 28 days for most use cases.
Historic Date
- Field Name & Label: Historic Date
- Description & Purpose: For custom date range extraction, specifies the start and end dates
- Validation Rules & Format: Date picker, required when Custom Range is selected
- Troubleshooting Tips: The Trade Desk typically maintains historical data for up to 13 months, but there may be limitations on how far back you can extract certain metrics.
Workflow & Examples:
- Select the appropriate template (e.g., "Trade Desk Campaign Dimensions" for campaign metadata)
- Choose a lookback period or select "Custom Range" and specify start and end dates
- Preview the query to confirm configuration
- Execute extraction
Example Use Cases:
Campaign Analysis:
- Template: Trade Desk Campaign Dimensions
- Lookback: 28-day Range
- Purpose: Analyze campaign settings, budget information, and flight dates
Ad Group Performance Analysis:
- Template: Trade Desk Ad Group Performance
- Lookback: 90-day Range
- Purpose: Review performance metrics at the ad group level including impressions, clicks, conversions, and video completion rates
Comprehensive Performance Review:
- Template: Trade Desk All Metric Performance
- Historic Date: Custom range for specific campaign periods
- Purpose: Deep dive into all available performance metrics including device-level breakdowns
Data Mapping & Underlying Models for The Trade Desk
Data Model Overview
The Trade Desk integration extracts data using predefined query templates that map to specific endpoints and data structures in The Trade Desk API.
Schema & Field Mapping
Ad Group Performance Schema
| Field | Description |
|---|---|
| Date | Date for the metrics |
| Partner_ID | The partner identifier |
| Advertiser_ID | The advertiser account identifier |
| Campaign_ID | The campaign identifier |
| Ad_Group_ID | The ad group identifier |
| Ad_Format | Format of the ad (Display, Video, etc.) |
| Creative_ID | The creative identifier |
| Frequency | Frequency cap number |
| Advertiser | Name of the advertiser |
| Campaign | Name of the campaign |
| Ad_Group | Name of the ad group |
| Ad_Group_Budget_In_Impressions | Ad group budget expressed in impressions |
| Ad_Group_Daily_Cap_In_Impressions | Daily impression cap for the ad group |
| Ad_Group_Daily_Target_In_Impressions | Daily impression target for the ad group |
| Ad_Group_Base_Bid_CPM_Adv_Currency | Base CPM bid in advertiser's currency |
| Ad_Group_Budget_Adv_Currency | Ad group budget in advertiser's currency |
| Ad_Group_Daily_Cap_Adv_Currency | Daily cap in advertiser's currency |
| Ad_Group_Daily_Target_Adv_Currency | Daily target in advertiser's currency |
| Advertiser_Currency_Code | Currency code of the advertiser |
| Partner_Currency_Code | Currency code of the partner |
| Creative | Name of the creative |
| Impressions | Number of impressions served |
| Clicks | Number of clicks received |
| TTD_Cost_Adv_Currency | Cost in advertiser's currency |
| TTD_Cost_Partner_Currency | Cost in partner's currency |
| TTD_Cost_USD | Cost in USD |
| Player_Views | Number of video player views |
| Player_Starts | Number of video playback starts |
| Player_25_Percent_Complete | Number of videos viewed to 25% completion |
| Player_50_Percent_Complete | Number of videos viewed to 50% completion |
| Player_75_Percent_Complete | Number of videos viewed to 75% completion |
| Player_Completed_Views | Number of videos viewed to completion |
| Player_Mute | Number of player mute actions |
| Player_Unmute | Number of player unmute actions |
| Player_Pause | Number of player pause actions |
| Player_Resume | Number of player resume actions |
| Player_Full_Screen | Number of full screen expansions |
| Player_Errors | Number of player errors |
| Player_Skip | Number of video skips |
| Player_Engaged_Views | Number of engaged video views |
| Player_Rewind | Number of rewind actions |
| Player_Expansion | Number of player expansions |
| Player_Collapse | Number of player collapses |
| Player_Invitation_Accept | Number of accepted invitations |
| Player_Close | Number of player closes |
| Sampled_Tracked_Impressions | Number of sampled tracked impressions |
| Sampled_Viewed_Impressions | Number of sampled viewed impressions |
| Deal_ID | Identifier for the deal |
| Ad_Server_Name | Name of the ad server |
| Ad_Server_Creative_Placement_ID | Ad server placement ID |
| Bids | Number of bids placed |
| Total_Bid_Amount_Adv_Currency | Total bid amount in advertiser's currency |
| Total_Bid_Amount_Partner_Currency | Total bid amount in partner's currency |
| Total_Bid_Amount_USD | Total bid amount in USD |
| Conversion_Touch_01 | Number of conversion touches for conversion type 1 |
| Conversion_Touch_Revenue_01 | Revenue from conversion touches for type 1 |
| Click_Conversion_01 | Number of click conversions for type 1 |
| Click_Conversion_Revenue_01 | Revenue from click conversions for type 1 |
| View_Through_Conversion_01 | Number of view-through conversions for type 1 |
| View_Through_Conversion_Revenue_01 | Revenue from view-through conversions for type 1 |
| Click_Conversion_02 | Number of click conversions for type 2 |
| Click_Conversion_Revenue_02 | Revenue from click conversions for type 2 |
| View_Through_Conversion_02 | Number of view-through conversions for type 2 |
| View_Through_Conversion_Revenue_02 | Revenue from view-through conversions for type 2 |
| Click_Conversion_03 | Number of click conversions for type 3 |
| Click_Conversion_Revenue_03 | Revenue from click conversions for type 3 |
| View_Through_Conversion_03 | Number of view-through conversions for type 3 |
| View_Through_Conversion_Revenue_03 | Revenue from view-through conversions for type 3 |
| Click_Conversion_04 | Number of click conversions for type 4 |
| Click_Conversion_Revenue_04 | Revenue from click conversions for type 4 |
| View_Through_Conversion_04 | Number of view-through conversions for type 4 |
| View_Through_Conversion_Revenue_04 | Revenue from view-through conversions for type 4 |
| Click_Conversion_05 | Number of click conversions for type 5 |
| Click_Conversion_Revenue_05 | Revenue from click conversions for type 5 |
| View_Through_Conversion_05 | Number of view-through conversions for type 5 |
| View_Through_Conversion_Revenue_05 | Revenue from view-through conversions for type 5 |
| Click_Conversion_06 | Number of click conversions for type 6 |
| Click_Conversion_Revenue_06 | Revenue from click conversions for type 6 |
| View_Through_Conversion_06 | Number of view-through conversions for type 6 |
| View_Through_Conversion_Revenue_06 | Revenue from view-through conversions for type 6 |
Ad Group Dimensions Schema
| Field | Description |
|---|---|
| AdBrainHouseholdCrossDeviceEnabled | Whether household cross-device targeting is enabled |
| AdGroupId | The unique identifier of the ad group |
| AdGroupName | The name of the ad group |
| AreFutureKoaFeaturesEnabled | Whether future KOA features are enabled |
| AssociatedBidLists | List of associated bid lists |
| Availability | Availability status of the ad group |
| CampaignId | The parent campaign identifier |
| ChannelId | The channel identifier |
| ComscoreSettings | JSON object with Comscore measurement settings |
| ContractTargeting | JSON object with contract targeting settings |
| CreatedAtUTC | Timestamp when the ad group was created |
| CreativeIds | List of creative IDs associated with the ad group |
| CurrentAndFutureAdditionalFeeCards | List of additional fee cards |
| CustomLabels | List of custom labels applied to the ad group |
| Description | Description of the ad group |
| DimensionalBiddingAutoOptimizationSettings | List of bidding optimization settings |
| DisplayViewabilityStandardIntegral | Standard for display viewability |
| FunnelLocation | Location in the marketing funnel |
| Increments | List of bidding increments |
| IndustryCategoryId | Industry category identifier |
| IsEnabled | Whether the ad group is enabled |
| IsHighFillRate | Whether high fill rate is enabled |
| IsUseClicksAsConversionsEnabled | Whether clicks are counted as conversions |
| IsUseSecondaryConversionsEnabled | Whether secondary conversions are enabled |
| KoaOptimizationSettings | JSON object with KOA optimization settings |
| KoaOptimizationsVersion | Version of KOA optimizations |
| LastUpdatedAtUTC | Timestamp when the ad group was last updated |
| NielsenSettings | JSON object with Nielsen measurement settings |
| PredictiveClearingEnabled | Whether predictive clearing is enabled |
| QualityAllianceViewabilityProfile | Viewability profile for quality alliance |
| ROIGoal | JSON object with ROI goal settings |
| RTBAttributes | JSON object with real-time bidding attributes |
| UseIdentityAlliance | Whether identity alliance is used |
| VideoViewabilityStandardIntegral | Standard for video viewability |
Campaign Dimensions Schema
| Field | Description |
|---|---|
| AdvertiserId | The advertiser account identifier |
| AssociatedBidLists | List of associated bid lists |
| AutoAllocatorEnabled | Whether auto allocator is enabled |
| AutoPrioritizationEnabled | Whether auto prioritization is enabled |
| Availability | Availability status of the campaign |
| BudgetAmount | Budget amount for the campaign |
| BudgetCurrencyCode | Currency code for the budget |
| BudgetInImpressions | Budget expressed in impressions |
| CampaignConversionReportingColumns | JSON object with conversion reporting column settings |
| CampaignFlights | JSON object with campaign flight settings |
| CampaignId | The unique identifier of the campaign |
| CampaignName | The name of the campaign |
| CampaignType | Type of campaign |
| CreatedAtUTC | Timestamp when the campaign was created |
| CtvTargetingAndAttribution | Whether CTV targeting is enabled |
| CurrentAndFutureAdditionalFeeCards | List of additional fee cards |
| CustomCPAClickWeight | Click weight for custom CPA |
| CustomCPAType | Type of custom CPA |
| CustomCPAViewthroughWeight | View-through weight for custom CPA |
| CustomLabels | List of custom labels applied to the campaign |
| CustomROASType | Type of custom ROAS |
| DailyBudgetAmount | Daily budget amount |
| DailyBudgetCurrencyCode | Currency code for daily budget |
| DailyBudgetInImpressions | Daily budget expressed in impressions |
| DefaultBidLists | List of default bid lists |
| Description | Description of the campaign |
| EndDate | End date of the campaign |
| FrequencySettings | JSON object with frequency cap settings |
| Increments | List of bidding increments |
| IsBallotMeasure | Whether campaign is a ballot measure |
| LastUpdatedAtUTC | Timestamp when the campaign was last updated |
| MinimumAdGroupSpendInAdvertiserCurrency | Minimum ad group spend |
| Objective | Campaign objective |
| PacingMode | Mode of budget pacing |
| PartnerCostPercentageFee | Partner cost percentage fee |
| PartnerCPCFee | JSON object with partner CPC fee settings |
| PartnerCPMFee | JSON object with partner CPM fee settings |
| PrimaryChannel | Primary channel for the campaign |
| PrimaryGoal | JSON object with primary goal settings |
| PurchaseOrderNumber | Purchase order number |
| StartDate | Start date of the campaign |
| TimeZone | Time zone for the campaign |
Creative Dimensions Schema
| Field | Description |
|---|---|
| AdvertiserId | The advertiser account identifier |
| Availability | Availability status of the creative |
| CreatedAtUTC | Timestamp when the creative was created |
| CreativeAuditStatuses | List of creative audit statuses |
| CreativeId | The unique identifier of the creative |
| CreativeName | The name of the creative |
| CreativeType | Type of creative |
| Description | Description of the creative |
| FlightEndDateUTC | End date of the creative flight |
| FlightStartDateUTC | Start date of the creative flight |
| ImageAttributes | JSON object with image attributes |
| LastUpdatedAtUTC | Timestamp when the creative was last updated |
| PoliticalDataId | Political data identifier |
| ShareLink | Link for sharing the creative |
| WillThisBeServedInChina | Whether the creative will be served in China |
All Metrics Performance Schema
| Field | Description |
|---|---|
| Date | Date for the metrics |
| Advertiser | Name of the advertiser |
| Advertiser_ID | The advertiser account identifier |
| Campaign | Name of the campaign |
| Campaign_ID | The campaign identifier |
| Ad_Group | Name of the ad group |
| Ad_Group_ID | The ad group identifier |
| Device_Type | Type of device (Desktop, Mobile, etc.) |
| Creative | Name of the creative |
| Creative_ID | The creative identifier |
| Ad_Format | Format of the ad |
| Impressions | Number of impressions served |
| Advertiser_Cost_USD | Cost in USD |
| Clicks | Number of clicks received |
| Sampled_Viewed_Impressions | Number of sampled viewed impressions |
| Sampled_Tracked_Impressions | Number of sampled tracked impressions |
| Player_25_Percent_Complete | Number of videos viewed to 25% completion |
| Player_50_Percent_Complete | Number of videos viewed to 50% completion |
| Player_75_Percent_Complete | Number of videos viewed to 75% completion |
| Player_Completed_Views | Number of videos viewed to completion |
5. Troubleshooting & FAQs for The Trade Desk
Common Issues & Error Messages
Authentication Failures
- Error: "Invalid credentials" or "Authentication failed"
- Solution: Verify your API username and password. Ensure they are correctly entered without any leading or trailing spaces. If you're using a Long-Lived Access Token, verify that it hasn't expired.
Advertiser ID Issues
- Error: "Advertiser not found" or "Invalid advertiser ID"
- Solution: Verify that your Advertiser ID is correct. Ensure you have the appropriate permissions to access the specified advertiser account.
Missing Data
- Common Causes:
- Date range outside of data availability
- No activity for the selected template dimensions
- Permissions issues with specific advertisers or campaigns
- Solution: Verify that data exists for the selected date range in The Trade Desk UI. Ensure your API credentials have access to the advertisers and campaigns you're trying to extract data from.
Contact & Support Information
- Nodus Support: support@nodus.com
Best Practices for The Trade Desk Connections
- Use a Long-Lived Access Token instead of username/password authentication when possible
- For Ad Group Performance reports, be aware that conversion metrics are tracked at multiple touchpoints (01-06 suffixes in the data)
- The All Metric Performance template provides a more streamlined view with key metrics for most analyses
- Start with smaller date ranges (7-28 days) for initial extractions to validate data quality
- For video campaigns, focus on the various Player completion metrics (25%, 50%, 75%, 100%) to understand engagement
- Monitor API usage to avoid hitting rate limits, especially during peak campaign periods