Twitter Data Connector

Learn how Singular pulls data from Twitter and displays it in your reports.


Quick Details

Data Connector Technology API (Twitter API version 9 - see documentation)
Data breakdown (segmentation)

Data from Twitter is always broken down by:

  • Campaign
  • Sub-campaign (line item)

In addition, you can get one of the following breakdowns:

  • Platform (default)
  • Country + City
  • Country + Region
  • Country + DMA Name
  • Age
  • Gender

If you're interested in getting geographic location instead of platform breakdown, reach out to your Customer Success Manager or Singular support and specify whether you want the user's City, Region, or DMA.

Note: Twitter does not provide publisher breakdown.

How far back we pull data 30 days
Time zone Defined by the customer per account
Is data available on the creative level? Yes
Does Singular show your creative assets? Yes - including images, videos, and streaming videos.
Singular does not show Polls.
Known Limitations/ Issues
  • Twitter does not provide Publisher breakdown.
  • Singular can't show Scheduled Tweets before the tweet is live. We pull them when/if they go live.
  • There are no install statistics per creative.
  • Metrics on the Creative level do not always match metrics pulled on the Sub-Campaign level (Twitter's Line Item).
  • There may be discrepancies between Twitter’s platform breakdown report and Twitter’s country breakdown report.

To learn more about internal discrepancies in Twitter data, see Twitter's article on the subject.

Data Mapping

Terminology Notes:

  • Sub-Campaign in Singular corresponds to Twitter's Line Item.
  • Creative in Singular can correspond to Twitter's Tweet, Promoted Tweet, Card, or Media Creative
  • Metrics are pulled from Twitter's Line Item, Promoted Tweet, and Media Creative objects.
  • The geographic location dimensions (Country, Region, City, DMA Name) are available only if you've requested to get location instead of platform breakdown (see "Data breakdown" above).

For a description of each field in Singular, see Metrics and Dimensions.

Field in Singular UI Field in Singular API Field in Twitter
Account ID adn_account_id Account_object: id
Account Name adn_account_name Account_object: name
Agency agency Not pulled directly from Twitter, but Singular can set the agency per each account.
App Site ID app_site_id Estimated based on any URLs available in creative-related objects (Tweets,  Promoted Tweets, Cards, Media Creatives, Account Medias). If not possible, we try to estimate based on campaign URLs and Line Item URLs.
Campaign URL adn_campaign_url
  • Pulled from a Card object related to a Tweet related to a Line Item in the campaign.
  • The field is "website_dest_url" in Twitter API v. 6.0 but if that is not populated we look under old field names: “website_url", "website_shortened_url", "media_url". 
  • If there was no Card, we look for the "landing_url" field in a Media Creative object.
Country country_field We query the Twitter API with segment_by=”LOCATIONS”, and take the segment name for each Line Item and Promoted Tweet.
Creative Reported URL creative_reported_url  
Date date_field Since the Singular data connector pulls daily reports, we add the date ourselves.
DMA Name
Same as Campaign URL
Network Campaign ID adn_campaign_id "id" in the Campaign object
Network Campaign Name adn_campaign_name "name" in the Campaign object
Network Creative ID adn_creative_id Depends on the type of the creative.
  • If the creative is a Promoted Tweet: "tweet_id" in the Promoted Tweet object
  • If the creative is a Media Creative: "id" in the Account Media object.
Network Creative Name adn_creative_name Take the "media id" from the Card object and query Twitter for the media "name".
Network Sub Campaign ID adn_sub_campaign_id "id" in the Line Item object
Network Sub Campaign Name adn_sub_campaign_name "name" in the Line item object
Platform platform
  • This is only available if you have asked Singular to receive the Platform breakdown instead of the Country breakdown.
  • We query the Twitter API with segment_by=”PLATFORMS”, and take the segment name for each Line Item and Promoted Tweet.
Public Id site_public_id "googleplay_app_id" or "iphone_app_id" in the Card object, if available.
Sub Ad Network adn_subadnetwork
  • Set to "twitterfeed" if the data was queried from "ALL_ON_TWITTER"
  • Set to "twittertpn" if the data was queried from "PUBLISHER_NETWORK"
Target Countries target_countries_str For each sub-campaign (line item), we pull "countries" from the /targeting_criteria endpoint. We concatenate the results into this field.
Text creative_text Depending on the type of the creative, either "name" from the Card object, "text" from the Tweet object, or "media_name" from the Account Media.
Timezone adn_timezone "timezone" in the Account object
Age age AGE
Gender gender GENDER
Average Frequency
frequency average_frequency
comments replies
likes likes
Network Clicks adn_clicks “clicks”
Network Impressions adn_impressions "impressions"
Network Installs adn_installs "mobile_conversion_installs"
Original Cost adn_original_cost "billed_charge_local_micro"
Original Currency adn_original_currency “currency” in the Campaign object
Page Follows
page_follows follows
reach total_audience_reach
shares retweets
Video Views video_views “video_total_views”
Completed Video Views completed_video_views “video_views_100”
Video Views - 25% video_views_25pct “video_views_25”
Video Views - 50% video_views_50pct “video_views_50”
Video Views - 75% video_views_75pct “video_views_75”