docs/examples/academy/19. Querying the SDK.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Module 4\n",
    "\n",
    "## Video 19: Querying the SDK\n",
    "**Python for the Energy Industry**\n",
    "\n",
    "To access data from a given endpoint, we do a 'search', which returns all data matching a given criteria. \n",
    "\n",
    "Note the Vessels endpoint documentation can be [found here](https://vortechsa.github.io/python-sdk/endpoints/vessels/)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2020-12-10 14:56:08,231 vortexasdk.client — WARNING — You are using vortexasdk version 0.26.0, however version 0.27.1 is available.\n",
      "You should consider upgrading via the 'pip install vortexasdk --upgrade' command.\n",
      "[{'call_sign': 'SVBC9', 'dead_weight': 299999, 'gross_tonnage': 161273, 'id': '508bc4b650b1eb69c0054c6bc3b3f40996c032f74e0fca06e344cec0f6bf8922', 'imo': 9532757, 'mmsi': 241089000, 'name': 'OCEANIS', 'to_bow': 278, 'to_port': 52, 'to_starboard': 27, 'to_stern': 33, 'related_names': ['OCEANIS'], 'current_product_type': [{'cargo_movement_id': '881caebc9311dd066c59927a123f6dc0881caebc9311dd066c59927a123f6dc0', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}, {'cargo_movement_id': '3488985d684cf1f28e1b2b8dd6589efc3488985d684cf1f28e1b2b8dd6589efc', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}], 'year': 2011, 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}], 'ref_type': 'vessel', 'vessel_status': 'vessel_status_ballast', 'corporate_entities': [{'id': 'b429e8a788a7322474da2f79676b7a4329e801b6ba2810056656d144905323a9', 'label': 'KOCH', 'layer': 'commercial_owner', 'source': 'external', 'probability': 1}], 'leaf': True, 'vessel_class': 'vlcc_plus', 'cubic_capacity': 345374, 'tags': [], 'flag': [{'tag': 'vessel_flag_tag', 'flag': 'GR', 'flag_country': 'b6be463f6999751d74c53b68865247ce565e003583579498f2537892bc13c69a'}], 'scrubber': [{'tag': 'vessel_scrubber_tag', 'scrubber': '478fca39000c49d6', 'planned': False}], 'layer': ['vessel']}, {'call_sign': 'ONJS', 'dead_weight': 299010, 'gross_tonnage': 154133, 'id': 'b7d1484243d4d47dfa69d8cc00e772824dda2ee2fb95f39a421c35cc72c1f50e', 'imo': 9732553, 'mmsi': 205761000, 'name': 'AEGEAN', 'to_bow': 284, 'to_port': 49, 'to_starboard': 38, 'to_stern': 22, 'related_names': ['GENER8 OCEANUS'], 'current_product_type': [{'cargo_movement_id': '0b174d04c743dda4dfb359e91e5c1f430b174d04c743dda4dfb359e91e5c1f43', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}], 'year': 2016, 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}], 'ref_type': 'vessel', 'vessel_status': 'vessel_status_ballast', 'corporate_entities': [{'id': 'de606ae491f0678e4156c2ca54966080bad57384b8ca16977620fb1b73428080', 'label': 'Tankers International pool', 'layer': 'commercial_owner', 'source': 'external', 'probability': 1}], 'leaf': True, 'vessel_class': 'vlcc_plus', 'cubic_capacity': 337936, 'tags': [], 'flag': [{'tag': 'vessel_flag_tag', 'flag': 'BE', 'flag_country': 'b563622dd5a266e6a022036c867c746bef712c2b06fb6f73402af43548fe94ac'}], 'scrubber': [], 'layer': ['vessel']}, {'call_sign': 'ONJP', 'dead_weight': 441585, 'gross_tonnage': 234006, 'id': '80654ba60f0e99c417825c4281e53420197b4812390df3debf0c602f51d82237', 'imo': 9246633, 'mmsi': 205753000, 'name': 'OCEANIA', 'to_bow': 322, 'to_port': 58, 'to_starboard': 16, 'to_stern': 52, 'related_names': ['OCEANIA', 'TI OCEANIA'], 'current_product_type': [{'cargo_movement_id': 'eeceffbc8ce545abae1a5e495fe3465feeceffbc8ce545abae1a5e495fe3465f', 'product_type': [{'id': '5de0b00094e0fd7542c10f9f8a71b4008d55750f21dc905cda9b0f7f5f76bc08', 'layer': 'group', 'label': 'Dirty Petroleum Products'}, {'id': '1c107b4317bc2c85fb6c13cd7b28e8e0a02ec7fecc68afc2b68ca0545c835e1c', 'layer': 'group_product', 'label': 'Fuel Oil'}], 'active': True}, {'cargo_movement_id': 'f741ac7f24e1de2d03ccfd3621c4933bf741ac7f24e1de2d03ccfd3621c4933b', 'product_type': [{'id': '5de0b00094e0fd7542c10f9f8a71b4008d55750f21dc905cda9b0f7f5f76bc08', 'layer': 'group', 'label': 'Dirty Petroleum Products'}, {'id': '1c107b4317bc2c85fb6c13cd7b28e8e0a02ec7fecc68afc2b68ca0545c835e1c', 'layer': 'group_product', 'label': 'Fuel Oil'}], 'active': False}, {'cargo_movement_id': '135861d286b8756567a5d9fc794ae2fb135861d286b8756567a5d9fc794ae2fb', 'product_type': [{'id': '5de0b00094e0fd7542c10f9f8a71b4008d55750f21dc905cda9b0f7f5f76bc08', 'layer': 'group', 'label': 'Dirty Petroleum Products'}, {'id': '1c107b4317bc2c85fb6c13cd7b28e8e0a02ec7fecc68afc2b68ca0545c835e1c', 'layer': 'group_product', 'label': 'Fuel Oil'}], 'active': False}, {'cargo_movement_id': '5caf37fadb2396d172f25b1cc9ff4e2e5caf37fadb2396d172f25b1cc9ff4e2e', 'product_type': [{'id': '5de0b00094e0fd7542c10f9f8a71b4008d55750f21dc905cda9b0f7f5f76bc08', 'layer': 'group', 'label': 'Dirty Petroleum Products'}, {'id': '1c107b4317bc2c85fb6c13cd7b28e8e0a02ec7fecc68afc2b68ca0545c835e1c', 'layer': 'group_product', 'label': 'Fuel Oil'}], 'active': False}], 'year': 2003, 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}], 'ref_type': 'vessel', 'vessel_status': 'vessel_status_laden_known', 'corporate_entities': [{'id': '90978e12a1382d35a8e7d72681ca380f84ee366d413500789991fd5e6f8f3439', 'label': 'EURONAV', 'layer': 'charterer', 'source': 'external', 'probability': 1}, {'id': '90978e12a1382d35a8e7d72681ca380f84ee366d413500789991fd5e6f8f3439', 'label': 'EURONAV', 'layer': 'commercial_owner', 'source': 'external', 'probability': 1}], 'leaf': True, 'vessel_class': 'vlcc_plus', 'cubic_capacity': 490505, 'tags': [{'tag': 'vessel_fso_tag', 'start_timestamp': '2017-03-03T20:09:37+0000', 'end_timestamp': '2017-05-16T09:36:12+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2017-05-17T20:01:21+0000', 'end_timestamp': '2017-05-30T09:35:39+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2017-06-07T10:59:39+0000', 'end_timestamp': '2017-10-28T02:30:48+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2017-11-08T21:01:32+0000', 'end_timestamp': '2017-12-03T23:32:36+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2018-06-23T09:15:16+0000', 'end_timestamp': '2018-07-02T02:30:06+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2017-10-28T04:31:37+0000', 'end_timestamp': '2017-11-08T19:20:23+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2017-12-04T01:45:04+0000', 'end_timestamp': '2017-12-18T16:45:43+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2018-07-02T04:50:25+0000', 'end_timestamp': '2018-08-09T12:44:22+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2015-06-09T16:19:56+0000', 'end_timestamp': '2015-07-20T03:35:51+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2015-07-23T06:02:28+0000', 'end_timestamp': '2015-08-07T07:06:35+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2015-08-07T07:36:21+0000', 'end_timestamp': '2015-10-07T01:18:14+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2015-10-07T05:03:03+0000', 'end_timestamp': '2015-10-14T11:43:08+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2015-10-20T13:27:59+0000', 'end_timestamp': '2015-10-29T03:17:11+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2015-10-29T09:22:04+0000', 'end_timestamp': '2015-11-17T14:22:21+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2015-11-17T15:09:31+0000', 'end_timestamp': '2015-12-23T04:00:18+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2015-12-30T05:53:45+0000', 'end_timestamp': '2016-01-08T04:59:53+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-02-01T05:37:06+0000', 'end_timestamp': '2016-02-14T13:23:52+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-02-23T06:51:45+0000', 'end_timestamp': '2016-03-03T04:00:14+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-03-06T05:52:53+0000', 'end_timestamp': '2016-03-25T14:10:20+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-03-25T15:01:28+0000', 'end_timestamp': '2016-04-20T14:32:34+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-04-26T08:53:19+0000', 'end_timestamp': '2016-05-08T05:07:20+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-05-16T06:37:25+0000', 'end_timestamp': '2016-06-10T04:29:16+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-06-16T04:47:31+0000', 'end_timestamp': '2016-08-04T00:29:58+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-08-06T06:02:48+0000', 'end_timestamp': '2016-08-18T08:43:47+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-08-18T11:36:58+0000', 'end_timestamp': '2016-09-19T05:12:10+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-09-22T11:35:48+0000', 'end_timestamp': '2016-10-29T12:51:03+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-11-03T08:36:54+0000', 'end_timestamp': '2016-12-06T04:19:55+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-12-06T07:23:00+0000', 'end_timestamp': '2016-12-14T06:33:45+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-12-14T07:41:14+0000', 'end_timestamp': '2016-12-21T11:52:12+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2016-12-21T14:21:42+0000', 'end_timestamp': '2017-01-08T05:40:19+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2017-01-08T07:52:00+0000', 'end_timestamp': '2017-01-16T04:01:16+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2017-01-16T07:04:03+0000', 'end_timestamp': '2017-02-26T08:14:10+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2019-09-29T21:58:32+0000', 'end_timestamp': '2020-03-09T08:19:55+0000'}, {'tag': 'vessel_fso_tag', 'start_timestamp': '2020-03-09T08:28:43+0000'}], 'flag': [{'tag': 'vessel_flag_tag', 'flag': 'BE', 'flag_country': 'b563622dd5a266e6a022036c867c746bef712c2b06fb6f73402af43548fe94ac'}], 'scrubber': [], 'layer': ['vessel']}, {'call_sign': 'D5TY5', 'dead_weight': 281395, 'gross_tonnage': 149724, 'id': '49878118cd36ca23cbba37edf7813288074756ac9cee30570a171471635114f4', 'imo': 9197868, 'mmsi': 636019316, 'name': 'SHINYO OCEAN', 'to_bow': 279, 'to_port': 51, 'to_starboard': 25, 'to_stern': 35, 'related_names': ['SHINYO OCEAN'], 'current_product_type': [{'cargo_movement_id': 'ff45015a3294e8187c5010b86bf335d4ff45015a3294e8187c5010b86bf335d4', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}, {'cargo_movement_id': '050c619a504327a4c8e1bd75b5048386050c619a504327a4c8e1bd75b5048386', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}, {'cargo_movement_id': 'aac541a3e9125aab5eca9d3f3524fc32aac541a3e9125aab5eca9d3f3524fc32', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}, {'cargo_movement_id': 'c868085c536bc65eb835bc90a643ebadc868085c536bc65eb835bc90a643ebad', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}, {'cargo_movement_id': '2dd6ba4a5e4027ff96c55181197a191a2dd6ba4a5e4027ff96c55181197a191a', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}, {'cargo_movement_id': 'dd183e2fd8899c79351bacc40b92ed01dd183e2fd8899c79351bacc40b92ed01', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}, {'cargo_movement_id': '249cc984f58292c111f5001d0a5372a7249cc984f58292c111f5001d0a5372a7', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}, {'cargo_movement_id': 'b74056f5c95f9e0fd842e24b2439a3a8b74056f5c95f9e0fd842e24b2439a3a8', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}], 'year': 2001, 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}], 'ref_type': 'vessel', 'vessel_status': 'vessel_status_ballast', 'corporate_entities': [{'id': '1c83153dfaab974f9919144483cfc9719e07fef8a4de602e40292e9ae99bc5cf', 'label': 'VL8 Pool', 'layer': 'commercial_owner', 'source': 'external', 'probability': 1}], 'leaf': True, 'vessel_class': 'vlcc_plus', 'cubic_capacity': 321888, 'tags': [{'tag': 'vessel_decommissioned_tag', 'start_timestamp': '2019-06-04T00:00:00+0000'}], 'flag': [{'tag': 'vessel_flag_tag', 'flag': 'LR', 'flag_country': '76044b057b5a5157476aff1aa4d2a6a7f5d0464cb5f5e6264ed6e3f9f27b01e3'}], 'scrubber': [], 'layer': ['vessel']}, {'call_sign': 'VROZ7', 'dead_weight': 299170, 'gross_tonnage': 156930, 'id': '8c7b33549ef4ceed125d53168b63e9d94eee5368b09f5e2644e15f2a9b557c11', 'imo': 9284960, 'mmsi': 477178100, 'name': 'OCEAN LILY', 'to_bow': 278, 'to_port': 52, 'to_starboard': 22, 'to_stern': 38, 'related_names': ['OCEAN LILY'], 'current_product_type': [{'cargo_movement_id': 'ac39b960bf44778dea8122a203daae10ac39b960bf44778dea8122a203daae10', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': True}, {'cargo_movement_id': '555f042e066a2d5594a1bb0b47623fb8555f042e066a2d5594a1bb0b47623fb8', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': True}, {'cargo_movement_id': '00aece37caa307d39b5cf1b49b0a400d00aece37caa307d39b5cf1b49b0a400d', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': True}, {'cargo_movement_id': 'daaedecaabe8f3f8e471da54c9113f53daaedecaabe8f3f8e471da54c9113f53', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': True}], 'year': 2004, 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}], 'ref_type': 'vessel', 'vessel_status': 'vessel_status_laden_known', 'corporate_entities': [{'id': '9ac2ab2b07e53a9b83e2368371d78c3041aa5d197e105a5396b27717629bcfc9', 'label': 'DAY HARVEST', 'layer': 'charterer', 'source': 'external', 'probability': 1}, {'id': '9cc2c2bd3dd7dd76abc9c2f444f9f9982f35f1a351d7063b1b10d96b5b5ad930', 'label': 'SINOCHEM', 'layer': 'commercial_owner', 'source': 'external', 'probability': 1}], 'leaf': True, 'vessel_class': 'vlcc_plus', 'cubic_capacity': 333416, 'tags': [], 'flag': [{'tag': 'vessel_flag_tag', 'flag': 'HK', 'flag_country': 'cc888be9693ccc01e6794e503bab3f12a4b0f85918ef15c853e63d25571bcfe5'}], 'scrubber': [], 'layer': ['vessel']}, {'call_sign': '7JQP', 'dead_weight': 312181, 'gross_tonnage': 159579, 'id': '6909805307b3bc561bbb9b5014c322b28265878443952e8aa6a5521a34147c72', 'imo': 9662875, 'mmsi': 432986000, 'name': 'ENEOS OCEAN', 'to_bow': 278, 'to_port': 57, 'to_starboard': 25, 'to_stern': 35, 'related_names': ['ENEOS OCEAN'], 'current_product_type': [{'cargo_movement_id': '5d1f020783fd9784d59d7e36603653775d1f020783fd9784d59d7e3660365377', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': True}, {'cargo_movement_id': '2ad2c52928dc916f55230268bc201f452ad2c52928dc916f55230268bc201f45', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': True}], 'year': 2014, 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}], 'ref_type': 'vessel', 'vessel_status': 'vessel_status_laden_known', 'corporate_entities': [{'id': '0185b6ffaf27c680fe3554dce5ba6b743ab349b4186093254d3bf41d12cd592a', 'label': 'JX OCEAN', 'layer': 'commercial_owner', 'source': 'external', 'probability': 1}], 'leaf': True, 'vessel_class': 'vlcc_plus', 'cubic_capacity': 320000, 'tags': [], 'flag': [{'tag': 'vessel_flag_tag', 'flag': 'JP', 'flag_country': '50182d9d05051a6c8d24f0514d4ee828da6eaa29eacbb11cfe368f51526328ce'}], 'scrubber': [{'tag': 'vessel_scrubber_tag', 'scrubber': '478fca39000c49d6', 'planned': False}], 'layer': ['vessel']}, {'call_sign': '3FSM8', 'dead_weight': 298732, 'gross_tonnage': 156805, 'id': '5ddaebd16e8998829f9116cfc2d5d4b3983eece99bfccba6924a86f481de64f4', 'imo': 9079107, 'mmsi': 370497000, 'name': 'NASHA', 'to_bow': 283, 'to_port': 49, 'to_starboard': 28, 'to_stern': 30, 'related_names': ['OCEANIC'], 'current_product_type': [{'cargo_movement_id': 'dc1c3e884cbe6a020cbc71197f767c70dc1c3e884cbe6a020cbc71197f767c70', 'product_type': [{'id': '5de0b00094e0fd7542c10f9f8a71b4008d55750f21dc905cda9b0f7f5f76bc08', 'layer': 'group', 'label': 'Dirty Petroleum Products'}, {'id': '1c107b4317bc2c85fb6c13cd7b28e8e0a02ec7fecc68afc2b68ca0545c835e1c', 'layer': 'group_product', 'label': 'Fuel Oil'}], 'active': False}, {'cargo_movement_id': 'b98dbc44bb5958aabbeecfc2c923dde0b98dbc44bb5958aabbeecfc2c923dde0', 'product_type': [{'id': '5de0b00094e0fd7542c10f9f8a71b4008d55750f21dc905cda9b0f7f5f76bc08', 'layer': 'group', 'label': 'Dirty Petroleum Products'}, {'id': '1c107b4317bc2c85fb6c13cd7b28e8e0a02ec7fecc68afc2b68ca0545c835e1c', 'layer': 'group_product', 'label': 'Fuel Oil'}], 'active': False}, {'cargo_movement_id': '3b7a5bf3279dfee627b87ae0b1dac0233b7a5bf3279dfee627b87ae0b1dac023', 'product_type': [{'id': '5de0b00094e0fd7542c10f9f8a71b4008d55750f21dc905cda9b0f7f5f76bc08', 'layer': 'group', 'label': 'Dirty Petroleum Products'}, {'id': '1c107b4317bc2c85fb6c13cd7b28e8e0a02ec7fecc68afc2b68ca0545c835e1c', 'layer': 'group_product', 'label': 'Fuel Oil'}], 'active': False}], 'year': 1996, 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}], 'ref_type': 'vessel', 'vessel_status': 'vessel_status_ballast', 'corporate_entities': [{'id': 'e35daeb0661afb54a35da1054075cc153bda97e727fba112eb394ca253576b2a', 'label': 'NITC', 'layer': 'commercial_owner', 'source': 'external', 'probability': 1}], 'leaf': True, 'vessel_class': 'vlcc_plus', 'cubic_capacity': 331295, 'tags': [{'tag': 'vessel_decommissioned_tag', 'start_timestamp': '2018-12-30T12:59:54+0000'}], 'flag': [{'tag': 'vessel_flag_tag', 'flag': 'PA', 'flag_country': 'f3058bcbb026a6921bf142f93dbd9e186043df9ee300407a01b35a2d2f588580'}], 'scrubber': [], 'layer': ['vessel']}, {'call_sign': 'EPJB9', 'dead_weight': 299990, 'gross_tonnage': 149383, 'id': 'c64b56b3c2ff3af6103b3156e04edbb72199b4618a20a298b53bc6ff59f435fd', 'imo': 9180281, 'mmsi': 422204700, 'name': 'HUMANITY', 'to_bow': 271, 'to_port': 51, 'to_starboard': 25, 'to_stern': 35, 'related_names': ['OCEAN NYMPH'], 'current_product_type': [{'cargo_movement_id': '0bb3d88d1c169d567245f6d676e55abd0bb3d88d1c169d567245f6d676e55abd', 'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11', 'layer': 'group', 'label': 'Crude/Condensates'}, {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653', 'layer': 'group_product', 'label': 'Crude'}], 'active': False}], 'year': 2000, 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}], 'ref_type': 'vessel', 'vessel_status': 'vessel_status_ballast', 'corporate_entities': [{'id': 'e35daeb0661afb54a35da1054075cc153bda97e727fba112eb394ca253576b2a', 'label': 'NITC', 'layer': 'commercial_owner', 'source': 'external', 'probability': 1}], 'leaf': True, 'vessel_class': 'vlcc_plus', 'cubic_capacity': 321928, 'tags': [], 'flag': [{'tag': 'vessel_flag_tag', 'flag': 'IR', 'flag_country': 'd308ddc557e774187ad6c7da81b39db990def9a39e6c88e79cb163b6bdd6e8e5'}], 'scrubber': [], 'layer': ['vessel']}]\n"
     ]
    }
   ],
   "source": [
    "import vortexasdk as v\n",
    "query = v.Vessels().search(vessel_classes='vlcc', term='ocean')\n",
    "\n",
    "print(query)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The data returned by the query is not interperatable in this format. We can think of it as a list of items, which each correspond to an item (in this case a vessel) matching the search query. We can see how many matching items were found:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(query)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So there are 8 matching vessels. The data makes a little more sense if we look at just one of these:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'call_sign': 'SVBC9',\n",
       " 'dead_weight': 299999,\n",
       " 'gross_tonnage': 161273,\n",
       " 'id': '508bc4b650b1eb69c0054c6bc3b3f40996c032f74e0fca06e344cec0f6bf8922',\n",
       " 'imo': 9532757,\n",
       " 'mmsi': 241089000,\n",
       " 'name': 'OCEANIS',\n",
       " 'to_bow': 278,\n",
       " 'to_port': 52,\n",
       " 'to_starboard': 27,\n",
       " 'to_stern': 33,\n",
       " 'related_names': ['OCEANIS'],\n",
       " 'current_product_type': [{'cargo_movement_id': '881caebc9311dd066c59927a123f6dc0881caebc9311dd066c59927a123f6dc0',\n",
       "   'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11',\n",
       "     'layer': 'group',\n",
       "     'label': 'Crude/Condensates'},\n",
       "    {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653',\n",
       "     'layer': 'group_product',\n",
       "     'label': 'Crude'}],\n",
       "   'active': False},\n",
       "  {'cargo_movement_id': '3488985d684cf1f28e1b2b8dd6589efc3488985d684cf1f28e1b2b8dd6589efc',\n",
       "   'product_type': [{'id': '54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11',\n",
       "     'layer': 'group',\n",
       "     'label': 'Crude/Condensates'},\n",
       "    {'id': '6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653',\n",
       "     'layer': 'group_product',\n",
       "     'label': 'Crude'}],\n",
       "   'active': False}],\n",
       " 'year': 2011,\n",
       " 'parent': [{'name': 'VLCC+', 'layer': ['vessel_class'], 'id': 'vlcc_plus'}],\n",
       " 'ref_type': 'vessel',\n",
       " 'vessel_status': 'vessel_status_ballast',\n",
       " 'corporate_entities': [{'id': 'b429e8a788a7322474da2f79676b7a4329e801b6ba2810056656d144905323a9',\n",
       "   'label': 'KOCH',\n",
       "   'layer': 'commercial_owner',\n",
       "   'source': 'external',\n",
       "   'probability': 1}],\n",
       " 'leaf': True,\n",
       " 'vessel_class': 'vlcc_plus',\n",
       " 'cubic_capacity': 345374,\n",
       " 'tags': [],\n",
       " 'flag': [{'tag': 'vessel_flag_tag',\n",
       "   'flag': 'GR',\n",
       "   'flag_country': 'b6be463f6999751d74c53b68865247ce565e003583579498f2537892bc13c69a'}],\n",
       " 'scrubber': [{'tag': 'vessel_scrubber_tag',\n",
       "   'scrubber': '478fca39000c49d6',\n",
       "   'planned': False}],\n",
       " 'layer': ['vessel']}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There's a lot of information here! Looking at the keys in this dictionary structure, we can see basic information about the vessel, along with the cargo that it is currently carrying. \n",
    "\n",
    "We can use a list comprehension to get the values of a particular key for each vessel in the returned data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['OCEANIS',\n",
       " 'AEGEAN',\n",
       " 'OCEANIA',\n",
       " 'SHINYO OCEAN',\n",
       " 'OCEAN LILY',\n",
       " 'ENEOS OCEAN',\n",
       " 'NASHA',\n",
       " 'HUMANITY']"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[vessel['name'] for vessel in query]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The query has a function `.to_df` which will convert the data into a pandas DataFrame structure. By default, it will only include some of the more important bits of information. We can also specifically list which colulmns we would like:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "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>name</th>\n",
       "      <th>imo</th>\n",
       "      <th>mmsi</th>\n",
       "      <th>related_names</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>OCEANIS</td>\n",
       "      <td>9532757</td>\n",
       "      <td>241089000</td>\n",
       "      <td>[OCEANIS]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>AEGEAN</td>\n",
       "      <td>9732553</td>\n",
       "      <td>205761000</td>\n",
       "      <td>[GENER8 OCEANUS]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>OCEANIA</td>\n",
       "      <td>9246633</td>\n",
       "      <td>205753000</td>\n",
       "      <td>[OCEANIA, TI OCEANIA]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>SHINYO OCEAN</td>\n",
       "      <td>9197868</td>\n",
       "      <td>636019316</td>\n",
       "      <td>[SHINYO OCEAN]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>OCEAN LILY</td>\n",
       "      <td>9284960</td>\n",
       "      <td>477178100</td>\n",
       "      <td>[OCEAN LILY]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>ENEOS OCEAN</td>\n",
       "      <td>9662875</td>\n",
       "      <td>432986000</td>\n",
       "      <td>[ENEOS OCEAN]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>NASHA</td>\n",
       "      <td>9079107</td>\n",
       "      <td>370497000</td>\n",
       "      <td>[OCEANIC]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>HUMANITY</td>\n",
       "      <td>9180281</td>\n",
       "      <td>422204700</td>\n",
       "      <td>[OCEAN NYMPH]</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "           name      imo       mmsi          related_names\n",
       "0       OCEANIS  9532757  241089000              [OCEANIS]\n",
       "1        AEGEAN  9732553  205761000       [GENER8 OCEANUS]\n",
       "2       OCEANIA  9246633  205753000  [OCEANIA, TI OCEANIA]\n",
       "3  SHINYO OCEAN  9197868  636019316         [SHINYO OCEAN]\n",
       "4    OCEAN LILY  9284960  477178100           [OCEAN LILY]\n",
       "5   ENEOS OCEAN  9662875  432986000          [ENEOS OCEAN]\n",
       "6         NASHA  9079107  370497000              [OCEANIC]\n",
       "7      HUMANITY  9180281  422204700          [OCEAN NYMPH]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query.to_df(columns=['name', 'imo', 'mmsi', 'related_names'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the Geographies endpoint, do a search for the term 'portsmouth'. How many matching queries are there? Where are they located?\n",
    "\n",
    "Note the Geographies endpoint documentation can be [found here](https://vortechsa.github.io/python-sdk/endpoints/geographies/)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}