Talkwalker Search Histogram API and Talkwalker Projects

https://api.talkwalker.com/api/v1/search/p/<project_id>/histogram/<type>

How it works

Talkwalker users can use the topics defined in their project with the Talkwalker API. The Project Search Histogram API can be used with the same parameters and types as the Search Histogram API. Additionally, in order to query a specific topic of a Talkwalker Project, the parameter topic can be set to one or more topic-IDs. Talkwalker users can also retrieve the datasets defined in their Customer Intelligence project using the parameter dataset. Datasets older than 7 days can no longer be queried.

note

same types as Talkwalker Search Histogram API.
Same usage, more on guide to using histograms.

Histogram types

type	Description	Representation
published	Timestamp of publication (epoch time in milliseconds)	Histogram
search_indexed	Timestamp of indexation in Talkwalker (epoch time in milliseconds)	Histogram
reach	The reach of an article/post represents the number of people who were reached by this article/post.	Histogram
engagement	The engagement of an article/post is the sum of actions made by others on that article/post.	Histogram
facebook_shares	Number of Facebook shares an article has	Histogram
facebook_likes	Number of Facebook likes an article has	Histogram
twitter_retweets	Number of Twitter retweets an article has	Histogram
twitter_shares	Number of Twitter share an article has	Histogram
twitter_likes	Number of Twitter likes an article has	Histogram
twitter_followers	Number of Twitter followers a source has	Histogram
twitter_impressions	Number of Twitter impressions an article has	Histogram
twitter_video_views	Number of Twitter video views an article has	Histogram
instagram_likes	Number of Instagram likes an article has	Histogram
youtube_views	Number of YouTube views a video has	Histogram
youtube_likes	Number of YouTube likes a video has	Histogram
youtube_dislikes	Number of YouTube dislikes a video has	Histogram
comment_count	Number of comments an article has	Histogram
language	Number of documents written in a language	Top-N Distribution
country	Number of documents with a source from a certain country	Top-N Distribution
source_region	Number of documents with a source from a certain region, depends on geolocation resolution	Top-N Distribution
source_city	Number of documents with a source from a certain city, depends on geolocation resolution	Top-N Distribution
gender	Number of documents written by an author of a particular gender	Top-N Distribution
age	Number of documents written by an author in a predefined age group	Distribution
unique_author	Total number of different authors	Distribution
hashtag	Number of documents containing a particular hashtag	Top-N Distribution
emoji	Number of documents containing a particular emoji code	Top-N Distribution
theme_cloud	percent of documents containing a particular word or hashtag	Top-N Distribution
interest	Number of documents within a particular interest group	Top-N Distribution
occupation	Number of documents within a particular occupation group	Top-N Distribution
sentiment	Number of documents with a particular sentiment	Distribution

Parameters

Same as Histogram API parameters with additional parameters topic, filter, channel, panel and dataset:

