updated for new v4 API

Author: rahulbot

MC01 - setup.ipynb

@@ -7,14 +7,12 @@
     "Media Cloud: Setting up Your Environment\n",
     "========================================\n",
     "\n",
-    "[Media Cloud](https://mediacloud.org) is an open-source platform for media analysis. It is a collaborative academic project supported by various non-profit foundations since 2011. You can use our various online tools to investigate news coverage about your topic of interest, and all the same information is available via a rich API.\n",
+    "[Media Cloud](https://mediacloud.org) is an open-source platform for media analysis. It is a collaborative academic project supported by various non-profit foundations since 2011. It is now led by a consortium of [University of Massachusetts Amherst](https://publicinfrastructure.org), [Northeastern University](http://dataculture.northeastern.edu), the [Media Ecosystems Analysis Group](https://www.mediaecosystems.org). You can use our various online tools to investigate news coverage about your topic of interest, and all the same information is available via a rich API.\n",
     "\n",
-    "This set of notebooks is a brief introduction to the API. It covers many of the most common operations we see researchers performing. The API is fully featured, so much so that [all our web-based tools](https://tools.mediacloud.org/#/home) are built on top of it.\n",
+    "This set of notebooks is a brief introduction to the API. It covers many of the most common operations we see researchers performing. The API is fully featured, so much so that [all our web-based tools](https://search.mediacloud.org/) are built on top of it.\n",
     "\n",
     "Relevant references:\n",
-    "* Our [a Python client for the api on PyPi](https://pypi.org/project/mediacloud/)\n",
-    "* The [general Media Cloud API specification](https://github.com/berkmancenter/mediacloud/blob/master/doc/api_2_0_spec/api_2_0_spec.md)\n",
-    "* The [topic-mapper specific Media Cloud API Specification](https://github.com/berkmancenter/mediacloud/blob/master/doc/api_2_0_spec/topics_api_2_0_spec.md)"
+    "* Our [a Python client for the api on PyPi](https://pypi.org/project/mediacloud/)"
    ]
   },
   {
@@ -23,19 +21,14 @@
    "source": [
     "## Setup Your API Key for this Tutorial\n",
     "\n",
-    "You need to instantiate a client with your **private** API key. This key is linked to your account, and has a quota attached to it so you don't blow up our servers. If you run into the quota then you will see errors returned in your API calls. Email us if you need to increase your quota.\n",
+    "You need to instantiate a client with your **private** API key. This key is linked to your account, and has a quota attached to it so you don't blow up our servers. If you use up your quota then you will see errors returned in your API calls. It is reset automatically every week. Email us if you need to increase your quota.\n",
     "\n",
     "To obtain your api key, you can:\n",
-    "1. [login to any of our tools](https://tools.mediacloud.org/)\n",
+    "1. [login to any of our tools](https://search.mediacloud.org/sign-in)\n",
     "2. click the little person icon in the top right, then select \"profile\"\n",
     "3. copy your API key from where it is shown in the list of information about your account\n",
     "\n",
-    "For this tutorial, we decided to use the commonly used [`python-dotenv`](https://pypi.org/project/python-dotenv/) library to load this magic string in each notebook file without exposing it.\n",
-    "\n",
-    "1. In this Jupyter Lab hosted on Binder, select File -> Open from Path from the menu bar\n",
-    "2. Type in \".env\" and click Open\n",
-    "3. Replace \"MY_MC_API_KEY\" with your API key (from your profile page)\n",
-    "4. Select File -> Save"
+    "For this tutorial, we decided to include a `MC_API_KEY` python constant at the top of each notebook. Replace the placeholder value with your api key and then you're off."
    ]
   },
   {
@@ -55,8 +48,8 @@
    "source": [
     "# If you are running this locally (not on Binder), then you should install the requirements. If you are using this on\n",
     "# Binder then all of these will be installed for you automatically.\n",
-    "#import sys\n",
-    "#!{sys.executable} -m pip install -r requirements.txt"
+    "import sys\n",
+    "!{sys.executable} -m pip install -r requirements.txt"
    ]
   },
   {
@@ -65,8 +58,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from dotenv import load_dotenv\n",
-    "load_dotenv()  # load config from .env file"
+    "import os, mediacloud.api\n",
+    "from importlib.metadata import version\n",
+    "# Set your personal API KEY\n",
+    "MC_API_KEY = 'MY_API_KEY'\n",
+    "search_api = mediacloud.api.SearchApi(MC_API_KEY)\n",
+    "f'Using Media Cloud python client v{version(\"mediacloud\")}'"
    ]
   },
   {
@@ -75,12 +72,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import os, mediacloud.api\n",
-    "# Read your personal API key from that .env file \n",
-    "my_mc_api_key = os.getenv('MC_API_KEY')\n",
-    "# A convention we use is to name your api client `mc`\n",
-    "mc = mediacloud.api.MediaCloud(my_mc_api_key)\n",
-    "mediacloud.__version__"
+    "import datetime as dt\n",
+    "# make sure your connection and API key work by asking for the total count of in 2023\n",
+    "results = search_api.story_count('*', dt.date(2023,1,1), dt.date(2023,12,31))\n",
+    "results"
    ]
   },
   {
@@ -89,25 +84,22 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# make sure your connection and API key work by asking for the high-level system statistics\n",
-    "mc.stats()"
+    "# or print it out as a nice json tree - we'll use this later (only works in Jupyter Lab)\n",
+    "from IPython.display import JSON\n",
+    "JSON(results)"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "# or print it out as a nice json tree - we'll use this later (only works in Jupyter Lab)\n",
-    "from IPython.display import JSON\n",
-    "JSON(mc.stats())"
-   ]
+   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -121,7 +113,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.10.1"
   }
  },
  "nbformat": 4,