1.3_company_identifiers.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "253dc99c-43f7-42dc-b214-b786d78f2632",
   "metadata": {},
   "source": [
    "# Translating Identifiers Into Factiva Codes\n",
    "\n",
    "This notebook shows how to translate supported company identifiers into Factiva Codes. This is usually done in pre-news data selection when there's a existing list of companies for which news content will be collected.\n",
    "\n",
    "In this notebook...\n",
    "* [Dependencies and Initialisation](#dependencies-and-initialisation)\n",
    "* [The Taxonomy Class](#the-taxonomy-class)\n",
    "* [Translating one or multiple identifiers](#translating-one-or-multiple-identifiers)\n",
    "* [Next Steps](#next-steps)\n",
    "\n",
    "**_NOTE_**: This notebook was tested using the [`factiva-analytics`](https://factiva-analytics-python.readthedocs.io/) Python package version **0.3.13** (Sep 2024) and [Factiva Analytics v3.0](https://developer.dowjones.com/site/docs/factiva_apis/factiva_analytics_apis/factiva_snapshots_api/snapshots_3_0/index.gsp#) endpoints."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "280091e1-bb79-4fa2-b97b-a79bf825c10c",
   "metadata": {},
   "source": [
    "## Dependencies and Initialisation\n",
    "Import statements and environment initialisation using the package `dotenv`. More details in the [Configuration notebook](0.2_configuration.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "0a4ca2c9-338a-40e7-a65d-7509fcd9cad0",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Using the Factiva Analytics Python Package version 0.3.13\n"
     ]
    }
   ],
   "source": [
    "import factiva.analytics as fa\n",
    "from factiva.analytics import FactivaTaxonomy, FactivaTaxonomyCategories\n",
    "from dotenv import load_dotenv\n",
    "load_dotenv()\n",
    "print(f\"Using the Factiva Analytics Python Package version {fa.__version__}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ae36196d-959e-4f92-a6cb-f55b927e03e0",
   "metadata": {},
   "source": [
    "## The FactivaTaxonomy Class\n",
    "\n",
    "The taxonomy class interacts with the API and thus, requires to authenticate by using the user_key parameter. By default it is taken from the environment variable `FACTIVA_USERKEY`.\n",
    "\n",
    "To get started, show the list of available identifiers can be obtained from the class `FactivaTaxonomyCategories`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "065e21e2-326b-45b7-8943-e655c40de437",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['hierarchySubject', 'hierarchyRegion', 'hierarchyIndustry', 'companies', 'executives']\n"
     ]
    }
   ],
   "source": [
    "t = FactivaTaxonomy()\n",
    "print([c.value for c in FactivaTaxonomyCategories])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "95a84d8a-2275-4bdb-b33f-f2ced6184f60",
   "metadata": {},
   "source": [
    "## Translating one or multiple identifiers\n",
    "\n",
    "The function `<FactivaTaxonomy>.get_company` is used in either case, the difference relies in the passed `company_codes` parameter type: `str` for one code or `list` for multiple codes.\n",
    "\n",
    "- **code_type**: str\n",
    "        String containing the company code type. Possible values are\n",
    "        `cusip`, `ticker`, `isin`, `sedol`\n",
    "- **company_codes**: str or list\n",
    "        Value or list of company_codes values.\n",
    "        \n",
    "Examples:\n",
    "\n",
    "```Python\n",
    "t.get_company('isin', company_codes='PLUNMST00014')\n",
    "\n",
    "             id  fcode                                common_name\n",
    "0  PLUNMST00014  UNSYT  Unima 2000 Systemy Teleinformatyczne S.A.\n",
    "\n",
    "company_list = ['US0378331005', 'US0231351067', 'US5949181045']\n",
    "t.get_company('isin', company_codes=company_list)\n",
    "\n",
    "             id   fcode      common_name\n",
    "0  US5949181045  MCROST  Microsoft Corp.\n",
    "1  US0231351067  AMZCOM  Amazon.com Inc.\n",
    "2  US0378331005   APPLC       Apple Inc.\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "149a5087-948b-4053-90be-35497708133a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>id</th>\n",
       "      <th>fcode</th>\n",
       "      <th>common_name</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>PLUNMST00014</td>\n",
       "      <td>UNSYT</td>\n",
       "      <td>Unima 2000 Systemy Teleinformatyczne S.A.</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "             id  fcode                                common_name\n",
       "0  PLUNMST00014  UNSYT  Unima 2000 Systemy Teleinformatyczne S.A."
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "t.get_company('isin', company_codes='PLUNMST00014')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "e0ffe94d-3ff7-4643-82d5-1136ad7b0bd4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>id</th>\n",
       "      <th>fcode</th>\n",
       "      <th>common_name</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>US5949181045</td>\n",
       "      <td>MCROST</td>\n",
       "      <td>Microsoft Corp.</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>US0378331005</td>\n",
       "      <td>APPLC</td>\n",
       "      <td>Apple Inc.</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>US0231351067</td>\n",
       "      <td>AMZCOM</td>\n",
       "      <td>Amazon.com Inc.</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "             id   fcode      common_name\n",
       "0  US5949181045  MCROST  Microsoft Corp.\n",
       "1  US0378331005   APPLC       Apple Inc.\n",
       "2  US0231351067  AMZCOM  Amazon.com Inc."
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "company_list = ['US0378331005', 'US0231351067', 'US5949181045']\n",
    "t.get_company('isin', company_codes=company_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6327f3e",
   "metadata": {},
   "source": [
    "# Next Steps\n",
    "\n",
    "* Take a look at the different [taxonomies](1.2_taxonomies_djid.ipynb) applied to the data, which can be used to select and later work with the downloaded content.\n",
    "* Run an [explain](1.4_snapshot_explain.ipynb) to get a quick idea about how to query the archive.\n",
    "* Explore the available fields in the archive and how to apply conditions on them according to the [query reference](2.1_complex_large_queries.ipynb)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "fadev",
   "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.12.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}