Creating Queries

There have been changes made in how you validate and upload queries in the new Consumer Research API. You can find these changes in the updated Creating Queries article.

To get Mentions into our system, you have to first set up a Query. Queries are keyword-based searches constructed using boolean operators, which retrieve matching Mentions from millions of online sources.

There are two steps to creating a Query via the API:

Validating a Query

The following call will validate a Query, ensuring that there are no errors within the search string:

curl -X GET https://api.brandwatch.com/query-validation?query=at_mentions%3Abrandwatch&language=en

The response will look like the following:

{
    "query": "at_mentions:brandwatch",
    "language": [
        "en"
    ],
    "errors": [],
    "issues": []
}

Uploading a Query

After you've validated that the Query search string has no errors, you can upload the Query to your account.

🚧
Warning
Once you upload a Query it will start counting towards your Mention or Query limit.
To familiarize yourself with Query writing best practices, it is highly recommended that you write a Query in the Brandwatch Analytics UI before uploading any Queries via the API.

The following call will create a new Query in the Project with ID 1998159537:
(Click here to learn how to get your Project ID)

curl -X POST \
  'https://api.brandwatch.com/projects/1998159537/queries/' \
  -H 'content-type: application/json' \
  -d '{"type":"search string","languageAgnostic":false,"samplePercent":100,"languages":["en"],"includedTerms":["at_mentions%3Abrandwatch"],"name":"Brandwatch Twitter Engagement","description":"","industry":"general-(recommended)"}'

This will upload a Query into your account, and return a response similar to the following:

{
    "id": 1998995501,
    "name": "Brandwatch Twitter Engagement",
    "description": null,
    "creationDate": "2017-06-19T15:04:59.449+0000",
    "lastModificationDate": "2017-06-19T15:04:59.455+0000",
    "industry": "general-(recommended)",
    "includedTerms": [
        "at_mentions:brandwatch"
    ],
    "languages": [
        "en"
    ],
    "averageMonthlyMentions": 0,
    "twitterLimit": 1500,
    "dailyLimit": 10000,
    "type": "search string",
    "twitterScreenName": null,
    "highlightTerms": [
        "brandwatch"
    ],
    "links": {
        "lastSevenDaysSentiment": "http://api.brandwatch.com/projects/1998159537/data/volume/queries/sentiment.json?access_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&queryId=1998995501&startDate=2017-06-12T15:04:59.479Z&endDate=2017-06-19T15:04:59.479Z",
        "lastSevenDaysVolume": "http://api.brandwatch.com/projects/1998159537/data/volume/queries/days.json?access_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&queryId=1998995501&startDate=2017-06-12T15:04:59.479Z&endDate=2017-06-19T15:04:59.479Z",
        "lastTenMentions": "http://api.brandwatch.com/projects/1998159537/data/mentions.json?access_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&queryId=1998995501&startDate=2017-06-12T15:04:59.479Z&endDate=2017-06-19T15:04:59.479Z&page=0&pageSize=10&orderBy=id&orderDirection=desc"
    },
    "samplePercent": 100,
    "lastModifiedUsername": "[email protected]",
    "languageAgnostic": false,
    "lockedQuery": false,
    "lockedByUsername": null,
    "lockedTime": null,
    "createdByWizard": false,
    "unlimitedHistoricalData": {
        "backfillMinDate": null,
        "unlimitedHistoricalDataEnabled": false
    }
}

Validating a Query

Uploading a Query

🚧Warning

🚧
Warning