parameter	description	required?	allowed values	default value
access_token	a read/write token specified in the API application	required
q	The query to search for	optional	Talkwalker query syntax
min	Minimum value for bins	optional	Long Integer value	For `published`: tomorrow - 8 days or max - 8 days
max	Maximum value for bins	optional	Long Integer value	For `published`: tomorrow or min + 8 days
min_include	Include min value	optional	`true` / `false`	true
max_include	Include max value	optional	`true` / `false`	false
interval	Bin Interval	optional	Duration for `published` and `search_indexed` / Integer for histogram / not used for distribution	dynamic
timezone	Timezone (for interval)	optional	tz database: timezone name (e.g. `Europe/Luxembourg`, `Australia/Perth`)	UTC
breakdown	Nested histogram	optional	`sentiment`, `sourcetype`, `country`, `topic`, `channel	-
value_type	Nested metric for time based histograms	optional	metric historgram types	-
top_n	Size limiter for demographic distribution	optional	Integer value in ]0, 100]	10
time_range	Time range filter in the format `number`+ a time unit character (e.g. `30d` for 30 days.)	optional
percentage_relation	Specify the relation for theme clouds	optional	`breakdown`, `query`, `total`	`breakdown`
tokenizing_mode	Tokenizing mode for theme cloud histograms	optional	normal, two_grams, three_grams, noun_phrase, verb_phrase	normal
forecast_days	Time series forecast in days. Predicts the future. Only available on project indices with forecast enabled	optional	Integer value in [1, 90]
topic	One or more topics that are defined in the Talkwalker project	optional, multiple
filter	One or more filters that are defined in the Talkwalker project	optional, multiple
channel	One or more channels that are defined in the Talkwalker project	optional, multiple
panel	One or more source panels that are defined in the Talkwalker project	optional, multiple
dataset	One or more datasets that are defined in the Talkwalker Customer Intelligence project	optional, multiple

Possible values for time_range as time unit characters are: s for seconds, m for minutes, h for hours, d for days, w for weeks and M for months.

Since some parameters are only used by certain histogram types, the following table provides an overview of all working combinations.

	access_token q	min max min_include max_include interval	timezone forecast_days value_type	breakdown	top_n	percentage_relation tokenizing_mode
published	x	x	x	x
search_indexed	x	x	x	x
engagement	x	x
reach	x	x
facebook_shares	x	x
facebook_likes	x	x
twitter_shares	x	x
twitter_retweets	x	x
twitter_followers	x	x
twitter_likes	x	x
twitter_impressions	x	x
twitter_video_views	x	x
youtube_likes	x	x
youtube_dislikes	x	x
youtube_views	x	x
instagram_likes	x	x
cluster_size	x	x
comment_count	x	x
sentiment	x
interest	x				x
occupation	x				x
theme_cloud	x			x	x	x
hashtag	x				x
emoji	x				x
unique_author	x
language	x				x
country	x				x
source_region	x				x
source_city	x				x
gender	x				x
age	x

Time series forecast

Forecasting is a feature currently available in Talkwalker Platform for projects that include the corresponding package. This parameter allows to make a time series prediction and determine the confidence interval.

Restrictions

The feature will be enabled only if all the following conditions are satisfied:

The histogram type is published or search_indexed
Parameter interval is set to 1d or is not present
Parameter max is not specified (prediction can't be done if we don't search for results "till now")
The package includes the forecast feature
Value set within [1, 90]

Time series forecast example

Command
curl 'https://api.talkwalker.com/api/v1/search/p/<project_id>/histogram/published?access_token=<access_token>&q=cats&forecast_days=1&pretty=true'

Response
{
    "status_code": "0",
    "status_message": "OK",
    "request": "GET /api/v1/search/p/<project_id>/histogram/published?access_token=<access_token>&q=cats&forecast_days=1&pretty=true",
    "result_histogram": {
        "header": {
            "v": ["Number Results"]
        },
        "data": ["__truncated_for_readability__"],
        "forecast": {
            "header": {
                "v": ["Number Results"]
            },
            "data": [
                {
                    "t": 1671235200000,
                    "v": [4.0],
                    "min_confidence": [0.0],
                    "max_confidence": [7.0]
                }
            ]
        }
    }
}

A new object is then available in the payload with field forecast, it keeps the same structure as a normal histogram, but with two additional arrays representing min. and max. confidence. The data object is composed of:

t indicates the time-based lower bound of the current bucket
v is the number of elements inside that bucket
min_confidence the minimum confidence of our AI for v
max_confidence the maximum confidence of our AI for v

Top influencers histogram.

Top influencers histogram is a specific Top-N Distribution list which can only be called in the context of a Talkwalker project. It returns the number of documents written by an author (or a source) with sentiment and performance metrics.

Top influencers endpoint

https://api.talkwalker.com/api/v1/search/p/<project_id>/histogram/top_influencers

Top influencers specific Parameters

parameter	description	required?	allowed values	default value
access_token	a read/write token specified in the API application	required
q	The query to search for	optional	Talkwalker query syntax
top_n	Size limiter for demographic distribution	optional	Integer value in ]0, 100]	10
time_range	Time range filter in the format `number`+ a time unit character (e.g. `30d` for 30 days.)	optional
topic	One or more topics that are defined in the Talkwalker project	optional, multiple
filter	One or more filters that are defined in the Talkwalker project	optional, multiple
channel	One or more channels that are defined in the Talkwalker project	optional, multiple
panel	One or more source panels that are defined in the Talkwalker project	optional, multiple
dataset	One or more datasets that are defined in the Talkwalker Customer Intelligence project	optional, multiple
influencer_type	Get the results for authors or sources.	optional	`author`, `source`	`author`
sort_criteria	Sort the results (always descending) by a criteria	optional	`total`, `positive`, `negative`, `neutral`, `reach`, `engagement`, `engagement_per_mention`, `reach_per_mention`	`total`

Possible values for time_range as time unit characters are: s for seconds, m for minutes, h for hours, d for days, w for weeks and M for months.

===== Top influencers example Top 3 influencers sorted by the potential reach per mention they posted in the last 7 days.

Command
curl 'https://api.talkwalker.com/api/v1/search/p/<project_id>/histogram/top_influencers?access_token=<access_token>&sort_criteria=reach_per_mention&top_n=3&time_range=7d'

Response
{
    "status_code": "0",
    "status_message": "OK",
    "request": "GET /api/v1/search/p/<project_id>/histogram/top_influencers?sort_criteria=reach_per_mention&top_n=3&time_range=7d&<access_token=access_token>",
    "result_top_influencers": {
        "influencers": [
            {
                "matched_topics": [
                    {
                        "topic_id": "<Topic ID 1>",
                        "posts_amount": 0
                    },
                    {
                        "topic_id": "<Topic ID 2>",
                        "posts_amount": 1
                    },
                    {
                        "topic_id": "<Topic ID 3>",
                        "posts_amount": 0
                    }
                ],
                "details": {
                    "id": "<ID 1>",
                    "name": "rimmi singhi",
                    "url": "http://www.yahoo.com/"
                },
                "network": "ONLINENEWS_OTHER",
                "posts": 1,
                "sentiment": {
                    "positive": 1,
                    "negative": 0,
                    "neutral": 0
                },
                "reach": 1.4397408e9,
                "reach_per_mention": 1.4397408e9,
                "engagement": 0.0,
                "engagement_per_mention": 0.0
            },
            {
                "matched_topics": [
                    {
                        "topic_id": "<Topic ID 1>",
                        "posts_amount": 2
                    },
                    {
                        "topic_id": "<Topic ID 2>",
                        "posts_amount": 1
                    },
                    {
                        "topic_id": "<Topic ID 3>",
                        "posts_amount": 0
                    }
                ],
                "details": {
                    "id": "<ID 2>",
                    "name": "grace kay",
                    "url": "http://www.yahoo.com/"
                },
                "network": "ONLINENEWS_OTHER",
                "posts": 2,
                "sentiment": {
                    "positive": 0,
                    "negative": 1,
                    "neutral": 1
                },
                "reach": 2.8794816e9,
                "reach_per_mention": 1.4397408e9,
                "engagement": 0.0,
                "engagement_per_mention": 0.0
            },
            {
                "matched_topics": [
                    {
                        "topic_id": "<Topic ID 1>",
                        "posts_amount": 0
                    },
                    {
                        "topic_id": "<Topic ID 2>",
                        "posts_amount": 1
                    },
                    {
                        "topic_id": "<Topic ID 3>",
                        "posts_amount": 1
                    }
                ],
                "details": {
                    "id": "<ID 3>",
                    "name": "yuri kageyama",
                    "url": "http://www.yahoo.com/"
                },
                "network": "ONLINENEWS_OTHER",
                "posts": 1,
                "sentiment": {
                    "positive": 0,
                    "negative": 0,
                    "neutral": 1
                },
                "reach": 1.4397408e9,
                "reach_per_mention": 1.4397408e9,
                "engagement": 0.0,
                "engagement_per_mention": 0.0
            }
        ],
        "influencer_type": "AUTHOR",
        "sort_criteria": "REACH_PER_MENTION"
    }
}

Credits

10 credits per Search Histogram API call.

Rate Limit

Project based histograms are limited to 30 calls per minute.

Limit the results by topic

In order to only include results that match either topic_a or topic_b when calling the search endpoint, we can add these topics as parameters.

https://api.talkwalker.com/api/v1/search/p/<project_id>/histogram/<type>?access_token=<access_token>&topic=topic_a&topic=topic_b

Talkwalker Search Histogram API and Talkwalker Projects

How it works​

Histogram types​

Parameters​

Time series forecast​

Restrictions​

Time series forecast example​

Top influencers histogram.​

Top influencers endpoint​

Top influencers specific Parameters​

Credits​

Rate Limit​

Limit the results by topic​