Creating Queries

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:

Required Fields

There are only two required fields when creating a Query via the API:

Parameter	Definition	Accepted Values
`name`	Name of the query	string (must be unique)
`booleanQuery`	Boolean query search	string

Optional Fields

Below is a list of optional fields/filters for your Query:

Parameters	Definition	Accepted Values
`contentSources`	Select which content sources you'd like the query to use	A list of strings. If an empty list is passed, all content sources will be selected. You can find a list of our content source IDs in the Global Preset Metrics article. You may also pass custom content sources you upload via our Data Upload API.
`description`	Description of the query	string
`exclusionSnippets`	Filter mention by preset exclusion templates. This field facilitate the exclusion of common topics like job ads, automated market research, etc.	Array of IDs. The complete list of available IDs can be looked up at Exclusion Snippets.
`imageFilter`	Filter to allow you to search for logos and/or images that contain objects, scenes and actions (i.e running) Note: you have to have this module enabled to use this. Contact your CSM to have this enabled.	`imageAnalysisType`: `images-or-keywords` or `images-and-keywords` (string) `logoIds` A list of IDs of 1 or multiple logos from our list of available logos. `objectIds`: A list of IDs of 1 or more objects from our list of available image objects/actions
`languages`	Select which language(s) your query should search	A list of language codes. If you would like your query to be language agnostic, pass an empty list: `languages: []`
`locationFilter`	Filter your Query by a specific location	`includedLocations`: A list of locations to include in Query `excludedLocations`: A list of locations to exclude from Query Find your specific location IDs here.
`lockedQuery`	Choose whether your Query can be edited by others	boolean
`startDate`	Choose how far back your Query should go. If you upload a Query without this field, it will default to `30 days`	"YYYY-MM-DD"

Validating a Query

The first step allows you to validate your Query before uploading it, ensuring that there are no errors within the search string or any of the filters you may set. The following example call validates a Query which includes a search string (booleanQuery), a language filter (languages), a logo search (imageFilter) and a location filter (locationFilter).

curl -X POST \ 'https://api.brandwatch.com/query-validation' \
-H 'Content-Type: application/json' \
-d '{
	"booleanQuery": "j*",
	"languages": [
        "en"
    ],
    "imageFilter": {
        "imageAnalysisType": "images-or-keywords",
        "logoIds": [
            1234
        ]
    },
    "locationFilter": {
        "includedLocations": [
            "USA.PAs"
        ]
    }
}'

If there are errors with the boolean or any of the filters, they will be shown in the JSON response in the errors field and the issues field will point out where the error is in the boolean. In the example below, there are 2 errors: one error in booleanQuery and one in locationFilter.

{
    "booleanQuery": "j*",
    "languages": [
        "en"
    ],
    "locationFilter": {
        "includedLocations": [
            "USA.PAs"
        ],
        "excludedLocations": []
    },
    "imageFilter": {
        "logoIds": [
            1234
        ],
        "objectIds": [],
        "imageAnalysisType": "images-or-keywords"
    },
    "audienceLists": null,
    "contentSources": [
    ],
    "errors": [
        "This wildcard matches too many unique terms. Please make it more specific.",
        "Invalid location code in locationFilter.includedLocations: \"USA.PAs\""
    ],
    "issues": [
        {
            "startRow": 1,
            "startColumn": 1,
            "endRow": 1,
            "endColumn": 2,
            "type": "error",
            "errorCode": "short_wildcard",
            "message": "This wildcard matches too many unique terms. Please make it more specific."
        }
    ],
    "samplePercentage": null,
    "queryLimitUsage": 1,
    "exclusionSnippets": null
}

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 Consumer Research 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 
'{
  "languages": [
    "en"
  ],
  "booleanQuery": "@brandwatch",
  "name": "Brandwatch Twitter Engagement",
  "startDate": "2019-01-01",
  "contentSources": [
    "blog",
    "twitter",
    "forum"
  ],
  "lockedQuery": "true",
  "audienceLists": [],
  "imageFilter": {
    "imageAnalyisType": "images-or-keywords",
    "logoIds": [
      1234
    ],
    "objectIds": [
      1234
    ]
  },
  "locationFilter": {
    "excludedLocations": [
      "USA.OH"
    ],
    "includedLocations": [
      "USA.PA"
    ]
  }
}'

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

{
  "id": 2000280000,
  "name": "Brandwatch Twitter Engagement",
  "description": null,
  "creationDate": "2020-07-10T19:14:30.799+0000",
  "lastModificationDate": "2020-07-10T19:14:30.802+0000",
  "languages": [
    "en"
  ],
  "type": "monitor",
  "highlightTerms": [
    "@brandwatch"
  ],
  "lastModifiedUsername": "[email protected]",
  "lockedQuery": false,
  "lockedByUsername": null,
  "lockedTime": null,
  "createdByWizard": false,
  "booleanQuery": "@brandwatch",
  "startDate": "2019-01-01T00:00:00.000+0000",
  "percentComplete": null,
  "samplePercentage": 100,
  "userRequestedSampling": false,
  "sampled": false,
  "queryLimitUsage": 1,
  "locationFilter": {
    "includedLocations": [
      "USA.PA"
    ],
    "excludedLocations": []
  },
  "imageFilter": {
    "logoIds": [
			1234    
    ],
    "objectIds": [],
    "imageAnalysisType": "images-or-keywords"
  },
  "contentSources": [
    "forum",
    "twitter",
    "blog"
  ],
  "audienceLists": [],
  "exclusionSnippets": [],
  "active": true
}

Required Fields

Optional Fields

Validating a Query

Uploading a Query

🚧Warning

🚧
Warning