Third-party geo data segments and rates

If you’re a geo data provider who has already designed your data taxonomy, your next step is to organize your data segments into elements and create your taxonomy in The Trade Desk Data Management Platform (DMP). Here's what you need to know:

• All platform endpoints require API token authentication and do not require secret keys.
• You can onboard data for more than one brand or advertiser, but you will need to complete a separate initial setup for all of them. For details, see Getting started for geo data providers.
• Geography data can include time slots to define when specific areas should be active.

Workflow diagram

The following diagram illustrates the process outlined in the next section, which includes links to the respective step-by-step instructions and also provides additional guidance on the decisions you might need to make along the way.

Process overview

Before you can create your geo segments and assign rates to them, be sure to complete the following tasks:

Initial setup
Design your taxonomy

The following table outlines the process step by step, while the diagram in the preceding section illustrates the decision-making workflow.

IMPORTANT: The listed endpoints are part of Platform APIs that require different authentication than the Data APIs. For details on creating long-lived and short-lived API tokens, see Authentication.

Create data elements

To create data elements and set up your taxonomy, use the POST /v3/thirdpartydata endpoint from the Platform API suite for each non-root segment in the taxonomy that you have designed.

The following table explains the properties required for creating a data element for either syndicated or custom taxonomy. For a complete reference, see POST /v3/thirdpartydata.

TIP: To facilitate the process of creating data elements for your taxonomy, be sure to have your taxonomy design table for reference.

Display name guidelines

When naming your segments during integration, the DisplayName value must reflect the full path of the segment, which determines both how it appears in the DMP UI and how buyers can find it. For example: In-Market > Travel > Flights > First Class. After your data segments are fully integrated, advertisers will see only the final element in the path—the part after the last greater-than symbol (>). In this example, they would see First Class. For details, see Third-party data taxonomy design.

The value is immutable after it is set. Here are the syntax and content guidelines for creating an effective DisplayName value:

• Use the full path of a segment as a display name.
• Use only greater-than symbols (>) and spaces to separate the path elements.
• Do not include tabs or special characters such as ', ", or ^.
• Use clear, descriptive names and avoid meaningless strings, such as random letters or numbers or placeholders like PROVIDER_NAME or Custom Segment 1234.
• Avoid sensitive terms. Segments containing them may be rejected. For details, see Sensitive categories.

To increase relevance and help advertisers better understand your segments, do the following:

• Ensure the users in your segment match the segment name.
• Build smaller, more targeted segments. For example, instead of having a segment called NY Restaurant Goers, divide it into more specific groups like NY Italian Restaurant Goers and NY Thai Restaurant Goers.

Sensitive categories

The Trade Desk may reject data segments if the DisplayName and Description properties contain terms from sensitive categories. Generally, at this time, the categories The Trade Desk considers sensitive include health conditions, ethnicity, race, religious affiliation, union membership, crime victim status, children's data, and sexual orientation. For details, see Check data change status.

Taxonomy example

The following diagram is a snippet that illustrates the First Class data element from the condensed taxonomy example in Third-party data taxonomy design.

Create data element request

Here's an example of a POST /v3/thirdpartydata request to create the First Class data element from the preceding syndicated taxonomy example.

{
  "ProviderId": "providerXYZ",
  "ProviderElementId": "cj3r",
  "ParentElementId": "ROOT",
  "DisplayName": "In-Market > Travel > Flights > First Class",
  "Buyable": true,
  "Description": "Users currently in market for first-class flights."
}

Here's an example of a POST /v3/thirdpartydata request to create the same data element from a custom taxonomy.

{
  "ProviderId": "providerXYZ",
  "ProviderElementId": "cj3r",
  "ParentElementId": "CUSTOM",
  "DisplayName": "In-Market > Travel > Flights > First Class",
  "Buyable": true,
  "Description": "Users currently in market for first-class flights."
}

After you create all data elements in your taxonomy, assign data rates to buyable segments. Here's what you need to know:

• You can check the approval status two hours after segment creation.
• You can assign rates to data segments that are pending approval.

IMPORTANT: Be sure to assign a rate to your data element within 2 hours of creating it.

Assign geolocations to elements

You can onboard the following geo data types:

• Radiuses
• ZIP codes or postal codes

The following sections provide instructions on how to add different geo data types to data elements.

Radiuses

IMPORTANT: The maximum number of radiuses per request is 10,000.

To add a radius to a geo segment, use the POST /v3/geotargetsegment/addgeotargets/{providerId}/{providerElementId} endpoint.

