Modifying topics with Talkwalker API
Overview
To create or edit topics, use the endpoint
To delete topics, use the endpoint
To get a list of all topics with their details, use the endpoint
https://api.talkwalker.com/api/v2/talkwalker/p/<project_id>/topics/list
Parameters
| parameter | description | required? | default value |
|---|---|---|---|
| access_token | a read/write token specified in the API application | required |
danger
Any modifications of topics done via the Talkwalker API will overwrite changes done in Talkwalker.
Definition of a topic
The definition of a topic consists of the following parameters:
| parameter | description | required? | values |
|---|---|---|---|
| topic_id | unique topic ID | optional | generated automatically if absent or left empty |
| topic_title | topic title | required | |
| topic_description | topic description | optional | |
| topic_color | color of the topic on the platform | optional | |
| topic_order | order of the topic in the list | optional | |
| category_id | category ID | required if category_title is absent | default to create an ungrouped topic |
| category_title | category title | required if category_id is absent | name of the group under which the topic will be created |
| category_description | category description | optional | |
| category_order | order of the category in the list | optional | |
| override | override the query | required | true or false |
| query | the topic query | required | |
| included_query | to determine if the query added is to be included or excluded | required | true or false |
| topic_type | specifies the topic type | optional | SEARCH or FILTER. default: SEARCH |
Create/edit a topic
Command
curl -XPOST 'https://api.talkwalker.com/api/v2/talkwalker/p/<project_id>/topics/import?access_token=<access_token>'
-d '<topic_definition>'
-H 'Content-Type: application/json; charset=UTF-8'
Topic definition to create a new topic under a new group
{
"topic_type": "search",
"topic_line_import": [
{
"topic_title": "my new topic",
"topic_description": "This is a topic description",
"category_title": "my new group",
"override": false,
"query": "cats",
"included_query": true
}
]
}
Topic definition to create a new ungrouped topic
{
"topic_type": "search",
"topic_line_import": [
{
"topic_title": "my new ungrouped topic",
"topic_description": "This is a topic description",
"category_id": "default",
"override": false,
"query": "cats",
"included_query": true
}
]
}
Topic definition to edit a topic
{
"topic_type": "search",
"topic_line_import": [
{
"topic_id": "<topic_id>",
"topic_title": "changed topic name",
"topic_description": "This is an updated topic description",
"category_id": "default",
"override": true,
"query": "changed query",
"included_query": true
},
{
"topic_id": "<topic_id>",
"topic_title": "changed topic name",
"topic_description": "This is an updated topic description",
"category_id": "default",
"override": true,
"query": "exclude these words",
"included_query": false
}
]
}
Rate Limit
This endpoint is limited to 30 calls per minute.
Delete a topic
Command
curl -XPOST 'https://api.talkwalker.com/api/v2/talkwalker/p/<project_id>/topics/delete?access_token=<access_token>'
-d '{
"bulk_topics": [
{
"id": "<topic1_id>",
"category_id": "default",
"topic_type": "FILTER"
},
{
"id": "<topic2_id>",
"category_id": "<category1_id>"
}
]
}'
-H 'Content-Type: application/json; charset=UTF-8'
To make sure that the topic has been successfully deleted, the success field in the call response should be set to true
Response
{
"status_code": "0",
"status_message": "OK",
"request": "POST /api/v2/talkwalker/p/<project_id>/topics/delete?access_token=<access_token>",
"result_topic_deletion": {
"bulk_answer": [
{
"id": "kowmxxxx_5imm9xxxxxxx",
"category_id": "default",
"success": true
},
{
"id": "exampleid123",
"category_id": "examplecategoryid123",
"success": true
}
]
}
}
Rate Limit
This endpoint is limited to 30 calls per minute.
Retrieve the definition of all topics
Command
curl -XGET 'https://api.talkwalker.com/api/v2/talkwalker/p/<project_id>/topics/list?access_token=<access_token>'
Response
{
"status_code": "0",
"status_message": "OK",
"request": "GET /api/v2/talkwalker/p/<project_id>/topics/list?access_token=<access_token>",
"result_topics": {
"topic_categories": [
{
"id": "default",
"title": "",
"description": "",
"query_topics": [
{
"id": "<topic_id>",
"title": "topic name",
"description": "",
"included_queries": ["query"],
"excluded_queries": ["query"]
}
]
},
{
"id": "<category_id>",
"title": "category name",
"description": "",
"query_topics": [
{
"id": "<topic_id>",
"title": "topic name",
"description": "",
"included_queries": ["query"]
}
]
}
],
"filter_categories": [
{
"id": "default_filter",
"title": "",
"description": "",
"query_topics": [
{
"id": "<filter_id>",
"title": "filter name",
"description": "",
"included_queries": ["query"]
}
]
},
{
"id": "<converted_from_topic>",
"title": "",
"description": "",
"query_topics": [
{
"id": "<filter_id>",
"title": "filter name",
"description": "",
"included_queries": ["query"]
}
]
},
{
"id": "<category_id>",
"title": "filter category name",
"description": "",
"query_topics": [
{
"id": "<filter_id>",
"title": "filter name",
"description": "",
"included_queries": ["query"]
}
]
}
]
}
}
Rate Limit
This endpoint is limited to 30 calls per minute.
Retrieve the definition of a specific topic
In order to only get the definition of a specific topic when calling the endpoint, we can add the topic ID to the endpoint.
Command
curl -XGET 'https://api.talkwalker.com/api/v2/talkwalker/p/<project_id>/topics/list/<topic_id>?access_token=<access_token>'
Response
{
"status_code": "0",
"status_message": "OK",
"request": "GET /api/v2/talkwalker/<project_id>/topics/list/<topic_id>?access_token=<access_token>",
"result_topic_details": {
"id": "<topic_id>",
"title": "topic name",
"description": "",
"category_id": "<category_id>",
"category_title": "",
"category_description": "",
"included_queries": ["query"],
"excluded_queries": ["query"],
"type": "SEARCH"
}
}
Rate Limit
This endpoint is limited to 30 calls per minute.
Remove an empty category
This endpoint allows you to delete empty categories.
Command
curl -XPOST 'https://api.talkwalker.com/api/v2/talkwalker/p/<project_id>/topics/delete_category?access_token=<access_token>'
-d '{
"category_id": "<category_id>",
"topic_type": "search" | "filter"
}'
-H 'Content-Type: application/json; charset=UTF-8'
Response
{
"status_code": "0",
"status_message": "OK",
"request": "POST /api/v2/talkwalker/p/<project_id>/topics/delete_category?access_token=<access_token>",
"result_topic_deletion": {
"category_id": "<category_id>"
}
}
caution
If the category used is not empty (contains one or more topics/filters), you will receive an error message "The category is not empty".
Rate Limit
This endpoint is limited to 30 calls per minute.