Skip to main content

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

Parameters

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

parameterdescriptionrequired?allowed valuesdefault value
access_tokena read/write token specified in the API applicationrequired
qThe query to search foroptionalTalkwalker query syntax
minMinimum value for binsoptionalLong Integer valueFor published: tomorrow - 8 days or max - 8 days
maxMaximum value for binsoptionalLong Integer valueFor published: tomorrow or min + 8 days
min_includeInclude min valueoptionaltrue / falsetrue
max_includeInclude max valueoptionaltrue / falsefalse
intervalBin IntervaloptionalDuration for published and search_indexed / Integer for histogram / not used for distributiondynamic
timezoneTimezone (for interval)optionaltz database: timezone name (e.g. Europe/Luxembourg, Australia/Perth)UTC
breakdownNested histogramoptionalsentiment, sourcetype, country, topic, `channel-
value_typeNested metric for time based histogramsoptionalmetric historgram types-
top_nSize limiter for demographic distributionoptionalInteger value in ]0, 100]10
time_rangeTime range filter in the format number+ a time unit character (e.g. 30d for 30 days.)optional
percentage_relationSpecify the relation for theme cloudsoptionalbreakdown, query, totalbreakdown
tokenizing_modeTokenizing mode for theme cloud histogramsoptionalnormal, two_grams, three_grams, noun_phrase, verb_phrasenormal
forecast_daysTime series forecast in days. Predicts the future. Only available on project indices with forecast enabledoptionalInteger value in [1, 90]
topicOne or more topics that are defined in the Talkwalker projectoptional, multiple
filterOne or more filters that are defined in the Talkwalker projectoptional, multiple
channelOne or more channels that are defined in the Talkwalker projectoptional, multiple
panelOne or more source panels that are defined in the Talkwalker projectoptional, multiple
datasetOne or more datasets that are defined in the Talkwalker Customer Intelligence projectoptional, 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.

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:

  1. The histogram type is published or search_indexed
  2. Parameter interval is set to 1d or is not present
  3. Parameter max is not specified (prediction can't be done if we don't search for results "till now")
  4. The package includes the forecast feature
  5. 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

parameterdescriptionrequired?allowed valuesdefault value
access_tokena read/write token specified in the API applicationrequired
qThe query to search foroptionalTalkwalker query syntax
top_nSize limiter for demographic distributionoptionalInteger value in ]0, 100]10
time_rangeTime range filter in the format number+ a time unit character (e.g. 30d for 30 days.)optional
topicOne or more topics that are defined in the Talkwalker projectoptional, multiple
filterOne or more filters that are defined in the Talkwalker projectoptional, multiple
channelOne or more channels that are defined in the Talkwalker projectoptional, multiple
panelOne or more source panels that are defined in the Talkwalker projectoptional, multiple
datasetOne or more datasets that are defined in the Talkwalker Customer Intelligence projectoptional, multiple
influencer_typeGet the results for authors or sources.optionalauthor, sourceauthor
sort_criteriaSort the results (always descending) by a criteriaoptionaltotal, positive, negative, neutral, reach, engagement, engagement_per_mention, reach_per_mentiontotal

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