Here's an example of how to add radiuses.

{
  "Points": [
    {
      "LngDeg": 65.821370,
      "LatDeg": -82.327429,
      "RadMet": 3000
    },
    {
      "LngDeg": -17.600772,
      "LatDeg": -66.155554,
      "RadMet": 3000
    }
  ]
}

Radius distance limits

The following table lists the distance limitations for radius geo data.

IMPORTANT: If you are setting a radius with a distance of over 20,000 meters be sure to consult your Technical Account Manager.

TIP: If you want to set a wide radius that exceeds any of these limitations, consider using postal or ZIP code data. Postal codes and ZIP codes allow for more flexibility in targeting because they rely on IP addresses instead of latitude and longitude coordinates.

Postal codes or ZIP codes

To add postal codes or ZIP codes to a data element, use the PUT /v3/geoevent endpoint and set the GeoEventId property to the ProviderElementId value of the data element to which you want to add the codes.

Here's an example of adding two ZIP codes to a data element.

{
  "GeoEventId": "PROVIDER_ELEMENT_ID_PLACEHOLDER",
  "ProviderId": "DATA_PROVIDER_ID_PLACEHOLDER",
  "GeoEventLocations": [
    {
      "CountryCode": "US",
      "PostalCode": "98052"
    },
    {
      "CountryCode": "US",
      "PostalCode": "37601"
    }
  ]
}

Assign rates to data elements

To assign rates to data elements in your taxonomy, use the POST /v3/datarate/batch endpoint from the Platform API suite and update all the buyable segments in the taxonomy as a batch.

IMPORTANT: If a buyable segment does not have a rate or users assigned to it, it will not appear in the DMP.

Rate requirements

Here’s what you need to know about assigning data rates:

• Data rates must be assigned as hybrid rates that use a percentage of media cost with a maximum CPM cap.
• Assign rates only to the buyable segments (data elements with buyable set to true) from your taxonomy unless your taxonomy utilizes rate-inheritance.
• If a buyable segment does not have a rate assigned directly or a rate assigned to its parent, it will not appear in The Trade Desk Data Management Platform (DMP).
• A batch can include a maximum of 5000 rates.
• Be sure to assign each segment to only one brand.

Taxonomy-specific rate requirements

Here's what you need to know about taxonomy-specific rate requirements:

• To specify eligible buyers for your segments, you must to set the rate level based on your taxonomy type: system rate level for syndicated taxonomies and partner or advertiser rate levels for custom taxonomies.
• The integration process is the same for both syndicated and custom taxonomies, except for the RateLevel property values: System for syndicated taxonomies and Partner or Advertiser for custom taxonomies.
• Depending on the rate level, custom taxonomies also require a partner or advertiser ID.

NOTE: You can always update your rates later.

For details, see Third-party data rates.

Data Rates object

The following table explains the DataRates object properties required for creating a data rate batch for either syndicated or custom taxonomy, using your provider ID. For a complete reference, see POST /v3/datarate/batch.

TIP: To facilitate the process of assigning rates, be sure to have a list of all the buyable segments from your taxonomy design table for reference. For details, see Third-party data taxonomy design.

Syndicated taxonomy request

The following is an example of a POST /v3/datarate/batch request to create a rate batch for a syndicated taxonomy.

{
  "ProviderId": "providerXYZ",
  "DataRates": [
    {
      "ProviderElementId": "cj3r",
      "BrandId": "yourBrandID",
      "RateLevel": "System", // Indicates a syndicated taxonomy intended for all buyers.
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.14,
      "CPMRate": {
        "Amount": 2.50,
        "CurrencyCode": "USD"
      }
    },
    {
      "ProviderElementId": "dk4s",
      "BrandId": "yourBrandID", 
      "RateLevel": "System", // Indicates a syndicated taxonomy intended for all buyers.
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.16,
      "CPMRate": {
        "Amount": 3.00,
        "CurrencyCode": "USD"
      }
    }
  ]
}

Custom taxonomy request

The following is an example of a POST /v3/datarate/batch request to create a rate batch for a custom taxonomy.

