jupyter_notebooks/connecting_to_the_barb_api_using_python.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "3ac80477-f4ab-47ab-8225-1848acdc85bd",
   "metadata": {},
   "source": [
    "# Connecting to the Barb API using python\n",
    "\n",
    "In this demo we will show you how to connect to the Barb API using Python. We will do this first without making use of the pybarb package (as you may wish to develop your own software from scratch). We will then show you how to use the pybarb package to make the same request.\n",
    "\n",
    "Note the full API documentation can be found [here](https://barb-api.co.uk/api-docs). \n",
    "\n",
    "It might also be useful to consult the [Getting Started](https://barb-api.co.uk/api-docs#section/Getting-started) section for information about authentication and basic API usage."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "71b57700-2491-4fdc-9cf6-c23e6c93a501",
   "metadata": {},
   "source": [
    "## Connecting to the API without pybarb\n",
    "\n",
    "First we set up our notebook with all the libraries we will need to access the API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "5b8df422-cc3d-4ba6-8b56-9ea09ec861ff",
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import json\n",
    "\n",
    "working_directory = '/path/to/your/dir/'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "da9fe2fd-238a-4c6e-9d4d-9f3ce2b377dd",
   "metadata": {},
   "source": [
    "### Getting the access token\n",
    "\n",
    "Following the steps in the [API Getting Started Guide ](https://barb-api.co.uk/api-docs#section/Getting-started) we run some python code to get an access token. This code uses your account details to get an access token from the API. Your creds.json file should include the email and password supplied by BARB. For example:\n",
    "\n",
    "```\n",
    "{\"email\": \"me@coppelia.io\", \"password\": \"INSERT PASSWORD\"}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "55309433-0176-4ce7-aebe-0897071ea01f",
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(working_directory + \"creds.json\") as file:\n",
    "    creds = json.load(file)\n",
    "api_root = \"https://barb-api.co.uk/api/v1/\"\n",
    "token_request_url = api_root + \"auth/token/\"\n",
    "response = requests.post(token_request_url, data = creds)\n",
    "access_token = json.loads(response.text)['access']\n",
    "headers = {'Authorization': 'Bearer {}'.format(access_token)}"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "dcfbe99e-998c-4d1f-8a47-9d34977ecdd8",
   "metadata": {},
   "source": [
    "### Using the access token to query the API\n",
    "\n",
    "Let's make a very simple call to the API to demonstrate that the access token works. We'll use the `get` method from the `requests` library to make a `GET` request to the `barb-api.co.uk/api/v1/panels` endpoint. We'll pass the access token as a parameter in the request.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "04f18439-ddf5-4164-b0ab-638d134330b9",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 1,\n",
      "        \"panel_region\": \"London - ITV,C4,ITV Breakfast\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 4,\n",
      "        \"panel_region\": \"Midlands -ITV,C4,ITV Breakfast\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 7,\n",
      "        \"panel_region\": \"North West\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 11,\n",
      "        \"panel_region\": \"Yorkshire\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 12,\n",
      "        \"panel_region\": \"North East\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 17,\n",
      "        \"panel_region\": \"Scotland - ITV,ITV Breakfast\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 18,\n",
      "        \"panel_region\": \"Wales & West Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 21,\n",
      "        \"panel_region\": \"South, South East & Channel Is\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 24,\n",
      "        \"panel_region\": \"East of England\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 27,\n",
      "        \"panel_region\": \"South West\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 30,\n",
      "        \"panel_region\": \"Ulster - ITV,C4,ITV Breakfast\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 33,\n",
      "        \"panel_region\": \"Border\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 37,\n",
      "        \"panel_region\": \"West\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 38,\n",
      "        \"panel_region\": \"Wales\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 39,\n",
      "        \"panel_region\": \"S4C - Total\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 40,\n",
      "        \"panel_region\": \"S4C - Indivs in non Welsh Sp H\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 41,\n",
      "        \"panel_region\": \"S4C - Welsh Speaking Indivs\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 48,\n",
      "        \"panel_region\": \"S4C - Indivs in Welsh Sp HH's\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 49,\n",
      "        \"panel_region\": \"S4C - Network\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 50,\n",
      "        \"panel_region\": \"BBC Network\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 51,\n",
      "        \"panel_region\": \"Online Network\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 58,\n",
      "        \"panel_region\": \"ITV Breakfast North,South,Mids\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 59,\n",
      "        \"panel_region\": \"ITV Breakfast England & Wales\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 61,\n",
      "        \"panel_region\": \"Mid-West Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 62,\n",
      "        \"panel_region\": \"West Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 63,\n",
      "        \"panel_region\": \"Yorkshire/North East Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 67,\n",
      "        \"panel_region\": \"North West/Border Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 68,\n",
      "        \"panel_region\": \"ITV,ITV Breakfast North Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 69,\n",
      "        \"panel_region\": \"South East Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 72,\n",
      "        \"panel_region\": \"Cable & DSAT Homes\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 74,\n",
      "        \"panel_region\": \"Channel 5 Ulster Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 75,\n",
      "        \"panel_region\": \"Channel 5 London Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 76,\n",
      "        \"panel_region\": \"Channel 5 North Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 77,\n",
      "        \"panel_region\": \"Channel 5 Scotland Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 79,\n",
      "        \"panel_region\": \"Channel 5 Part Network Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 80,\n",
      "        \"panel_region\": \"C4 Network\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 82,\n",
      "        \"panel_region\": \"C4 South - ITV Breakfast South\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 84,\n",
      "        \"panel_region\": \"C4 North\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 85,\n",
      "        \"panel_region\": \"C4 Scotland\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 87,\n",
      "        \"panel_region\": \"C4 - ITV Breakfast GB\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 88,\n",
      "        \"panel_region\": \"C4 England Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 89,\n",
      "        \"panel_region\": \"C4 London/South/Mids Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": true,\n",
      "        \"panel_code\": 90,\n",
      "        \"panel_region\": \"C4 London/South Macro\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 99,\n",
      "        \"panel_region\": \"ITV Network\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 100,\n",
      "        \"panel_region\": \"S4C Panel Boost Home\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 107,\n",
      "        \"panel_region\": \"Welsh Spk Ind In WSH - Northx\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 108,\n",
      "        \"panel_region\": \"Welsh Spk Ind In WSH - Westx\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 109,\n",
      "        \"panel_region\": \"Welsh Spk Ind in WSH - Southx\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 503,\n",
      "        \"panel_region\": \"BBC East Region\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 504,\n",
      "        \"panel_region\": \"BBC West Region\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 505,\n",
      "        \"panel_region\": \"BBC South West Region\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 506,\n",
      "        \"panel_region\": \"BBC South Region\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 507,\n",
      "        \"panel_region\": \"BBC Yorkshire & Lincolnshire\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 508,\n",
      "        \"panel_region\": \"BBC North East & Cumbria\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 509,\n",
      "        \"panel_region\": \"BBC North West Region\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 510,\n",
      "        \"panel_region\": \"BBC Scotland Region\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 511,\n",
      "        \"panel_region\": \"BBC Ulster Region\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 512,\n",
      "        \"panel_region\": \"BBC Wales Region\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 513,\n",
      "        \"panel_region\": \"BBC Midlands West\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 514,\n",
      "        \"panel_region\": \"BBC Midlands East\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 515,\n",
      "        \"panel_region\": \"BBC London\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 516,\n",
      "        \"panel_region\": \"BBC South East\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 670,\n",
      "        \"panel_region\": \"Broadband Network\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 750,\n",
      "        \"panel_region\": \"TV and/or online homes\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 751,\n",
      "        \"panel_region\": \"Online Multiple Screen Network\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 912,\n",
      "        \"panel_region\": \"Network Factoring - North East\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 927,\n",
      "        \"panel_region\": \"Network Factoring - SouthWest\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 930,\n",
      "        \"panel_region\": \"Network Factoring - Ulster\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 933,\n",
      "        \"panel_region\": \"Network Factoring - Border\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 937,\n",
      "        \"panel_region\": \"Network Factoring - HTV West\"\n",
      "    },\n",
      "    {\n",
      "        \"is_macro_region\": false,\n",
      "        \"panel_code\": 941,\n",
      "        \"panel_region\": \"Network - Wales\"\n",
      "    }\n",
      "]\n"
     ]
    }
   ],
   "source": [
    "api_url = api_root + \"panels/\"\n",
    "response = requests.get(url = api_url,headers=headers)\n",
    "panels = response.json()\n",
    "print(json.dumps(panels, indent=4, sort_keys=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1a2f0cd",
   "metadata": {},
   "source": [
    "## Connecting to the API with pybarb\n",
    "\n",
    "pybarb handles the authentication and connection to the API for you. You can connect to the API by creating a new instance of the `BarbAPI` class. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "1d9c1dfe",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pybarb as pb\n",
    "\n",
    "# Read in Barb API credentials\n",
    "with open(\"/Users/simon_business/Documents/disposable/clients/BARB/creds.json\") as file:\n",
    "    creds = json.load(file)\n",
    "\n",
    "# Create a BarbAPI object and connect\n",
    "barb_api = pb.BarbAPI(creds)\n",
    "barb_api.connect()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53c8c906",
   "metadata": {},
   "source": [
    "It is also a lot easier to query the endpoints in pybarb as we can simply use some of the predefined methods. For example, here is how to get a list of the Barb panels:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "5d9ac66f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['London - ITV,C4,ITV Breakfast',\n",
       " 'Midlands -ITV,C4,ITV Breakfast',\n",
       " 'North West',\n",
       " 'Yorkshire',\n",
       " 'North East',\n",
       " 'Scotland - ITV,ITV Breakfast',\n",
       " 'Wales & West Macro',\n",
       " 'South, South East & Channel Is',\n",
       " 'East of England',\n",
       " 'South West',\n",
       " 'Ulster - ITV,C4,ITV Breakfast',\n",
       " 'Border',\n",
       " 'West',\n",
       " 'Wales',\n",
       " 'S4C - Total',\n",
       " 'S4C - Indivs in non Welsh Sp H',\n",
       " 'S4C - Welsh Speaking Indivs',\n",
       " \"S4C - Indivs in Welsh Sp HH's\",\n",
       " 'S4C - Network',\n",
       " 'BBC Network',\n",
       " 'Online Network',\n",
       " 'ITV Breakfast North,South,Mids',\n",
       " 'ITV Breakfast England & Wales',\n",
       " 'Mid-West Macro',\n",
       " 'West Macro',\n",
       " 'Yorkshire/North East Macro',\n",
       " 'North West/Border Macro',\n",
       " 'ITV,ITV Breakfast North Macro',\n",
       " 'South East Macro',\n",
       " 'Cable & DSAT Homes',\n",
       " 'Channel 5 Ulster Macro',\n",
       " 'Channel 5 London Macro',\n",
       " 'Channel 5 North Macro',\n",
       " 'Channel 5 Scotland Macro',\n",
       " 'Channel 5 Part Network Macro',\n",
       " 'C4 Network',\n",
       " 'C4 South - ITV Breakfast South',\n",
       " 'C4 North',\n",
       " 'C4 Scotland',\n",
       " 'C4 - ITV Breakfast GB',\n",
       " 'C4 England Macro',\n",
       " 'C4 London/South/Mids Macro',\n",
       " 'C4 London/South Macro',\n",
       " 'ITV Network',\n",
       " 'S4C Panel Boost Home',\n",
       " 'Welsh Spk Ind In WSH - Northx',\n",
       " 'Welsh Spk Ind In WSH - Westx',\n",
       " 'Welsh Spk Ind in WSH - Southx',\n",
       " 'BBC East Region',\n",
       " 'BBC West Region',\n",
       " 'BBC South West Region',\n",
       " 'BBC South Region',\n",
       " 'BBC Yorkshire & Lincolnshire',\n",
       " 'BBC North East & Cumbria',\n",
       " 'BBC North West Region',\n",
       " 'BBC Scotland Region',\n",
       " 'BBC Ulster Region',\n",
       " 'BBC Wales Region',\n",
       " 'BBC Midlands West',\n",
       " 'BBC Midlands East',\n",
       " 'BBC London',\n",
       " 'BBC South East',\n",
       " 'Broadband Network',\n",
       " 'TV and/or online homes',\n",
       " 'Online Multiple Screen Network',\n",
       " 'Network Factoring - North East',\n",
       " 'Network Factoring - SouthWest',\n",
       " 'Network Factoring - Ulster',\n",
       " 'Network Factoring - Border',\n",
       " 'Network Factoring - HTV West',\n",
       " 'Network - Wales']"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "barb_api.list_panels()"
   ]
  }
 ],
 "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.9.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}