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:

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

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
}