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/5/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 (black list). 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/5/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
    ]
  }
}