{
  "ProviderId": "providerXYZ",
  "DataRates": [
    {
      "ProviderElementId": "2130",
      "BrandId": "yourBrand1ID",
      "RateLevel": "Partner", // Indicates a custom taxonomy intended only for the specified partner and their advertisers.
      "PartnerId": "partnerXYZ", // Indicates the partner to which the data element is assigned.
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.14,
      "CPMRate": {
        "Amount": 2.50,
        "CurrencyCode": "USD"
      }
    },
    {
      "ProviderElementId": "2133",
      "BrandId": "yourBrand1ID", 
      "RateLevel": "Partner", // Indicates a custom taxonomy intended only for the specified partner and their advertisers.
      "PartnerId": "partnerXYZ", // Indicates the partner to which the data element is assigned.
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.16,
      "CPMRate": {
        "Amount": 3.00,
        "CurrencyCode": "USD"
      }
    }
  ]
}

TIP: To check the processing of your data rate batch, send a GET /v3/datarate/batch/{batchId} request with the BatchId returned in the response from the POST /v3/datarate/batch request.

For details on the rate processing queue eligibility period, syndicated taxonomy approval status, and other details, see Third-party data rates. See also Manage data elements and rates.

Manage geo data elements and rates

After you have completed your third-party data integration, you may need to retrieve the taxonomy and data rate details or update them. The following table lists the common management tasks for data elements and rates.

Retrieve brand details

To retrieve a list of brands for your provider ID, for example, to look up a brand ID when assigning rates, use the GET /v3/datarate/brands/{providerId} endpoint.

The following is an example of a GET /v3/datarate/brands/{providerId} body response.

[
  {
    "LogoUrl": "https://s3.amazon.com...",
    "BrandId": "yourBrand1ID",
    "BrandName": "Brand One"
  },
  {
    "LogoUrl": "https://s3.amazon.com...",
    "BrandId": "yourBrand2ID",
    "BrandName": "Brand Two"
  },
  {
    "LogoUrl": "https://s3.amazon.com...",
    "BrandId": "yourBrand3ID",
    "BrandName": "Brand Three"
  }
]

Retrieve taxonomy details

To retrieve a paged list of segments, for example, to view their relationships in the taxonomy or to look up a ProviderElementId value to use as a ParentElementId for a new segment, use the POST /v3/thirdpartydata/query endpoint.

Request example

The following is a POST /v3/thirdpartydata/query request body example of how to retrieve a paged list of segments.

{
  "ProviderId": "providerXYZ",
  "PageStartIndex": 0,
  "PageSize": 50
}

Response example

The following is a POST /v3/thirdpartydata/query response body example with a paged list of segments. Note that the last segment has the sensitive term "peanuts" in the Description property, which led to the denial of segment compliance approval.

{
  "Result": [
    {
      "ThirdPartyDataId": 12345678,
      "TaxonomyComplianceStatus": "Approved", 
      "ProviderId": "providerXYZ",
      "ProviderElementId": "ax7m",
      "ParentElementId": "ROOT",
      "DisplayName": "In-Market > Travel > Car Rentals",
      "Buyable": false,
      "Description": null,
      "AudienceSize": null
    },
    {
      "ThirdPartyDataId": 98745632,
      "TaxonomyComplianceStatus": "Approved", 
      "ProviderId": "providerXYZ",
      "ProviderElementId": "bt9q",
      "ParentElementId": "ROOT",
      "DisplayName": "In Market > Travel > Destinations",
      "Buyable": false,
      "Description": null,
      "AudienceSize": null
    },
    {
      "ThirdPartyDataId": 45632178,
      "TaxonomyComplianceStatus": "Pending",
      "ProviderId": "providerXYZ",
      "ProviderElementId": "cj3r",
      "ParentElementId": "ROOT",
      "DisplayName": "In-Market > Travel > Flights > First Class",
      "Buyable": false,
      "Description": null,
      "AudienceSize": null
    },
     {
      "ThirdPartyDataId": 78932174,
      "TaxonomyComplianceStatus": "Denied", 
      "ProviderId": "providerXYZ",
      "ProviderElementId": "dk4s",
      "ParentElementId": "ROOT",
      "DisplayName": "In-Market > Travel > Flights > Economy Class",
      "Buyable": true,
      "Description": null,
      "AudienceSize": null
    }
  ],
  "ResultCount": 4,
  "TotalFilteredCount": 4,
  "TotalUnfilteredCount": 4
}

Retrieve individual data element details

To retrieve details for a specific segments, for example, to look up the buyable status or a ParentElementId value when creating a sibling segment, use the POST /v3/thirdpartydata/query endpoint.

Request example

The following is a POST /v3/thirdpartydata/query request body example of how to retrieve a specific segment.

{
  "ProviderId": "providerXYZ",
  "ProviderElementId": "el5t",
  "PageStartIndex": 0,
  "PageSize": 1
}

Response example

