Talkwalker Search documents outside of any project

https://api.talkwalker.com/api/v1/search/results

How it works

The Talkwalker Search API allows you to retrieve up to 500 sorted results for a given timeframe within the last 30 days. In addition, a histogram of the number of results can also be returned. You can sort the results by publication time, indexing time, engagement or other metrics. A single search query can support up to 50 operands. To create complex queries, operands may be combined using Boolean operators.

A few words about the results

Search results can be sorted by engagement, time or other metrics and be restricted to specific attribute value ranges (for example only return results published in a certain timerange). When no special filters are applied, a single search request will return results from all media types and all languages over the past 30 days sorted by engagement by default. You don’t need to execute one search request for each language and media type separately.

To get a smaller set of results, you can either get only the highest ranked results or get a random sample set.

important

Social media content is not exported from this endpoint.

Parameters

parameter	description	required?	default value
access_token	API access token	required
q	The query to search for	required
offset	Number of results to skip (for paging)	optional	default: 0 / maximum: 500
hpp	Number of hits per page (for paging)	optional	default: 10 / maximum: 500
sort_by	Criteria for sorting the results.	optional	default: engagement
sort_order	Sorting order (ascending or descending)	optional	default: desc
hl	Turns highlighting on or off	optional	default: true
pretty	Formatted json for testing	optional	false
time_range	Time range filter in the format number + a time unit character (e.g. 30d for 30 days.)	optional

note

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.

Credits

1 credit per returned result, at least 10 credits per call (e.g. 100 results = 100 credits, 10 results = 10 credits and 0 results = 10 credits).

Examples

Get 100 results containing the word "cats" and "dogs"

Set the query cats AND dogs with query=cats%20AND%20dogs (note: in URLs spaces are replaced by %20) and set hits per page to 100 with hpp=100.

Command

curl 'https://api.talkwalker.com/api/v1/search/results?access_token=demo&q=cats%20AND%20dogs&hpp=100'

More on the Talkwalker Query Syntax

Get results containing the word "cats" sorted from new to old

To sort the results by date, set sort_by to published (to sort by the date of publication), to get the newest results first, set sort_order=desc.

Command

curl 'https://api.talkwalker.com/api/v1/search/results?access_token=demo&q=cats&sort_by=published&sort_order=desc'

All options for sort_by are : reach, facebook_shares, facebook_likes, twitter_shares, twitter_retweets, twitter_followers, youtube_likes, youtube_dislikes, youtube_views, cluster_size, comment_count, published, search_indexed, trending_score

You may find additional information on the document fields , except for trending_score, as presented next.

What is the meaning of Trending Score?

The Trending Score evaluates the acceleration of the engagement of a specific story over time. Mentions which are rapidly getting more engagement are given a higher score (out of 10), enabling you to discover breaking stories on specific topics. When calculating the Trending Score our algorithms look at the speed at which the engagement is growing, and then assign each result with a relative score (out of 10) based upon the speed at which the engagement is growing. The scores are categorised in the following way:

• 0-3: the article is not trending (or not trending anymore)
• 4-6: the article is slightly trending
• 7-10: the article is really trending, right now

Get results containing the word "cats" sorted by their Trending Score

Command

curl 'https://api.talkwalker.com/api/v1/search/results?access_token=demo&q=cats&sort_by=trending_score&sort_order=desc&pretty=true'

Response

{
    "status_code": "0",
    "status_message": "OK",
    "request": "GET /api/v1/search/results?access_token=demo&q=cats&sort_by=trending_score&sort_order=desc&pretty=true",
    "pagination": {
        "next": "GET /api/v1/search/results?access_token=demo&q=cats&sort_by=trending_score&sort_order=desc&pretty=true&offset=10",
        "total": 5169304
    },
    "result_content": {
        "data": [
            {
                "data": {
                    //truncated
                    "word_count": 421,
                    "trending_score": 6
                }
                // truncated
            }
        ]
    }
}

Rate Limit

This endpoint is limited to 240 calls per minute.