Analysis Request

The Analysis API accepts a JSON query containing parameters specifying the type of analysis to be initiated along with data sources, date ranges, language filtering, and more.

The API has been designed to return data for date ranges no greater than any single 24 hour period.

We have package pricing based on the number of queries that you would like to run. A "query" is a request for data about a keyword, keyword phrase, or complex boolean for a 24hr period. (So to get volume metrics for "nike" for the last week in May, you would need to run 7 queries - one for each day with the same keyword = "nike"; to get volume metrics for "nike OR swoosh OR 'just do it'" for the last week in May, you would also need to run 7 queries).

We count queries submitted to the API that have successfully generated results against your quota. Queries that result in an error being generated, or which do not create a result which can be successfully retrieved are not counted. Please note: queries that generate zero results (i.e. found no matching posts) are counted as having successfully searched our data stores and processed your request, and these will generate a result which can be retrieved showing the zero volume.

Required Fields

Field	Definition	Accepted values
`sources`	The data sources from which the aggregate data is derived.	`TWITTER`, `TUMBLR`, `NEWS`, `REVIEWS`, `YOUTUBE`, `BLOGS`, `FORUMS` & `REDDIT` (case sensitive)
`analysis`	The types of analysis to be performed.	`volume`, `sentiment`, `emotion`, `gender`, `age`, `location`, `source` (case sensitive)
`startDate`	The beginning of the date range that contains the Mentions.	"YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx" Note: you can specify the time zone by replacing +xxxx with the ISO UTC offset, e.g -0500 for New York standard time
`endDate`	The end of the date range that contains the Mentions.	"YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx" Note: you can specify the time zone by replacing +xxxx with the ISO UTC offset, e.g -0500 for New York standard time
`keywords`	The search query to retrieve the results you would like	string

❗️
Values passed to the startDate and endDate parameters must not exceed a 24 hour period. An error will indicate queries containing invalid date ranges.

Optional Fields

Field	Definition	Accepted values
`languages`	The languages of the Mentions to be used in the aggregate data.	Supported values can be found in the Language Codes article.
`locations`	The locations of the Mentions to be used in the aggregate data.	Supported values are the `geo.id`s from this list in our help center or search using our locations endpoint.

Here's an example request:

curl -X POST 'https://api.brandwatch.com/analysis/' \
-H 'Content-Type: application/json' \
-d '{
    "analysis": [
        "volume",
        "gender",
        "age",
        "location",
        "source"
    ],
    "keywords": "iPhone",
    "languages": {
        "type": "include",
        "values": [
            "en"
        ]
    },
    "locations": {
        "type": "include",
        "values": [
            "USA"
        ]
    },
    "sources": [
        "TWITTER"
    ],
    "startDate": "2021-04-02T00:00:00+05:00",
    "endDate": "2021-04-03T00:00:00+05:00"
}'

Here is an example response. You will then take the newly-created resultId in order to retrieve your results with your next request.

{
  "status": "WAITING",
  "resultId": 527434743,
  "resultsUri": "https://api.brandwatch.com/analysis/",
  "retrieveAt": "2021-04-01T12:01:00Z",
  "retrieveAtMillis": 1617278460000,
  "request": {
    "analysis": [
      "volume",
      "gender",
      "age",
      "location",
      "source"
    ],
    "startDate": "2021-04-02T00:00:00+05:00",
    "endDate": "2021-04-03T00:00:00+05:00",
    "sources": [
      "TWITTER"
    ],
    "keywords": "iPhone",
    "languages": {
      "type": "include",
      "values": [
        "en"
      ]
    },
    "locations": {
      "type": "include",
      "values": [
        "USA"
      ]
    }
  }
}

Users will see a response with an HTTP status code 202 along with a key:value pair containing the ID which should be retrieved at the time specified in the response body. This ID can then be used to determine if the job is complete.

{
  "resultId": 527434743,
  "status": "DONE",
  ...
  ...
}

🚧
The Analysis API will periodically respond synchronously depending on query complexity and caching, but you should always be prepared to handle asynchronous responses.