The following is a POST /v3/thirdpartydata/query response body example with details of a specific segment.

{
  "Result": [
    {
      "ThirdPartyDataId": 78932174,
      "TaxonomyComplianceStatus": "Approved",
      "ProviderId": "providerXYZ",
      "ProviderElementId": "el5t",
      "ParentElementId": "ROOT",
      "DisplayName": "In-Market > Travel > Flights > Business Class",
      "Buyable": true,
      "Description": "Users who have recently looked for web hosting services.",
      "AudienceSize": null
    }
  ],
  "ResultCount": 1,
  "TotalFilteredCount": 1,
  "TotalUnfilteredCount": 1
}

Retrieve data rate details

To retrieve a paged list of all data rates for your provider ID or the rate details for an individual data element, use the POST /v3/datarate/query endpoint.

The following is a POST /v3/datarate/query request body example of how to retrieve a paged list of all data rates in a custom taxonomy.

IMPORTANT: To use this query, you must have a brand ID. To retrieve a list of available brand IDs for your provider ID, use the POST /v3/datarate/brands/{providerId} endpoint.

{
  "BrandId":"brandXYZ",
  "ProviderId": "providerXYZ",
  "RateLevel": "Partner", // Indicates a custom taxonomy intended only for the specified partner and their advertisers.
  "PageStartIndex": 0,
  "PageSize": 10
}

The following is a POST /v3/datarate/query request body example of how to retrieve data rates for a specific segment in a syndicated taxonomy.

{
  "BrandId":"brandXYZ",
  "ProviderId": "providerXYZ",
  "ProviderElementIds": [
    "1113"
  ],
  "RateLevel": "System", // Indicates a syndicated taxonomy intended for all buyers.
  "PageStartIndex": 0,
  "PageSize": 1
}

Remove third-party data segments

NOTE: To remove third-party data segments from a custom taxonomy for a specific partner or advertiser, contact your Technical Account Manager and Data Partnerships lead. Segments will be deleted from all data groups for the specified partners or advertisers. Note that segment removal requires a standard advance client notification of 30 days, with any non-standard notification timelines evaluated on a case-by-case basis.

To remove a third-party data segment from a syndicated or custom taxonomy, complete the following steps.

To remove a segment from the DMP, set its Buyable property to false. Non-buyable segments cannot appear in the DMP and cannot be added to new data groups for targeting.

NOTE: Data groups where the segment was previously assigned can still use the segment for targeting.

The following is a PUT /v3/thirdpartydata request body example that shows how to make a segment non-buyable.

{
  "ProviderId": "providerXYZ",
  "ProviderElementId": "fm6u",
  "Buyable": false
}

Check data change status

Two hours after segment creation, use the POST /v3/thirdpartydata/query endpoint to check its taxonomy compliance status. This endpoint retrieves a list of data elements, each with a TaxonomyComplianceStatus property indicating its compliance status. For details, see Retrieve taxonomy details.

The following table describes each value in the TaxonomyComplianceStatus property.

NOTE: You can also use the GET /v3/thirdpartydata/status/{providerId}/{providerElementId} endpoint to check the compliance status of an individual segment.

If the approval status is set to Denied, check if the data element contains sensitive terms. If the data element contains sensitive terms but otherwise its data complies with your contract, re-word the segment display name and description to exclude sensitive terms. If you are an onboarder, coordinate with your brands.

IMPORTANT: You cannot edit the denied segment for approval. You must submit a new segment, along with new rates.

FAQs

The following is a list of commonly asked questions about geo data integrations.

How long does it take before changes are reflected in targeting?

Be sure to include at least a 12-hour buffer for the latest changes to be reflected in targeting.

Do advertisers need to use the DMP to access my geo segments?

No. Advertisers can find and add your geo segments using the platform UI, without accessing the DMP.

How should I maintain radius data?

The Trade Desk recommends creating geofences only around active locations. For example, if your segment includes 100 store locations but 40 are closed, create geofences for only the 60 that remain open.

Is there a limit on radius sizes?

Yes. For details, see Radius distance limits.

Will using less precise coordinates for radiuses add to the overall targeting area?

The radius remains the same in total size, and targets the area based on the precision set for the coordinates, truncating trailing zeroes. For example, a radius with coordinates (40.3, 50.2) is the same as if you had specified (40.3000, 50.2000).

Is the search area for device coordinates scaled according to the supplied precision?

No. A radius is considered a match only if a supplied coordinate is in the exact latitude, longitude, and meter radius provided. Device coordinates with low precision do match any segment.