Project data access

When accessing data through a Talkwalker project, either a GET or POST HTTP request with several optional parameters can be used (see Table).

GET request command

curl -XGET 'https://api.talkwalker.com/api/v3/stream/p/<project_id>/results?access_token=<access_token>'

POST request command

curl -XPOST 'https://api.talkwalker.com/api/v3/stream/p/<project_id>/results?access_token=<access_token>'
-H 'Content-Type: application/json; charset=UTF-8'
-d '{"q": "<query_string>"}'

The POST request accepts a query in either its body or its URL.

The max_hits parameter is only accepted in the URL and stops the data access after a set amount of results.

Optional parameters

parameter	description
q	query to match
max_hits	stops the data access after the given number of hits
topic	One or more topics, custom filters or panels that are defined in the Talkwalker project.
dataset	One or more datasets that are defined in the Talkwalker Customer Intelligence project
filter	One or more custom filters that are defined in the Talkwalker project. The combination logic is the operator AND between the IDs if they are from different groups.
panel	One or more source panels that are defined in the Talkwalker project

Limit the results by topic

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

https://api.talkwalker.com/api/v3/stream/p/<project_id>/results?access_token=<access_token>&topic=topic_a&topic=topic_b

Result chunk

The result chunk for project data access has the form:

Sample CT_RESULT chunk

{
  "chunk_type" : "CT_RESULT",
  "chunk_result" : {
    "data" : {
      "data" : {
        "url" : "<url>",
        ...
        "matched" : {
          "appearance" : "<appearance>"
        },
        ...
      }
    }
  }
}

The url is not provided in every situation, e.g. Twitter results.

While new results count towards the max_hits parameter and require 1 credit each, it is also possible to obtain updated results. The field appearance under matched provides this information with the following values: UNKNOWN, NEW and UPDATED. Updated results come at no cost. Similar to when credits run out, only the specified maximum number of results is billed when the max_hits parameter is set and that amount of results is reached before the end of a chunk. Still, the full chunk is delivered.

Rate Limit

This endpoint is limited to 5 calls per minute.