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:
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 QueryexcludedLocations : A list of locations to exclude from QueryFind 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
}
Updated 7 months ago