--- agentTools: projectIndex: https://developers.brandwatch.com/llms.txt --- # 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](https://developers.brandwatch.com/docs/creating-queries#validating-a-query) 2. [Uploading your Query](https://developers.brandwatch.com/docs/creating-queries#uploading-a-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: [block:parameters] { "data": { "h-0": "Parameters", "h-1": "Definition", "h-2": "Accepted Values", "0-0": "`contentSources`", "0-1": "Select which content sources you'd like the query to use", "0-2": "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](https://developers.brandwatch.com/docs/available-filters#accepted-values-for-global-preset-metrics) article. \n \nYou may also pass custom content sources you upload via our [Data Upload API](https://developers.brandwatch.com/docs/getting-started-data-upload).", "1-0": "`description`", "1-1": "Description of the query", "1-2": "string", "2-0": "`exclusionSnippets`", "2-1": "Filter mention by preset exclusion templates. This field facilitate the exclusion of common topics like job ads, automated market research, etc.", "2-2": "Array of IDs. The complete list of available IDs can be looked up at [Exclusion Snippets](https://developers.brandwatch.com/docs/exclusion-snippets).", "3-0": "`imageFilter`", "3-1": "Filter to allow you to search for logos and/or images that contain objects, scenes and actions (i.e running) \n \nNote: you have to have this module enabled to use this. Contact your CSM to have this enabled.", "3-2": "`imageAnalysisType`: `images-or-keywords` or `images-and-keywords` (string) \n \n[`logoIds`](https://developers.brandwatch.com/docs/objects-logos#logos) A list of IDs of 1 or multiple logos from our list of available logos. \n \n[`objectIds`](https://developers.brandwatch.com/docs/objects-logos#image-objects): A list of IDs of 1 or more objects from our list of available image objects/actions", "4-0": "`languages`", "4-1": "Select which language(s) your query should search", "4-2": "A list of [language codes](https://developers.brandwatch.com/docs/languages-and-timezones#languages). If you would like your query to be language agnostic, pass an empty list: `languages: []`", "5-0": "`locationFilter`", "5-1": "Filter your Query by a specific location", "5-2": "`includedLocations`: A list of locations to include in Query \n \n`excludedLocations`: A list of locations to exclude from Query \n \nFind your specific location IDs [here](https://developers.brandwatch.com/docs/locations).", "6-0": "`lockedQuery`", "6-1": "Choose whether your Query can be edited by others", "6-2": "boolean", "7-0": "`startDate`", "7-1": "Choose how far back your Query should go. If you upload a Query without this field, it will default to `30 days`", "7-2": "\"YYYY-MM-DD\"" }, "cols": 3, "rows": 8, "align": [ "left", "left", "left" ] } [/block] ## 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 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`. ```json { "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 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: ```json { "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": "user@brandwatch.com", "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 } ```