Topic Clusters API
Behavior
Given a query term, the Topic Clusters API returns discrete clusters of documents based on similarity.
GET /api/v2/query-terms/{term}/clusters
Request Fields
Attribute | Description |
|---|---|
term string | (Path Parameter - Required) |
geo string or null | (Optional) ISO-2 geo code specifying the country where results should be filtered from. Defaults to null for global |
Response Fields
Attribute | Description |
|---|---|
x_term string | The query term |
geo string | ISO-2 country code |
clusters list of dict | List of discrete document clusters |
clusters[i].name string | Inferred topic label of cluster |
clusters[i].start_date string | Start date of documents in cluster |
clusters[i].end_date string | End date of documents in cluster |
clusters[i].summary string | General summary of documents in cluster |
clusters[i].docs list of dict | List of documents comprising the cluster |
clusters[i].docs[j].body string | Content body of document. Social Media handles are redacted for privacy |
clusters[i].docs[j].processed_body string | Cleaned content body of document with redacted text removed. |
clusters[i].docs[j].timestamp string | Date posted of document |
clusters[i].docs[j].source string | Data source of document |
clusters[i].docs[j].x float | x-coordinate for plotting in a 2-dimension space based on sentence embeddings |
clusters[i].docs[j].y float | y-coordinate for plotting in a 2-dimension space based on sentence embeddings |
clusters[i].labels list of dicts | List of cluster labels |
clusters[i].labels[j].label string | Label for cluster |
clusters[i].labels[j].importance float | Score representing the importance of the label to the cluster |
Sample Request
GET api/v2/query-terms/turmeric/clusters HTTP/1.1
Content-Type: application/json
Authorization: Bearer <TOKEN>Sample Response
{
"x_term": "turmeric",
"geo": "US",
"clusters": [
{
"name": "Wellness Boost",
"start_date": "2023-08-25",
"end_date": "2024-02-22",
"summary": "This cluster contains posts focusing on turmeric as a beneficial ingredient for energy, skin health, meal preparation, and homemade beverages, emphasizing its versatility and health benefits.",
"docs": [
{
"body": "<REDACTED><REDACTED> Ohh Sorry to hear that . We usually have home made remedy for this .\nOne pinch of turmeric in one spoon of mustard oil .",
"processed_body": "ohh sorry to hear that | we usually have home made remedy for this | one pinch of turmeric in one spoon of mustard oil",
"timestamp": "2023-11-14",
"source": "twitter",
"x": 8.169857025146484,
"y": 1.7958219051361084
},
...
],
"labels": [
{
"label": "turmeric",
"importance": 0.9493799898080516
},
{
"label": "make",
"importance": 0.6726127320954908
},
...
]
},
...
]
}