DEMO.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python Client Library for the Brandwatch Consumer Research API: Demo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The goal of this notebook is to demonstrate the capabilities of the Python Client Library for Brandwatch's Consumer Research API. The library was designed to address many of the challenges involved in building complex applications which interact with RESTful APIs in general and Brandwatch's Consumer Research API in particular:\n",
    "<ul>\n",
    "<li>The library's object hierarchy roughly mirrors the API's resource hierarchy, making the code intuitive for those familiar with the Brandwatch Consumer Research platform</li>\n",
    "<li>All required parameters are enforced, and most optional parameters are supported and documented</li>\n",
    "<li>Typical workflows are supported behind the scenes; for instance, one can validate, upload, and backfill a query with a single function call</li>\n",
    "<li>The library is designed to support simple and readable code: sensible defaults are chosen for rarely used parameters and all resource IDs are handled behind the scenes\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From the user's perspective, the basic structure of the library is as follows.  One first creates an instance of the class `BWProject`; this class handles authentication (via a user name and password or API key) and keeps track of project-level data such as the project's ID.  (Behind the scenes, the user-level operations are handled by the class `BWUser` from which `BWProject` is inherited.)  One passes `BWProject` instance as an argument in the constructor for a series of classes which manage the various Brandwatch resources: queries, groups, tags, categories, etc.  These resource classes manage all resource-level operations: for example a single `BWQueries` instance handles all HTTP requests associated with queries in its attached project."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Typically, you'd import only the classes you plan on using, but for this demo all classes are listed except for superclasses which you do not use explicitly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bcr_api.bwproject import BWProject, BWUser\n",
    "from bcr_api.bwresources import BWQueries, BWGroups, BWAuthorLists, BWSiteLists, BWLocationLists, BWTags, BWCategories, BWRules, BWMentions, BWSignals\n",
    "import datetime"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The library uses the Python logging module to tell you what it's doing; if desired you can control what sort of output you see by uncommenting one of the lines below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import logging\n",
    "logger = logging.getLogger(\"bcr_api\")\n",
    "\n",
    "#(Default) All logging messages enabled\n",
    "#logger.setLevel(logging.DEBUG)\n",
    "\n",
    "#Does not report URLs of API requests, but all other messages enabled\n",
    "#logger.setLevel(logging.INFO)\n",
    "\n",
    "#Report only errors and warnings\n",
    "#logger.setLevel(logging.WARN)\n",
    "\n",
    "#Report only errors\n",
    "#logger.setLevel(logging.ERROR)\n",
    "\n",
    "#Disable logging\n",
    "#logger.setLevel(logging.CRITICAL)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Project"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you use the API for the first time you have to authenticate with Brandwatch. This will get you an access token. The access token is stored in a credentials file (`tokens.txt` in this example). Once you've authenticated your access token will be read from that file so you won't need to enter your password again (until your token expires).\n",
    "\n",
    "You can authenticate from command line using the provided console script `bcr-authenticate`:\n",
    "\n",
    "```\n",
    "$ bcr-authenticate\n",
    "Please enter your Brandwatch credentials below\n",
    "Username: example@example\n",
    "Password:\n",
    "Authenticating user: example@example\n",
    "Writing access token for user: example@example\n",
    "Writing access token for user: example@example\n",
    "Success! Access token: 00000000-0000-0000-0000-000000000000\n",
    "```\n",
    "\n",
    "Alternatively, you can authenticate directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "BWUser(username=\"user@example.com\", password=\"YOUR_PASSWORD\", token_path=\"tokens.txt\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you have authenticated you can load your project:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "YOUR_ACCOUNT = your_account\n",
    "YOUR_PROJECT = your_project\n",
    "\n",
    "project = BWProject(username=YOUR_ACCOUNT, project=YOUR_PROJECT)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we really begin, please note that you can get documentation for any class or function by viewing the help documentation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(BWProject)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Queries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we create some objects which can manipulate queries and groups in our project:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "queries = BWQueries(project)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check what queries already exist in the account"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "queries.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also upload queries directly via the API by handing the \"name\" and \"booleanQuery\" to the upload funcion. You can optionally pass in a \"startDate\" to specify when the query data should be collected from.\n",
    "\n",
    "The BWQueries class inserts default values for a number of fields, such as \"languages\", \"contentSources\" and \"description\", but we can override the defaults by including them as keyword arguments if we want. \n",
    "\n",
    "Upload accepts two boolean keyword arguments - \"create_only\" and \"modify_only\" (both defaulting to False) - which specifies what API verbs the function is allowed to use; for instance, if we set \"create_only\" to True then the function will post a new query if it can and otherwise it will do nothing.  Note: this is true of all upload functions in this package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "queries.upload(name = \"Brandwatch Engagement\", \n",
    "             booleanQuery = \"engagingWith:brandwatch\",)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you're uploading many queries at a time, you can upload in batches.  This saves API calls and allows you to just pass in a list rather than iterating over the upload function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "queries.upload_all([\n",
    "    {\"name\":\"Pets\", \n",
    "     \"booleanQuery\":\"dogs OR cats\"}, \n",
    "        \n",
    "    {\"name\":\"ice cream cake\", \n",
    "     \"booleanQuery\":\"(\\\"ice cream\\\" OR icecream) AND (cake)\"},\n",
    "        \n",
    "    {\"name\": \"Test1\",\n",
    "     \"booleanQuery\": \"dog OR cat\"},\n",
    "    \n",
    "    {\"name\": \"Test2\",\n",
    "     \"booleanQuery\": \"mouse OR rat\"},\n",
    "        \n",
    "    {\"name\": \"Test3\",\n",
    "     \"booleanQuery\": \"magpie OR parrot\"},\n",
    "    \n",
    "    {\"name\": \"Test4\",\n",
    "     \"booleanQuery\": \"llama OR rhea\"},\n",
    "    \n",
    "    {\"name\": \"Test5\",\n",
    "     \"booleanQuery\": \"capybara OR quokka\"},\n",
    "\n",
    "    ])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can delete queries one at a time, or in batches."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "queries.delete(name = \"Pets\")\n",
    "queries.delete_all([\"ice cream cake\", \"Test2\", \"Test3\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Groups"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You'll notice that a lot of the things that were true for queries are also true for groups.  Many of the functions are nearly identical with any adaptations necessary handled behind the scenes for ease of use.\n",
    "\n",
    "Again (as with queries), we need to create an object with which we can manipulate groups within the account"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups = BWGroups(project)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And can check for exisiting groups in the same way as before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's check which queries are in each group in the account"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for group in groups.names:\n",
    "    print(group)\n",
    "    print(groups.get_group_queries(group))\n",
    "    print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can easily create a group with any preexisting queries.\n",
    "\n",
    "(Recall that upload accepts two boolean keyword arguments - \"create_only\" and \"modify_only\" (both defaulting to False) - which specifies what API verbs the function is allowed to use; for instance, if we set \"create_only\" to True then the function will post a new query if it can and otherwise it will do nothing.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups.upload(name = \"group 1\", queries = [\"Test4\", \"Test5\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or upload new queries and create a group with them, all in one call"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups.upload_queries_as_group(group_name = \"group 2\", \n",
    "                               query_data_list = [{\"name\": \"Test6\",\n",
    "                                           \"booleanQuery\": \"adcioahnanva\"},\n",
    "                                          \n",
    "                                          {\"name\": \"Test7\",\n",
    "                                           \"booleanQuery\": \"ioanvauhekanv;\"}])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can either delete just the group, or delete the group and the queries at the same time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups.delete(\"group 1\")\n",
    "print()\n",
    "groups.deep_delete(\"group 2\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Downloading Mentions (From a Query or a Group)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can download mentions from a Query or from a Group (the code does not yet support Channels)\n",
    "\n",
    "There is a function get_mentions() in the classes BWQueries and in BWGroups. They are used the same way.\n",
    "\n",
    "Be careful with time zones, as they affect the date range and alter the results. If you're using the same date range for all your operations, I reccomend setting some variables at the start with dates and time zones. \n",
    "\n",
    "Here, today is set to the current day, and start is set to 30 days ago. Each number is offset by one to make it accurate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "today = (datetime.date.today() + datetime.timedelta(days=1)).isoformat() + \"T05:00:00\"\n",
    "start = (datetime.date.today() - datetime.timedelta(days=2)).isoformat() + \"T05:00:00\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To use get_mentions(), the minimum parameters needed are name (query name in this case, or group name if downloading mentions from a group) and the start date."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filtered = queries.get_mentions(name = \"Test5\",\n",
    "                                startDate = start, \n",
    "                                endDate = today)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are over a hundred filters you can use to only download the mentions that qualify. see the full list in the file filters.py\n",
    "\n",
    "Here, different filters are used, which take different data types. filters.py details which data type is used with each filter. Some filters, like sentiment and xprofession below, have a limited number of settings to choose from.\n",
    "\n",
    "You can filter many things by inclusion or exclusion. The x in xprofession stands for exclusion, for example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filtered = queries.get_mentions(name = \"Test5\", \n",
    "                                startDate = start, \n",
    "                                endDate = today, \n",
    "                                sentiment = \"positive\", \n",
    "                                twitterVerified = False, \n",
    "                                impactMin = 50, \n",
    "                                xprofession = [\"Politician\", \"Legal\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To filter by tags, pass in a list of strings where each string is a tag name.\n",
    "\n",
    "You can filter by categories in two differnt ways: on a subcategory level or a parent category level.  To filter on a subcategory level, use the category keyword and pass in a dictionary, where each the keys are the parent categories and the values are lists of the subcategories.  To filter on a parent category level, use the parentCategory keyword and pass in a list of parent category names.\n",
    "\n",
    "Note: In the following call the parentCategory filter is redundant, but executed for illustrative purposes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filtered = queries.get_mentions(name = \"Test5\", \n",
    "                                startDate = start, \n",
    "                                endDate = today,\n",
    "                                parentCategory = [\"Colors\", \"Days\"],\n",
    "                                category = {\"Colors\": [\"Blue\", \"Yellow\"], \n",
    "                                            \"Days\": [\"Monday\"]}, \n",
    "                                tag = [\"Tastes Good\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filtered[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can make many calls to aggregate data, just as you would in a BCR dashboard. For example, here we break down volume by sentiment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sentiment_volumes = queries.get_chart(name='Test1', \n",
    "                                      startDate=start, \n",
    "                                      endDate=today,\n",
    "                                      y_axis='volume', \n",
    "                                      x_axis='sentiment',\n",
    "                                      breakdown_by='queries')\n",
    "sentiment_volumes['results']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Categories"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instantiate a BWCategories object by passing in your project as a parameter, which loads all of the categories in your project.\n",
    "\n",
    "Print out ids to see which categories are currently in your project. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "categories = BWCategories(project)\n",
    "\n",
    "categories.ids"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Upload categories individually with upload(), or in bulk with upload_all(). If you are uploading many categories, it is more efficient to use upload_all().\n",
    "\n",
    "For upload(), pass in name and children. name is the string which represents the parent category, and children is a list of dictionaries where each dictionary is a child category- its key is \"name\" and its value is the name of the child category.\n",
    "\n",
    "By default, a category will allow multiple subcategories to be applied, so the keyword argument \"multiple\" is set to True. You can manually set it to False by passing in multipe=False as another parameter when uploading a category.\n",
    "\n",
    "For upload_all(), pass in a list of dictionaries, where each dictionary corrosponds to one category, and contains the parameters described above."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's upload a category and then check what's in the category."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "categories.upload(name = \"Droids\", \n",
    "                  children = [\"r2d2\", \"c3po\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's upload a few categories and then check what parent categories are in the system"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "categories.upload_all([{\"name\":\"month\", \n",
    "                        \"children\":[\"January\",\"February\"]}, \n",
    "                       {\"name\":\"Time of Day\", \n",
    "                        \"children\":[\"morning\", \"evening\"]}])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To add children/subcategories, call upload() and pass in the parent category name and a list of the new subcategories to add. \n",
    "\n",
    "If you'd like to instead overwrite the existing subcategories with new subcategories, call upload() and pass in the parameter overwrite_children = True."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "categories.upload(name = \"Droids\", children = [\"bb8\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also possible to upload categories with the associated boolean and filters, as shown in the example below. To do this, you can use the separate `upload_rule_categories` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "child_categories_and_rules = [\n",
    "        {\"name\": \"Positive views on chocolate\",\n",
    "            \"rules\": [\n",
    "                {\"filter\": {\"search\": \"chocolate OR chocco*\",\n",
    "                        \"sentiment\": [\"positive\"],}\n",
    "                }\n",
    "            ]\n",
    "        },\n",
    "        {\"name\": \"Vanilla\",\n",
    "            \"rules\": [\n",
    "                {\"filter\": {\"search\": \"vanilla\",}\n",
    "                }\n",
    "            ]\n",
    "        }\n",
    "    ]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "categories.upload_rule_categories(name='ice cream views', children=child_categories_and_rules)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Please note that all rules which add categories or tags should now use the `BWCategories.upload_rule_categories()` and `BWTags.upload()` methods**, rather than using `BWRules`. This reflects updates to the BCR API outlined [here](https://developers.brandwatch.com/docs/retrieving-categories-2) and [here](https://developers.brandwatch.com/docs/retrieving-tags-2)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "categories.delete(name='ice cream views')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To rename a category, call rename(), with parameters name and new_name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "categories.rename(name = \"month\", new_name = \"Months\")\n",
    "categories.ids[\"Months\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can delete categories either individually with delete(), or in bulk with delete_all(). \n",
    "\n",
    "You also have the option to delete the entire parent category or just some of the subcategories.  \n",
    "\n",
    "To delete ALL CATEGORIES in a project, call clear_all_in_project with no parameters. Be careful with this one, and do not use unless you want to delete all categories in the current project."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First let's delete just some subcategories."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "categories.delete({\"name\": \"Months\", \"children\":[\"February\"]})\n",
    "categories.delete_all([{\"name\": \"Droids\", \"children\": [\"bb8\", \"c3po\"]}])\n",
    "categories.ids"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tags"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instantiate a BWTags object by passing in your project as a parameter, which loads all of the tags in your project.\n",
    "\n",
    "Print out ids to see which tags are currently in your project. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tags = BWTags(project)\n",
    "\n",
    "tags.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two ways to upload tags: individually and in bulk. When uploading many tags, it is more efficient to use upload_all. \n",
    "\n",
    "In upload, pass in the name of the tag.\n",
    "\n",
    "In upload_all, pass in a list of dictionaries, where each dictionary contains \"name\" as the key and the tag name as the its value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tags.upload(name = \"yellow\")\n",
    "tags.upload_all([{\"name\":\"green\"}, \n",
    "                 {\"name\":\"blue\"}, \n",
    "                 {\"name\":\"purple\"}])\n",
    "\n",
    "tags.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also possible to upload tags with the associated boolean and filters, as shown in the example below. You can specify multiple rules (searches and filters), but in this case we only have one rule to populate this tag with mentions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rules_for_tag = [\n",
    "                {\n",
    "                    \"filter\": {\n",
    "                        \"search\": \"cat OR cats\",\n",
    "                    }\n",
    "                },\n",
    "            ]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tags.upload(name='cats', rules=rules_for_tag)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To change the name of a tag, but mantain its id, upload it with keyword arguments name and new_name. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tags.upload(name = \"cats\", new_name = \"Felis catus\")\n",
    "\n",
    "tags.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As with categories, there are three ways of deleting tags. \n",
    "\n",
    "Delete one tag by calling delete and passing in a string, the name of the tag to delete\n",
    "\n",
    "Delete multiple tags by calling delete_all and passing in a list of strings, where each string is a name of a tag to delete\n",
    "\n",
    "To delete ALL TAGS in a project, call clear_all_in_project with no parameters. Be careful with this one, and do not use unless you want to delete all tags in the current project"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tags.delete(\"purple\")\n",
    "tags.delete_all([\"blue\", \"green\"])\n",
    "\n",
    "tags.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Brandwatch Lists"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: to avoid ambiguity between the python data type \"list\" and a Brandwatch author list, site list, or location list, the latter is referred to in this demo as a \"Brandwatch List.\"\n",
    "\n",
    "BWAuthorLists, BWSiteLists, BWLocationLists work almost identically.\n",
    "\n",
    "First, instantiate your the object which contains the Brandwatch Lists in your project, with your project as a the parameter. This will load the data from your project so you can see what's there, upload more Brandwatch Lists, edit existing Brandwatch Lists, and delete Brandwatch Lists from your project\n",
    "\n",
    "Printing out ids will show you the Brandwatch Lists (by name and ID) that are currently in your project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "authorlists = BWAuthorLists(project)\n",
    "authorlists.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To upload a Brandwatch List, pass in a name as a string and the contents of your Brandwatch List as a list of strings. The keyword \"authors\" is used for BWAuthorLists, shown below. The keyword \"domains\"is used for BWSiteLists. The keyword \"locations\" is used for BWLocationLists.\n",
    "\n",
    "To see the contents of a Brandwatch List, call get_list with the name as the parameter\n",
    "\n",
    "Uploading is done with either a POST call, for new Brandwatch Lists, or a PUT call, for existing Brandwatch Lists, where the ID of the Brandwatch Lists is mantained, so if you upload and then upload a list with the same name and different contents, the first upload will create a new Brandwatch List, and the second upload will modify the existing list and keep its ID. Similarly, you can change the name of an existing Brandwatch List by passing in both \"name\" and \"new_name\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "authorlists.upload(name = \"Writers\", \n",
    "                   authors = [\"Edward Albee\", \"Tenessee Williams\", \"Anna Deavere Smith\"])\n",
    "\n",
    "authorlists.get(\"Writers\")[\"authors\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "authorlists.upload(name = \"Writers\", \n",
    "                   new_name = \"Playwrights\", \n",
    "                   authors = [\"Edward Albee\", \"Tenessee Williams\", \"Anna Deavere Smith\", \"Susan Glaspell\"])\n",
    "\n",
    "authorlists.get(\"Playwrights\")[\"authors\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To add items to a Brandwatch List without reentering all of the existing items, call add_items "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "authorlists.add_items(name = \"Playwrights\", \n",
    "                      items = [\"Eugene O'Neill\"])\n",
    "\n",
    "authorlists.get(\"Playwrights\")[\"authors\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To delete a Brandwatch List, pass in its name. Note the ids before the Brandwatch List is deleted, compared to after it is deleted. The BWLists object is updated to reflect the Brandwatch Lists in the project after each upload and each delete"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "authorlists.names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "authorlists.delete(\"Playwrights\")\n",
    "\n",
    "authorlists.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The only difference between how you use BWAuthorlists compared to how you use BWSiteLists and BWLocationLists is the parameter which is passed in. \n",
    "\n",
    "BWAuthorlists:\n",
    "\n",
    "authors = [\"edward albee\", \"tenessee williams\", \"Anna Deavere Smith\"]\n",
    "\n",
    "BWSiteLists:\n",
    "\n",
    "domains = [\"github.com\", \"stackoverflow.com\", \"docs.python.org\"]\n",
    "\n",
    "*BWLocationLists:\n",
    "\n",
    "locations = [{\"id\": \"mai4\", \"name\": \"Maine\", \"type\": \"state\", \"fullName\": \"Maine, United States, North America\"},   \n",
    "{\"id\": \"verf\", \"name\": \"Vermont\", \"type\": \"state\", \"fullName\": \"Vermont, United States, North America\"},    \n",
    "{\"id\": \"rho4\", \"name\": \"Rhode Island\", \"type\": \"state\", \"fullName\": \"Rhode Island, United States, North America\"} ]\n",
    "\n",
    "*Requires dictionary of location data instead of a string\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instantiate a BWRules object by passing in your project as a parameter, which loads all of the rules in your project.\n",
    "\n",
    "Print out names and IDs to see which rules are currently in your project. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rules = BWRules(project)\n",
    "rules.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Every rule must have a name, an action, and filters.\n",
    "\n",
    "The first step to creating a rule through the API is to prepare filters by calling filters(). \n",
    "\n",
    "If your desired rules applies to a query (or queries), include queryName as a filter and pass in a list of the queries you want to apply it to.\n",
    "\n",
    "There are over a hundred filters you can use to only download the mentions that qualify. See the full list in the file filters.py.  Here, different filters are used, which take different data types. filters.py details which data type is used with each filter. Some filters, like sentiment and xprofession below, have a limited number of settings to choose from.  You can filter many things by inclusion or exclusion. The x in xprofession stands for exclusion, for example.\n",
    "\n",
    "If you include search terms, be sure to use nested quotes - passing in \"cat food\" will result in a search that says cat food (i.e. cat AND food)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filters = rules.filters(queryName = \"Test1\", \n",
    "                        sentiment = \"positive\", \n",
    "                        twitterVerified = False, \n",
    "                        impactMin = 50, \n",
    "                        xprofession = [\"Politician\", \"Legal\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filters = rules.filters(queryName = [\"Test1\", \"Test4\"], \n",
    "                        search = '\"cat food\" OR \"dog food\"')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The second step is to prepare the rule action by calling rule_action().\n",
    "\n",
    "For this function, you must pass in the action and setting. Lots of rule actions are available, but if you want to add categories or tags, these should be handled by uploading tags and associated rules at the same time by using `tags.upload()` or `categories.upload_rule_categories()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "action = rules.rule_action(action = \"priority\", \n",
    "                           setting = \"high\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The last step is to upload!\n",
    "\n",
    "Pass in the name, filters, and action.   Scope is optional - it will default to query if queryName is in the filters and otherwise be set to project.  Backfill is also optional - it will default to False.\n",
    "\n",
    "The upload() function will automatically check the validity of your search string and give a helpful error message if errors are found."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rules.upload(name = \"rule\", \n",
    "             scope = \"query\", \n",
    "             filter = filters, \n",
    "             ruleAction = action,\n",
    "             backfill = True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also upload rules in bulk.  Below we prepare a bunch of filters and actions at once."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filters1 = rules.filters(search = \"caknvfoga;vnaei\")\n",
    "filters2 = rules.filters(queryName = [\"Test1\"], search = \"(bloop NEAR/10 blorp)\")\n",
    "filters3 = rules.filters(queryName = [\"Test1\", \"Test4\"], search = '\"hello world\"')\n",
    "\n",
    "action1 = rules.rule_action(action = \"sentiment\", setting = \"positive\")\n",
    "action2 = rules.rule_action(action = \"starred\", setting = True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When uploading in bulk, it is helpful (but not necessary) to use the rules() function before uploading in order to keep the dictionaries organized."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rule1 = rules.rule(name = \"rule1\", \n",
    "                   filter = filters1, \n",
    "                   action = action1, \n",
    "                   scope = \"project\")\n",
    "\n",
    "rule2 = rules.rule(name = \"rule2\", \n",
    "                   filter = filters2, \n",
    "                   action = action2)\n",
    "\n",
    "rule3 = rules.rule(name = \"rule3\", \n",
    "                   filter = filters3, \n",
    "                   action = action1,\n",
    "                   backfill = True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rules.upload_all([rule1, rule2, rule3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As with other resources, we can delete, delete_all or clear_all_in_project"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rules.delete(name = \"rule\")\n",
    "rules.delete_all(names = [\"rule1\", \"rule2\", \"rule3\"])\n",
    "\n",
    "rules.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Signals"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instantiate a BWSignals object by passing in your project as a parameter, which loads all of the signals in your project.\n",
    "\n",
    "Print out ids to see which signals are currently in your project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "signals = BWSignals(project)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "signals.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, we can upload signals individually or in batch.\n",
    "\n",
    "You must pass at least a name, queries (list of queries you'd like the signal to apply to) and subscribers.  For each subscriber, you have to pass both an emailAddress and notificationThreshold.  The notificationThreshold will be a number 1, 2 or 3 - where 1 means send all notifications and 3 means send only high priority signals.\n",
    "\n",
    "Optionally, you can also pass in categories or tags to filter by.  As before, you can filter by an entire category with the keyword parentCategory or just a subcategory (or list of subcategories) with the keyword category.  An example of how to pass in each filter is shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "signals.upload(name= \"New Test\",\n",
    "               queries= [\"ice cream cake\"],\n",
    "               parentCategory = [\"Colors\"],\n",
    "               subscribers= [{\"emailAddress\": \"test12345@brandwatch.com\", \"notificationThreshold\": 1}])\n",
    "\n",
    "signals.upload_all([{\"name\": \"Signal Me\",\n",
    "                    \"queries\": [\"ice cream cake\"],\n",
    "                    \"category\": {\"Colors\": [\"Blue\", \"Yellow\"]},\n",
    "                    \"subscribers\": [{\"emailAddress\": \"testaddress123@brandwatch.com\", \"notificationThreshold\": 3}]},\n",
    "                   {\"name\": \"Signal Test\",\n",
    "                    \"queries\": [\"ice cream cake\"],\n",
    "                    \"tag\": [\"Tastes Good\"],\n",
    "                    \"subscribers\": [{\"emailAddress\": \"exampleemail@brandwatch.com\", \"notificationThreshold\": 2}]}])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "signals.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Signals can be deleted individually or in bulk."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "signals.delete(\"New Test\")\n",
    "signals.delete_all([\"Signal Me\", \"Signal Test\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "signals.names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Patching Mentions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To patch the metadata on mentions, whether those mentions come from queries or from groups, you must first instantiate a BWMentions object and pass in your project as a parameter. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mentions = BWMentions(project)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filtered = queries.get_mentions(name = \"ice cream cake\", \n",
    "                                startDate = start, \n",
    "                                endDate = today,\n",
    "                                parentCategory = [\"Colors\", \"Days\"],\n",
    "                                category = {\"Colors\": [\"Blue\", \"Yellow\"], \n",
    "                                            \"Days\": [\"Monday\"]}, \n",
    "                                tag = [\"Tastes Good\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "if you don't want to upload your tags and categories ahead of time, you don't have to! BWMentions will do that for you, but if there are a lot of differnet tags/categories, it's definitely more efficient to upload them in bulk ahead of time"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For this example, i'm arbitrarily patching a few of the mentions, rather than all of them"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mentions.patch_mentions(filtered[0:10], action = \"addTag\", setting = [\"cold\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mentions.patch_mentions(filtered[5:12], action = \"starred\", setting = True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mentions.patch_mentions(filtered[6:8], action = \"addCategories\", setting = {\"color\":[\"green\", \"blue\"]})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}