What is API?
The Next Generation Cision Communications Cloud has an API for its Monitoring and Analytics product that allows you to connect PR data in your account to other internal data sets it has access to. Connecting this data via the API allows you to see a broader impact on ROI and make connections between actions other departments are making and PR.
The API connection has specific code developers use to pull data into other systems. Click here to learn more. DEVELOPERS: Click here to learn how Cision's API works.
Using our API, you can get the valuable information you need out of Cision to report on your PR efforts into your own internal reporting and analytics tools. Cision’s API runs off of searches that are already created in Cision, and has the option to return the following:
A list of all articles and their metadata that match a search.
A list of aggregate data from a set of articles that match a search.
Which Metrics Does API Provide?
On a per article level, we have the following metrics available per article in a search:
Date
Mediatype (news/blog/etc.)
Title
URL
Author
Sentiment
Ad Equivalency
Total Social Shares
Shares broken down by outlet (Twitter, Facebook, Pinterest) all fields from your analytics integration (sessions, page views, % new sessions, new users, page views per session, time on page, bounce rate, goal completions, goal value, goal conversion rate, revenue) country, state, city
On an aggregate level, we have the following stats available for the entire set of articles that match a search:
Total mentions
Social shares
Ad equivalency
How Does Cision's API Work?
We comply with our partnership and do not provide readership via API.
In order to support the widest array of business intelligence (BI) tools, we developed our API so that you can pull data from Cision into your apps. We don’t have any direct connectors for other tools with our Cision API, so the development effort to pull from the Cision API and import that data into your system of choice falls on you and your developers.
For Developers
The Next Generation Cision Communications Cloud API uses REST endpoints to return either JSON- or CSV-formatted data. We use token-based authentication, which requires a token to be set in each request header.
Request Throttling Rate:
Requests to the API across all endpoints MAY BE throttled to a maximum of 10 requests per minute (1 request every 6 seconds). Requests which exceed the rate limit MAY receive the standard 429 (Too Many Requests) HTTP response code. Systems implementing a connection to the Cision API will need to handle this response appropriately.
API Access:
The API uses token authentication, provided using your client credentials. You first need an auth token to pass as an HTTP header for each API request. To get this token, POST to https://api.trendkite.com/api/login with the body of the post containing your Cision login username and password. For example: {“username”:<INSERT USERNAME>, “password”:<INSERT PASSWORD>}
An example CURL request for obtaining auth token:
curl -X POST -H "Content-Type: application/json" -d '{"username":"myusername","password":"mypassword"}' https://api.trendkite.com/api/login
If everything is setup properly, the response will be JSON containing a string token such as: {...,"access_token":"o4g0v7a9750d86odujul3o6kauidndbc"}
For subsequent API calls, use this token as an X-Auth-Token header
Example: curl -H "X-Auth-Token: o4g0v7a9750d86odujul3o6kauidndbc" ...
Jsonp is not supported but the more modern and secure alternative CORS is: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing
Example
"https://api.trendkite.com/api/v2.2/totalmentions?s=4045&range-start=2016-07-01T12:08:56.235-0700&range-end=2016-08-01T12:08:56.235-0700&page-num=0&page-size=10&sort=asc"
When viewing the returned information you will notice that readership for non-broadcast and non-print (online articles) will always be 0.
Along with the returned information, there will be a http message url where you can take the url from the header in the response and follow it to get a download that includes the readership data.
This URL expires for security reasons, so you will have 5 minutes to turn around and download the data.
Example response header:
The URL value in the header property x-additional-info will return a CSV file with the same values as the response, plus the real readership value. Note that the file will expire after 5 minutes for security reasons. Just call the endpoint again to get a new valid URL.
GET: /api/v2.2/totalmentions
URL Parameters:
s (required): Next Generation Cision Communications Cloud search id (obtain from URL in Search Management page).
For example: http://app.trendkite.com/search#/edit/4050
range-start (required): date of search query begin
range-end (required): date of search query end
page-num (optional): when requesting results by page, the page number to return. If omitted, default is page-num=0 which is the first page.
page-size (optional): when requesting results by page, the maximum number of results per page. If omitted, default is 100 records. Use this parameter to get more results per page.
sort (optional): {asc | desc} the sort order for results by date (default is descending)
format (optional) : {csv | json} the output type to return (default is json)
ga-id (optional): Add Google Analytics data to mentions if possible. This Google Analytics ID corresponds to SQL’s google_analytics_account table’s ga_id column, and it must be attached to the authenticated user’s account.
GET Example usage:
curl -H "X-Auth-Token: <INSERT TOKEN>" "https://api.trendkite.com/api/v2.2/totalmentions?s=4045&range-start=2016-07-01T12:08:56.235-0700&range-end=2016-08-01T12:08:56.235-0700&page-num=0&page-size=10&sort=asc"
GET Example response:
[
{
"adEquivalency": 0.0,
"author": "Audacy",
"avgSessionDuration": 0.0,
"bounceRate": 0.0,
"city": "",
"country": "",
"date": "03/01/22",
"goalCompletions": 0,
"goalConversionRate": 0,
"goalValue": 0.0,
"impactScore": "low",
"link": "http://staging.trendkite.com/redir?s=300000004916679",
"mediaOutlet": "Bernstein & Rahimi Show",
"mediaType": "podcast",
"newUsers": 0,
"pageViews": 0,
"pageViewsPerSession": 0.0,
"percentNewSessions": 0.0,
"prAttrVisitBreakdown": {},
"prAttrVisitCompetitorBreakdown": {},
"prAttrVisitCompetitorTotal": null,
"prAttrVisitData": null,
"readership": 0, // set to 0 or viewership/circulation values in the default response. Check the response header for an url with the complete readership
"sentiment": "neutral",
"seoImpact": 0,
"sessions": 0,
"shares": 0,
"socialFacebook": 0,
"socialGoogleplus": 0,
"socialLinkedin": 0,
"socialPinterest": 0,
"socialReddit": 0,
"socialTwitter": 0,
"state": "",
"title": "Transition: Station promos are out of control",
"transactionRevenue": 0.0,
"url": "https://traffic.omny.fm/d/clips/4b5f9d6d-9214-48cb-"
}
]
GET Example response header:
NOTE: The URL value in the header property x-additional-info will return a CSV file with the same values as the response plus the real readership value. The file will expire in 5 min. Just call the endpoint again to get a new valid URL.
GET : /api/v2.2/searches
URL Parameters:
shared (optional): true - add parameter and set to true to see searches shared with the API user
GET Example usage:
curl -H "X-Auth-Token: <INSERT TOKEN>" "https://api.trendkite.com/api/v2.2/searches"
GET Example response:
{
"searches": [
{
"id": 12345678,
"title": "My Company",
"taxonomy": "COMPANY"
},
{
"id": 12345679,
"title": "My Product",
"taxonomy": "CUSTOM"
}
]
}
GET : /api/v2.2/stats
URL Parameters:
s (required): TrendKite search id (obtain from URL in Search Management page). For example: http://app.trendkite.com/search#/edit/4050
range-start (required): date of search query begin
range-end (required): date of search query end
type (optional): {all | ave | readership | totalMentions | socialShares} Either get back all stats, or specify which stat you want returned.
GET Example usage:
curl -H "X-Auth-Token: <INSERT TOKEN>" "http://api.trendkite.com/api/v2.2/stats?s=225993&range-start=2018-02-09T00:00:00.000Z&range-end=2018-05-10T00:00:00.000Z"
GET Example response:
[
{
"status": "Success",
"searchId": "1111111",
"searchName": "My Example Search Name",
"startDate": "2018-08-01T00:00:00.000-0000",
"endDate": "2018-08-31T00:00:00.000-0000",
"data": [
{
"ave": [
{
"isoCode": "$",
"name": "Newspaper",
"value": 1954819401
},
{
"isoCode": "$",
"name": "Blog",
"value": 56812094
},
{
"isoCode": "$",
"name": "Television",
"value": 248053677
}
],
"totalAVE": 2259685172
},
{
"readership": [
{
"isoCode": "$",
"name": "Newspaper",
"value": 1039797554246
},
{
"isoCode": "$",
"name": "Blog",
"value": 30219199437
},
{
"isoCode": "$",
"name": "Television",
"value": 4907611275
}
],
"totalReadership": 0
},
{
"totalMentions": 527025
},
{
"socialShares": {
"socialFacebookComments": 0,
"socialFacebookLike": 0,
"socialFacebookShare": 0,
"socialFacebookTotal": 15608524,
"socialGoogleplus": 0,
"socialLinkedin": 60531,
"socialPinterest": 34091,
"socialSum": 16265130,
"socialTwitter": 561984
},
"totalSocialShares": 16265130
}
]
}
]