Keyword Insights

Given a group of keywords, get the associated Tweet volume as well as a set of 30 related keywords. The Tweet volume corresponds to the input keywords only, not the related keywords.

A maximum time range (end_time - start_time) of 7 days is allowed.

Please note that results are scoped by a single geo (country).

Resource URL

https://ads-api.twitter.com/8/insights/keywords/search

Parameters

Name Description
granularity
required

Specifies the granularity of the data returned for the time range denoted by start_time and end_time. For instance, when set to HOUR, you will be presented with a datapoint for each hour between start_time and end_time. request.

Type: enum

Possible values: DAY, HOUR

keywords
required

A comma-separated string of keywords to narrow search by. All keywords are OR'ed with one another.

Note: A maximum of 10 keywords (keywords and negative_keywords combined) may be used.

Type: string

Example: developers

start_time
required

Scopes the retrieved data to data collected in the window of time between start_time and end_time. Expressed in ISO 8601.

Type: string

Example: 2017-07-10T00:00:00Z

end_time
optional

Scopes the retrieved data to data collected in the window of time between start_time and end_time. Expressed in ISO 8601.

Note: Defaults to the current time.

Type: string

Example: 2017-07-11T00:00:00Z

location
optional

A targeting value you would get from the GET targeting_criteria/locations endpoint to narrow results in terms of where the user of the account is located. Note that at present only country level locations are supported.

Type: string

Example: 0ce8b9a7b2742f7e

negative_keywords
optional

A comma-separated string of keywords to exclude. All negative keywords are OR'ed with one another.

Note: A maximum of 10 keywords (keywords and negative_keywords combined) may be used.

Type: string

Example: rain

Example Request

GET https://ads-api.twitter.com/8/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

Example Response

{
  "request": {
    "params": {
      "start_time": "2018-02-01T00:00:00Z",
      "end_time": "2018-02-02T00:00:00Z",
      "granularity": "DAY",
      "keywords": [
        "developers"
      ]
    }
  },
  "data": {
    "related_keywords": [
      "dev",
      "developer",
      "coders",
      "mysql",
      "devs",
      "#technology",
      "#developers",
      "security",
      "programmers",
      "#tech",
      "javascript",
      "#iot",
      "#bigdata",
      "cloud",
      "devops",
      "php",
      "developer",
      "programmer",
      "engineer",
      "big data",
      "agile",
      "app",
      "programming",
      "ios",
      "maker",
      "startups",
      "developer's",
      "java",
      "#devops",
      "startup"
    ],
    "tweet_volume": [
      15707
    ]
  }
}

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.