Creating Queries

Adding a new Query search to your Project

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:

  1. Validating your Query
  2. Uploading your Query

Required Fields

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

ParameterDefinitionAccepted Values
nameName of the querystring (must be unique)
booleanQueryBoolean query searchstring

Optional Fields

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

ParametersDefinitionAccepted Values
contentSourcesSelect which content sources you'd like the query to useA 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.
descriptionDescription of the querystring
exclusionSnippetsFilter 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.
imageFilterFilter 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
languagesSelect which language(s) your query should searchA list of language codes. If you would like your query to be language agnostic, pass an empty list: languages: []
locationFilterFilter your Query by a specific locationincludedLocations: A list of locations to include in Query

excludedLocations: A list of locations to exclude from Query

Find your specific location IDs here.
lockedQueryChoose whether your Query can be edited by othersboolean
startDateChoose 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
}