The Zoomph Partner Mention API is made available to provide metrics for owned and operated social and streaming accounts.
Introduction
The Zoomph Partner Mention API is made available to content right-holders to provide insight into how content associated with the right-holders is creating brand exposures for their partners/sponsors. The data returned from the API can be integrated into internal data warehouse or data lake repositories for the purpose of surfacing business intelligence reports on measuring the performance of branded or organic sponsor placement. Data from this API cannot be redistributed in any form.
Zoomph identifies sponsor exposures by determining either text mentions of the sponsor in the social media post or by determining presence of brand logos of the sponsor in photo, video or streaming media. Additionally, brand placement can also be tracked in the Zoomph platform.
The API provides the following metrics back:
- Impressions
- Video Views
- Engagement
- Image/Video metrics, if the exposure was from photo, video or streaming media
- Brand exposure value
To use this API, please contact your Zoomph Account Manager. Once the API is provisioned, you will be provided an Access Token to use to validate any API calls you make. The API will be subject to a rate limit starting from 10 calls per minute.
API Specification – Report Request
Path
https://api.zoomph.com/partnermention/report
Query String Parameters
None
Method
The search criteria is passed in via a JSON POST.
Request Payload
All fields are required except GranularDetection which is optional.
GranularDetection has the following options – “True” – every detected logo will be returned in the output and “False” which is the default where a consecutive exposures of a logo will be aggregated together.
{
"Partners": "...", //Array of partners to process
"FeedId": "...", //Numeric id of the Zoomph feed to process
"Query": "...", //Query DSL to filter feed content if needed
"GranularDetection": "...", //Option to extract every granular logo detected
}
Sample Response
POST https://api.zoomph.com/partnermention/report?access_token=yourAccessTokenHere
POST Data (JSON)
{
"Partners": ["adidas","coca-cola"],
"FeedId": 65405,
"Query":"created>2019-07-27T01:00:00Z AND created<2019-08-06T01:00:00Z"
}
Response
{
"ReportId": 32,
"Message": "Your report is being generated."
}
API Specification – Report Results
The API returns text mentions by searching for brands labelled using the TEXT MENTION tag group and returns brand logo exposure by searching for brands labelled using the LOGO AI tag group. For example querying “Nike” as a ‘Partner’ will identify all posts in the selected feed that are tagged as TEXT MENTION:Nike or LOGO AI:Nike and return all possible Nike exposures that meet the query filter criteria.
For a single video post, a brand might have multiple logo exposures – the API treats each such exposure as a unique atomic output.
Path
https://api.zoomph.com/partnermention/report/{report id}
https://api.zoomph.com/partnermention/report/{report id}/csv
Query String Parameters
Fields to request (optional). Note this is not required for the CSV endpoint.
|
Field |
Data Type |
Description |
|
Id |
Integer |
Zoomph unique identifier for exposure |
|
Partner |
String |
Name of partner |
|
PartnerMentionType |
String |
Type of exposure – text mention or detected logo |
|
ServiceType |
String |
Social media channel – Twitter, Facebook, Instagram, YouTube, Twitch |
|
ServiceId |
String |
Identifier of social media post |
|
PartnerExposureCreator |
String |
This identifies the creator of the partner exposure |
|
PartnerExposureCreatorName |
String |
Name of the creator of the partner exposure |
|
PartnerExposureDate |
DateTime |
Date when the partner exposure happened |
|
Message |
String |
Associated text of the post which created the partner exposure.
For Twitter, this field is not available for unauthenticated profiles as per Twitter Terms-of-service. If the author of the tweet is authenticated in the Zoomph account, then this field will be populated |
|
ContentType |
String |
Text, Photo or Video |
|
Url |
String |
Link to social media post.
For Twitter, this field is not available for unauthenticated profiles as per Twitter Terms-of-service. If the author of the tweet is authenticated in the Zoomph account, then this field will be populated |
|
Verified |
Boolean |
Flag indicating if verified account (Twitter only) |
|
FollowerCount |
Integer |
Number of followers of poster |
|
FollowerInteractionRate |
Float |
Number of Engagements / FollowerCount |
|
Impressions |
Long |
Impressions of social media post. This field is used if the poster authenticates with Zoomph |
|
ProjectedImpressions |
Long |
Projected impressions of social media post using statistical regression. This field is used if the poster does not authenticate with Zoomph |
|
RetweetCount |
Integer |
Number of retweets of the post. For Twitter tweets
This field is not available for unauthenticated profiles as per Twitter Terms-of-service. If the author of the tweet is authenticated in the Zoomph account, then this field will be populated |
|
LikeCount |
Integer |
Number of likes of the post
This field is not available for unauthenticated profiles as per Twitter Terms-of-service. If the author of the tweet is authenticated in the Zoomph account, then this field will be populated |
|
ReplyCount |
Integer |
Number of replies to the post. For Twitter and Instagram Stories
This field is not available for unauthenticated profiles as per Twitter Terms-of-service. If the author of the tweet is authenticated in the Zoomph account, then this field will be populated |
|
CommentCount |
Integer |
Number of comments to the post. Applies to Instagram, Facebook and YouTube content |
|
ViewCount |
Integer |
Number of video views to the post. |
|
LoveCount |
Integer |
Number of love reactions. Applies to Facebook content |
|
ShareCount |
Integer |
Number of shares of the post. Applies to Facebook content |
|
WowCount |
Integer |
Number of wow reactions. Applies to Facebook content |
|
HahaCount |
Integer |
Number of haha reactions. Applies to Facebook content |
|
SadCount |
Integer |
Number of sad reactions. Applies to Facebook content |
|
AngryCount |
Integer |
Number of angry reactions. Applies to Facebook content |
|
AverageConcurrentViewers |
Integer |
Average number of live viewers sampled at 10 minute intervals across the duration of a live stream. This applies to Twitch streams and YouTube live content only |
|
IsProrated |
Boolean |
Indicates if the Live Streaming broadcasts was sampled for Vision AI processing. |
|
AnalyzedProratedSeconds |
Integer |
Number of seconds of sample used for proration (see IsProrated flag) |
|
BrandExposureValue |
Long |
Discounted exposure for the partner/brand exposure |
|
HoursWatched |
Long |
Number of hours watched for a live broadcast = Average Concurrent Viewers x Stream Duration in Hours |
|
VideoTotalSeconds |
Float |
Total duration of video or live broadcast |
|
LogoAverageClarity |
Float |
Average clarity of logo of partner |
|
LogoAverageSize |
Float |
Average size of logo of partner in relation to total screen size. This is valid only for image/video detected logos. |
|
LogoStartSeconds |
Float |
Start time in seconds on when the logo was shown. This is valid only for image/video detected logos. |
|
LogoEndSeconds |
Float |
End time in seconds on when the logo was shown. This is valid only for image/video detected logos. |
|
LogoTotalSeconds |
Float |
Exposure time in seconds on when the logo was shown. This is valid only for image/video detected logos. |
|
LogoFrameCount |
Float |
Number of frames in which logo was shown. This is valid only for image/video detected logos. |
|
LogoImpressions |
Integer |
Projection of the number of logo impressions for this brand exposure |
|
Mentions |
String |
Comma separated list of social handles mentioned in the post text |
|
Hashtags |
String |
Comma separated list of social hashtags mentioned in the post text |
|
Engagement |
Integer |
Total engagements in the social media post. For Twitter, this includes retweets, likes and replies. For Facebook, this includes reactions and comments. For Instagram, this includes likes, comments and saves. For YouTube, this includes likes, dislikes and comments. |
|
FrameUrl |
String |
Link to frame which contains the brand exposure. This is valid only for image/video detected logos. This link is valid for 30 days from the time of processing. |
|
Language |
String |
Detected language of the post text |
|
ProvinceFips |
String |
FIPS code of Province of origin of post |
|
CountryFips |
String |
FIPS code of Country of origin of post |
|
Sentiment |
String |
Derived sentiment of the text of the post. Possible values are Positive, Negative, Objective |
|
VODViews |
Integer |
Number of video-on-demand video views for the post. For social media video posts from Facebook, Instagram and Twitter – this will match the ViewCount metric |
|
Tags |
String |
Comma separated list of tags associated with the post |
|
LogoAI |
String |
Comma separated list of all logos identified in the frame of the detected logo. Only if granular flag is set |
|
TextMention |
String |
Comma separated list of profiles identified in the text of the post |
|
PartnerAssetLabel |
String |
The asset on which the logo was placed. Value will be blank if not identified. Requires asset detection to be enabled |
|
AssetAI |
String |
Comma separated list of assets identified in the frame of the detected logo. Only if granular flag is set. Requires asset detection to be enabled |
|
LogoOnAssetAI |
String |
Comma separated list of logo+asset combinations identified in the frame of the detected logo. Only if granular flag is set. Requires asset detection to be enabled |
|
ExitsCount |
Integer |
Number of exits for an Instagram Story |
|
TapForwardCount |
Integer |
Number of Tap Forwards for an Instagram Story |
|
TapBackwardCount |
Integer |
Number of Tap Backwards for an Instagram Story |
|
DislikeCount |
Integer |
Number of dislikes for a YouTube video |
|
Reach |
Integer |
Metric for Facebook and Instagram only. Indicates the number of unique impressions for the post |
|
OrganicImpressions |
Integer |
Metric for Facebook only. Indicates the Organic Impressions for the post |
|
PaidImpressions |
Integer |
Metric for Facebook only. Indicates the Paid Impressions for the post |
|
EngagementRate |
Float |
Number of engagements / Number of impressions |
|
FollowersGained |
Integer |
Followers gained during the duration of a live broadcast. Applies to Twitch only |
|
PeakLiveViewerCount |
Integer |
The maximum number of viewers seen at any time during a live broadcast. Applies to Twitch streams and YouTube live streams. |
|
LiveViews |
Integer |
The total number of views gained during a live broadcast. Applies to Twitch and YouTube live |
|
ProjectedVideoViews |
Integer |
An estimate of video views computed using statistical regression if true video views are not available |
|
PostValue |
Float |
An estimate of the media equivalent value for the entire social media post. This is estimated using a CPM, CPE and CPV rate cards and estimates the cost to reach the same audience if a paid channel was used on the same social platform |
|
Interactions |
Integer |
Total number of interactions for Twitter and Facebook content. This is available for authenticated profiles only. |
|
LogoLocation |
String |
Applies if granular flag is set. This indicates the placement of the center of the logo in any of the following cells:
|
|
EngagementAndInteractions |
Integer |
Total number of post engagement and post interactions for Twitter and Facebook content. This is available for authenticated profiles only. |
|
SaveCount |
Integer |
Total number of times the post was saved. This applies to Instagram. |
Method
The search criteria is passed on via a JSON GET.
Request Payload
None
Sample Response 1
GET https://api.zoomph.com/partnermention/report/32 ?access_token=yourAccessTokenHere&fields=Partner&fields=Impressions&fields=ProjectedImpressions&fields=PartnerMentionType&fields=LogoAverageClarity&fields=LogoAverageSize
Response
{
"Report": [
{
"Id": -1578338793,
"Partner": "HyperX Gaming",
"PartnerMentionType": "LogoDetection",
"ServiceType": "Twitch",
"ServiceId": "XXXXXXXX",
"AuthorUsername": "XXXXXXXX",
"AuthorDisplayName": "XXXXXXXX",
"Created": "2020-03-06T00:00:00",
"Message": null,
"ContentType": "Photo",
"Url": "https://www.twitch.tv/videos/XXXXXXXX",
"Verified": null,
"FollowerCount": null,
"Impressions": 7400,
"ProjectedImpressions": null,
"LogoAverageClarity": 0.299744546,
"LogoAverageSize": 0.00582697242
},
{
"Id": -242442226,
"Partner": "HyperX Gaming",
"PartnerMentionType": "LogoDetection",
"ServiceType": "YouTube",
"ServiceId": "XXXXXXXX",
"AuthorUsername": null,
"AuthorDisplayName": "XXXXXXXX",
"Created": "2019-03-29T23:00:00Z",
"Message": "PPL 2019 - Week 1 - Day 1. Enter a fantasy world of ancient technology with a team-based shooter with strategy elements and deep character customization.",
"ContentType": "Video",
"Url": "https://www.youtube.com/watch?v=XXXXXXXX",
"Verified": null,
"FollowerCount": null,
"Impressions": 24275,
"ProjectedImpressions": null,
"LogoAverageClarity": 0.5183167,
"LogoAverageSize": 0.0144021288
},
,
{
"Id": 4361226,
"Partner": "HyperX Gaming",
"PartnerMentionType": "LogoDetection",
"ServiceType": "Twitter",
"ServiceId": "XXXXXXXX",
"AuthorUsername": "XXXXXXXX",
"AuthorDisplayName": "XXXXXXXX",
"Created": "2019-03-29T23:00:00Z",
"Message": null,
"ContentType": "Image",
"Url": null,
"Verified": null,
"FollowerCount": null,
"Impressions": 1451,
"ProjectedImpressions": 24275,
"LogoAverageClarity": 0.3284137,
"LogoAverageSize": 0.0212013287
},
...
]
}
Sample Response 2
GET https://api.zoomph.com/partnermention/report/32/csv?access_token=yourAccessTokenHere
This will provide a CSV download of all fields.