{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b9e06507",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "A Security Master provides financial product reference data and is a foundational building block of any quantitative financial analytics engine. The core component of Goldman Sachs' Security Master is symbology, the data necessary to map from one identifier to another. Clients can retrieve this data via the GS Quant SDK."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d9844f7",
   "metadata": {},
   "source": [
    "## Getting Started\n",
    "Set up a GsSession. You must input the client_id and client_secret of an application with access to Security Master. For more information on the product and on how to get access, please contact [GS Data Services](mailto:data-services@gs.com)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "333f29f9",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gs_quant.session import Environment, GsSession\n",
    "GsSession.use(client_id='client_id', client_secret='client_secret')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be357aad",
   "metadata": {},
   "source": [
    "Set source to Security Master (or else it will default to Asset Service)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a9288aa9",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gs_quant.markets.securities import SecurityMaster, SecurityMasterSource\n",
    "SecurityMaster.set_source(SecurityMasterSource.SECURITY_MASTER)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e23cde3a",
   "metadata": {},
   "source": [
    "## Querying\n",
    "Retrieve a security by identifier. The get_asset method returns identifiers at a point in time specified by the `as_of` parameter (which should be set to 2021-01-01 or later, given the history available in Security Master)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08cc971f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "from gs_quant.markets.securities import SecurityIdentifier, SecurityMaster\n",
    "\n",
    "asset = SecurityMaster.get_asset('GS UN', SecurityIdentifier.BBID, as_of=datetime.date(2021, 1, 5))\n",
    "print(asset, '\\n')\n",
    "asset.get_identifiers()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a00d2241",
   "metadata": {},
   "source": [
    "You can use SecurityIdentifier members to pull out identifier values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "31696f61",
   "metadata": {},
   "outputs": [],
   "source": [
    "asset.get_identifiers()[SecurityIdentifier.BBID.value]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "397888ae",
   "metadata": {},
   "source": [
    "## Bulk Querying\n",
    "\n",
    "#### History\n",
    "You can retrieve identifier history (from 2021-01-01 onwards) for a list of assets. The following example also shows a ticker change."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "002a5ab4",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "from gs_quant.markets.securities import SecurityIdentifier, SecurityMaster\n",
    "\n",
    "ids = ['CTLP UW', 'TSLA UW', 'FB UW']\n",
    "as_of = datetime.datetime(2021, 6, 5)  # as-of-date used to map input IDs to assets\n",
    "start = datetime.datetime(2000, 1, 5)  # get identifier entries with update time after this time\n",
    "end = as_of  # get identifier entries with update time before this time\n",
    "identifiers = SecurityMaster.get_identifiers(ids, SecurityIdentifier.BBID, as_of=as_of, start=start, end=end)\n",
    "[identifier for identifier in identifiers['CTLP UW'] if identifier['type'] == SecurityIdentifier.TICKER.value]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "93597208",
   "metadata": {},
   "source": [
    "#### Point in Time\n",
    "\n",
    "You can retrieve point-in-time identifiers without specifying individual assets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5629db2b",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "from gs_quant.markets.securities import AssetType, SecurityMaster\n",
    "from gs_quant.target.common import AssetClass\n",
    "\n",
    "as_of = datetime.datetime(2021, 5, 1)\n",
    "identifiers = SecurityMaster.get_all_identifiers(AssetClass.Equity, [AssetType.STOCK], as_of=as_of)\n",
    "identifiers[next(iter(identifiers))]  # show identifiers for one of the retrieved securities"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "You can also use a generator to retrieve each page of results when needed - just call `next()`."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "import datetime\n",
    "from gs_quant.markets.securities import SecurityMaster\n",
    "\n",
    "generator = SecurityMaster.get_all_identifiers_gen(as_of=datetime.datetime(2021, 5, 1))\n",
    "page_1 = next(generator)\n",
    "page_2 = next(generator)\n",
    "page_3 = next(generator)\n",
    "# and so on... (keep in mind that a generator will raise StopIteration when it is done)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Mapping Between Identifiers\n",
    "\n",
    "To map from one ID to other IDs for the same security, use the `map_identifiers` function.\n",
    "For example, if we have a security \"GS UN\" and want to find its CUSIP over a certain date range: "
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "import datetime\n",
    "from gs_quant.markets.securities import SecurityMaster\n",
    "\n",
    "start = datetime.date(2021, 10, 11)\n",
    "end = datetime.date(2021, 10, 15)\n",
    "SecurityMaster.map_identifiers([\"GS UN\"], [SecurityIdentifier.CUSIP], start, end)\n"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.10"
  },
  "pycharm": {
   "stem_cell": {
    "cell_type": "raw",
    "source": [],
    "metadata": {
     "collapsed": false
    }
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}