Top Terms - v1

Strategy properties

Strategy id top_terms
Version 1
Supports grouping? No
Cost #terms across topics
Learn more...

Strategy usage

Overview

This strategy identifies the most engaged with terms (keywords and phrases) for each of a set of topics.

The strategy allows you to specify a set of topics using keywords. The strategy will identify for each topic the content that is seeing the most engagement, and which of your terms appear the most in this content.

The strategy also allows you to restrict analysis for all topics to an audience, to a common overall topic (defined using keywords and concepts), or both.

For each term in each topic the strategy tells you the number of members who engaged with content that uses the term.

Note that only terms in the any and all properties for topics are analzyed for their usage, however you can still use the none property to exclude content from a topic.

Use cases

The strategy helps you answer questions such as:

  • For a defined topic, or each of a set of topics, which words and phrases are used in content that is seeing engagement?

Parameters

To execute this strategy you must provide specify the topics parameter.

Parameter Type Required? Description
keywords

array(Keywords)

Where each topic is defined using a Keywords parameter.

Yes. Between 1 and 10 topics can be specified.

Topics to be analyzed.

audience audience

No.

Restrict analysis to this audience.

concepts concepts

No.

Restrict analysis to content mentioning these concepts.

keywords keywords

No.

Restrict analysis to content mentioning these keywords.

period period

No. Defaults to 28 days.

The time period to analyze.

sort_by sort_by

No. Defaults to unique_authors.

Note that engagement_ratio is not a supported sort option for this strategy.

The output field to sort results by.

Example requests

The following examples show which parameters should be submitted to the API to answer the stated questions.

Which terms for each of my two topics are seeing the most engagement from members in the US?

{
    "type": "strategy",
    "name": "example",
    "subscription_id": "cd99abbc812f646c77bfd8ddf767a134f0b91e84",
    "parameters": {
        "strategy": "top_terms",
        "version": 1,
        "parameters": {
            "audience": {
                "countries": ["united states"]
            },
            "topics": {
                "cloud": {
                    "any": ["cloud", "azure", "aws"]
                },
                "machine learning": {
                    "any": ["ml", "deep learning", "autonomous car"]
                }
            }
        }
    }
}

Which terms for each of my two topics (within the overall theme of 'cloud') are seeing the most engagement from members in the US?

{
    "type": "strategy",
    "name": "example",
    "subscription_id": "cd99abbc812f646c77bfd8ddf767a134f0b91e84",
    "parameters": {
        "strategy": "top_terms",
        "version": 1,
        "parameters": {
            "audience": {
                "countries": ["united states"]
            },
            "keywords": {
                "any": ["cloud", "azure", "aws", "google cloud"],
                "none": ["careers", "jobs"]
            },
            "topics": {
                "hosting": {
                    "any": ["hosting", "servers", "virtual machines"]
                },
                "cost": {
                    "any": ["cost", "pricing", "price plans"]
                }
            }
        }
    }
}

Here the top-level keywords parameter ensures that content analyzed for each topic must relate to the topic of 'cloud'.

Output

If the strategy is successfully executed it will return output with the following structure:

{
    "redacted": false,
    "topics": {
        "cloud": {
            "redacted": false,
            "terms": [
                {
                    "term": "cloud",
                    "redacted": false,
                    "unique_authors": 10000,
                    "interactions": 12000
                },
                {
                    "term": "azure",
                    "redacted": false,
                    "unique_authors": 8400,
                    "interactions": 11300
                },
            ...
            ]
        },
        ...
    }
}

If the top-level redacted property is true then not enough data was found for the analysis. Consider widening your topic or audience for your analysis.

A set of results is returned for each topic that was analyzed. If the redacted property is true for a topic then not enough data was found to analyze this topic.

For each term for each topic the following details are returned:

  • term - the term that was analyzed.
  • redacted - whether enough data was found to analyze the term's usage.
  • unique_authors - how many members engaged with content mentioning the term in the analyzed period.
  • interactions - how many engagements from members related to content mentioning the term in the analyzed period.

Usage costs

The cost of running the strategy is based upon the number of terms you define for your topics:

Analysis tasks consumed = (total number of terms across all topics)

Note that only terms in the any and all properties for topics are analzyed for their usage. Therefore terms included in the none property incur no cost.