Add Notebook (#29)

* Add colab notebook
* Bump version

notebook/Bellingcat_EDGAR_Tool.ipynb

@@ -0,0 +1,122 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "iCBS4YMpURiq"
+      },
+      "source": [
+        "# Bellingcat EDGAR Search Tool 🔎🏦\n",
+        "\n",
+        "<a href=\"https://www.bellingcat.com\"><img alt=\"Bellingcat logo: Discover Bellingcat\" src=\"https://img.shields.io/badge/Discover%20Bellingcat-%20?style=for-the-badge&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAA4AAAAYCAYAAADKx8xXAAABhGlDQ1BJQ0MgcHJvZmlsZQAAKJF9kT1Iw0AcxV9TS0UqDnZQEcxQneyiIo6likWwUNoKrTqYXPoFTRqSFBdHwbXg4Mdi1cHFWVcHV0EQ%2FABxdnBSdJES%2F5cUWsR4cNyPd%2Fced%2B8AoVllqtkTA1TNMtKJuJjLr4rBVwQwhhBEDEvM1JOZxSw8x9c9fHy9i%2FIs73N%2Fjn6lYDLAJxLHmG5YxBvEs5uWznmfOMzKkkJ8Tjxp0AWJH7kuu%2FzGueSwwDPDRjY9TxwmFktdLHcxKxsq8QxxRFE1yhdyLiuctzir1Tpr35O%2FMFTQVjJcpzmKBJaQRIo6klFHBVVYiNKqkWIiTftxD%2F%2BI40%2BRSyZXBYwcC6hBheT4wf%2Fgd7dmcXrKTQrFgcCLbX%2BMA8FdoNWw7e9j226dAP5n4Err%2BGtNYO6T9EZHixwBA9vAxXVHk%2FeAyx1g6EmXDMmR%2FDSFYhF4P6NvygODt0Dfmttbex%2BnD0CWulq%2BAQ4OgYkSZa97vLu3u7d%2Fz7T7%2BwHEU3LHAa%2FQ6gAAAAZiS0dEAAAAAAAA%2BUO7fwAAAAlwSFlzAAAuIwAALiMBeKU%2FdgAAAAd0SU1FB%2BgFHwwiMH4odB4AAAAZdEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIEdJTVBXgQ4XAAAA50lEQVQ4y82SvWpCQRCFz25ERSJiCNqlUiS1b5AuEEiZIq1NOsGXCKms0wXSp9T6dskDiFikyiPc%2FrMZyf3FXSGQ0%2BzuzPl2ZoeVKgQ0gQ2wBVpVHlcDkjM5V%2FJ5nag6sJ%2FZX%2Bh%2FC7gEhqeAFKf7p1M9aB3b5oN1OomB7g1axUBPBr3GQHODHmOgqUF3MZAzKI2d4LWBV4H%2BMXDuJd1a7Cew1k7SwksaHC4LqNaw7aeX9GWHXkC1G1sTAS17Y3Kk2lnp4wNLiz0DrgLq8qt2MfmSSabAO%2FBBXp26dtrADPjOmN%2BAUdG7B3cE61l5hOZiAAAAAElFTkSuQmCC&logoColor=%23fff&color=%23000\"></a><!--\n",
+        "--><a href=\"https://discord.gg/bellingcat\"><img alt=\"Discord logo: Join our community\" src=\"https://img.shields.io/badge/Join%20our%20community-%20?style=for-the-badge&logo=discord&logoColor=%23fff&color=%235865F2\"></a><!--\n",
+        "--><a href=\"https://github.com/bellingcat/EDGAR\"><img alt=\"Github logo: Explore the code\" src=\"https://img.shields.io/badge/Explore%20the%20code-%20?style=for-the-badge&logo=github&color=%2329903b\"></a>\n",
+        "\n",
+        "A tool to search the US Securities and Exchange Commission EDGAR database of corporate filings and download the results as a spreadsheet.\n",
+        "\n",
+        "The corporate filings held within the EDGAR database contain a wealth of quantitative and qualitative information on every legal entity that issues non-exempt securities in the United States.\n",
+        "\n",
+        "This search tool was initially developed as part of the Bellingcat Tech Fellowship program, we hope it helps you utilise this incredible, free resource.\n",
+        "\n",
+        "> <font color='#ffc107'>⚠️Warning:</font> Using both `search_keywords` and only `company_cik` at the same time might not work correctly, we recommend avoiding using both in a search (you can leave `search_keywords` blank and only specify `company_cik`)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "g8OW2QMw9qll"
+      },
+      "outputs": [],
+      "source": [
+        "# @title Search EDGAR { display-mode: \"form\" }\n",
+        "\n",
+        "# @markdown ### ⬅️ Click to search the EDGAR filings with the below parameters\n",
+        "\n",
+        "search_keywords = \"Volcano Safety\" # @param {type:\"string\"}\n",
+        "start_date = '2024-01-01' # @param {type:\"date\"}\n",
+        "end_date = '2024-12-31' # @param {type:\"date\"}\n",
+        "\n",
+        "filing_type = \"all\" # @param [\"all\", \"all_except_section_16\", \"all_annual_quarterly_and_current_reports\", \"all_section_16\", \"beneficial_ownership_reports\", \"exempt_offerings\", \"registration_statements\", \"filing_review_correspondence\", \"sec_orders_and_notices\", \"proxy_materials\", \"tender_offers_and_going_private_tx\", \"trust_indentures\"]\n",
+        "company_cik = \"\" # @param {type:\"string\"}\n",
+        "\n",
+        "filter_by_location = \"\" # @param [\"\",\"Incorporated in\", \"Principal executive offices in\"]\n",
+        "location = \"\" # @param [\"\",\"Alabama\", \"Alaska\", \"Arizona\", \"Arkansas\", \"California\", \"Colorado\", \"Connecticut\", \"Delaware\", \"District of Columbia\", \"Florida\", \"Georgia\", \"Hawaii\", \"Idaho\", \"Illinois\", \"Indiana\", \"Iowa\", \"Kansas\", \"Kentucky\", \"Louisiana\", \"Maine\", \"Maryland\", \"Massachusetts\", \"Michigan\", \"Minnesota\", \"Mississippi\", \"Missouri\", \"Montana\", \"Nebraska\", \"Nevada\", \"New Hampshire\", \"New Jersey\", \"New Mexico\", \"New York\", \"North Carolina\", \"North Dakota\", \"Ohio\", \"Oklahoma\", \"Oregon\", \"Pennsylvania\", \"Rhode Island\", \"South Carolina\", \"South Dakota\", \"Tennessee\", \"Texas\", \"United States\", \"Utah\", \"Vermont\", \"Virginia\", \"Washington\", \"West Virginia\", \"Wisconsin\", \"Wyoming\", \"Alberta, Canada\", \"British Columbia, Canada\", \"Canada (Federal Level)\", \"Manitoba, Canada\", \"New Brunswick, Canada\", \"Newfoundland, Canada\", \"Nova Scotia, Canada\", \"Ontario, Canada\", \"Prince Edward Island, Canada\", \"Quebec, Canada\", \"Saskatchewan, Canada\", \"Yukon, Canada\", \"Afghanistan\", \"Aland Islands\", \"Albania\", \"Algeria\", \"American Samoa\", \"Andorra\", \"Angola\", \"Anguilla\", \"Antarctica\", \"Antigua and Barbuda\", \"Argentina\", \"Armenia\", \"Aruba\", \"Australia\", \"Austria\", \"Azerbaijan\", \"Bahamas\", \"Bahrain\", \"Bangladesh\", \"Barbados\", \"Belarus\", \"Belgium\", \"Belize\", \"Benin\", \"Bermuda\", \"Bhutan\", \"Bolivia\", \"Bosnia and Herzegovina\", \"Botswana\", \"Bouvet Island\", \"Brazil\", \"British Indian Ocean Territory\", \"Brunei Darussalam\", \"Bulgaria\", \"Burkina Faso\", \"Burundi\", \"Cambodia\", \"Cameroon\", \"Cape Verde\", \"Cayman Islands\", \"Central African Republic\", \"Chad\", \"Chile\", \"China\", \"Christmas Island\", \"Cocos (Keeling) Islands\", \"Colombia\", \"Comoros\", \"Congo\", \"Congo, the Democratic Republic of the\", \"Cook Islands\", \"Costa Rica\", \"Cote D'ivoire \", \"Croatia\", \"Cuba\", \"Cyprus\", \"Czech Republic\", \"Denmark\", \"Djibouti\", \"Dominica\", \"Dominican Republic\", \"Ecuador\", \"Egypt\", \"El Salvador\", \"Equatorial Guinea\", \"Eritrea\", \"Estonia\", \"Ethiopia\", \"Falkland Islands (Malvinas)\", \"Faroe Islands\", \"Fiji\", \"Finland\", \"France\", \"French Guiana\", \"French Polynesia\", \"French Southern Territories\", \"Gabon\", \"Gambia\", \"Georgia (country)\", \"Germany\", \"Ghana\", \"Gibraltar\", \"Greece\", \"Greenland\", \"Grenada\", \"Guadeloupe\", \"Guam\", \"Guatemala\", \"Guernsey\", \"Guinea\", \"Guinea-bissau\", \"Guyana\", \"Haiti\", \"Heard Island and Mcdonald Islands\", \"Holy See (Vatican City State)\", \"Honduras\", \"Hong Kong\", \"Hungary\", \"Iceland\", \"India\", \"Indonesia\", \"Iran, Islamic Republic of\", \"Iraq\", \"Ireland\", \"Isle of Man\", \"Israel\", \"Italy\", \"Jamaica\", \"Japan\", \"Jersey\", \"Jordan\", \"Kazakhstan\", \"Kenya\", \"Kiribati\", \"Korea, Democratic People's Republic of \", \"Korea, Republic of\", \"Kuwait\", \"Kyrgyzstan\", \"Lao People's Democratic Republic \", \"Latvia\", \"Lebanon\", \"Lesotho\", \"Liberia\", \"Libyan Arab Jamahiriya\", \"Liechtenstein\", \"Lithuania\", \"Luxembourg\", \"Macau\", \"Macedonia, the Former Yugoslav Republic of\", \"Madagascar\", \"Malawi\", \"Malaysia\", \"Maldives\", \"Mali\", \"Malta\", \"Marshall Islands\", \"Martinique\", \"Mauritania\", \"Mauritius\", \"Mayotte\", \"Mexico\", \"Micronesia, Federated States of\", \"Moldova, Republic of\", \"Monaco\", \"Mongolia\", \"Montenegro\", \"Montserrat\", \"Morocco\", \"Mozambique\", \"Myanmar\", \"Namibia\", \"Nauru\", \"Nepal\", \"Netherlands\", \"Netherlands Antilles\", \"New Caledonia\", \"New Zealand\", \"Nicaragua\", \"Niger\", \"Nigeria\", \"Niue\", \"Norfolk Island\", \"Northern Mariana Islands\", \"Norway\", \"Oman\", \"Pakistan\", \"Palau\", \"Palestinian Territory, Occupied\", \"Panama\", \"Papua New Guinea\", \"Paraguay\", \"Peru\", \"Philippines\", \"Pitcairn\", \"Poland\", \"Portugal\", \"Puerto Rico\", \"Qatar\", \"Reunion\", \"Romania\", \"Russian Federation\", \"Rwanda\", \"Saint Barthelemy\", \"Saint Helena\", \"Saint Kitts and Nevis\", \"Saint Lucia\", \"Saint Martin\", \"Saint Pierre and Miquelon\", \"Saint Vincent and the Grenadines\", \"Samoa\", \"San Marino\", \"Sao Tome and Principe\", \"Saudi Arabia\", \"Senegal\", \"Serbia\", \"Seychelles\", \"Sierra Leone\", \"Singapore\", \"Slovakia\", \"Slovenia\", \"Solomon Islands\", \"Somalia\", \"South Africa\", \"South Georgia and the South Sandwich Islands\", \"Spain\", \"Sri Lanka\", \"Sudan\", \"Suriname\", \"Svalbard and Jan Mayen\", \"Swaziland\", \"Sweden\", \"Switzerland\", \"Syrian Arab Republic\", \"Taiwan, Province of China\", \"Tajikistan\", \"Tanzania, United Republic of\", \"Thailand\", \"Timor-leste\", \"Togo\", \"Tokelau\", \"Tonga\", \"Trinidad and Tobago\", \"Tunisia\", \"Turkey\", \"Turkmenistan\", \"Turks and Caicos Islands\", \"Tuvalu\", \"Uganda\", \"Ukraine\", \"United Arab Emirates\", \"United Kingdom\", \"United States Minor Outlying Islands\", \"Uruguay\", \"Uzbekistan\", \"Vanuatu\", \"Venezuela\", \"Viet Nam\", \"Virgin Islands, British\", \"Virgin Islands, U.s.\", \"Wallis and Futuna\", \"Western Sahara\", \"Yemen\", \"Zambia\", \"Zimbabwe\", \"Unknown\"]\n",
+        "\n",
+        "# Handle empty arguments\n",
+        "search_keywords = \"\\\"\\\"\" if search_keywords == \"\" else search_keywords\n",
+        "filing_type = None if filing_type == \"all\" else filing_type\n",
+        "company_cik = None if company_cik == \"\" else company_cik\n",
+        "\n",
+        "if filter_by_location == \"Incorporated in\":\n",
+        "  loc_filter = f\"--inc_in \\\"{location}\\\"\"\n",
+        "elif filter_by_location == \"Principal executive offices in\":\n",
+        "  loc_filter = f\"--peo_in \\\"{location}\\\"\"\n",
+        "else:\n",
+        "  loc_filter = \"\"\n",
+        "\n",
+        "# Load Python dependencies\n",
+        "import pandas as pd\n",
+        "from datetime import datetime\n",
+        "from google.colab import data_table, files\n",
+        "from ipywidgets import widgets\n",
+        "from IPython.display import display\n",
+        "from IPython import get_ipython\n",
+        "\n",
+        "data_table.enable_dataframe_formatter()\n",
+        "\n",
+        "# Create the output files\n",
+        "output = f\"edgar_search_results_{datetime.now().strftime('%d%m%Y_%H%M%S')}.csv\"\n",
+        "logfile = f\"./edgar_log_{datetime.now().strftime('%d%m%Y_%H%M%S')}.log\"\n",
+        "\n",
+        "# Enable Widgets\n",
+        "!jupyter nbextension enable --py widgetsnbextension >> {logfile} 2>&1\n",
+        "\n",
+        "# Install the EDGAR search tool on the first run\n",
+        "![ ! -f \"edgar_tool_installed\" ] && echo -n \"Loading the EDGAR Tool on first search...\" && pip install edgar-tool >> {logfile} 2>&1 && pip install pandas==1.5.3 >> {logfile} 2>&1 && touch edgar_tool_installed && echo \"Loaded.\"\n",
+        "\n",
+        "# Run the tool with the query\n",
+        "!echo -n \"Searching EDGAR...\"\n",
+        "!edgar-tool text_search {search_keywords} --start_date {start_date} --end_date {end_date} --filing_form {filing_type} --entity_id {company_cik} --output {output} --browser firefox --min-wait 0.5 --max-wait 1.5 {loc_filter} >> {logfile} 2>&1\n",
+        "exit_code = get_ipython().__dict__['user_ns']['_exit_code']\n",
+        "!echo \"Done.\"\n",
+        "\n",
+        "# Error handling\n",
+        "if exit_code == 2:\n",
+        "  print(\"\\x1b[33m No results were found for your query.\\x1b[0m\")\n",
+        "elif exit_code != 0:\n",
+        "  print(\"\\x1b[31m Something went wrong with the EDGAR tool, check your search and try again.\\x1b[0m\")\n",
+        "else:\n",
+        "  try:\n",
+        "    # Load results\n",
+        "    results = pd.read_csv(output)\n",
+        "\n",
+        "    # Show download button\n",
+        "    btn = widgets.Button(description='Download Results')\n",
+        "    btn.on_click(lambda x: files.download(output))\n",
+        "    display(btn)\n",
+        "\n",
+        "    # Display the results in a data table\n",
+        "    display(results)\n",
+        "  except FileNotFoundError as e:\n",
+        "    print(\"\\x1b[31m Something went wrong with the EDGAR tool, please get in touch at [email protected] and help us improve the tool for everyone. \\x1b[0m\")\n",
+        "\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.12.1"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "edgar-tool"
-version = "1.2.1"
+version = "1.3.0"
 description = "Search and retrieve corporate and financial data from the United States Securities and Exchange Commission (SEC)."
 authors = ["Bellingcat"]
 license = "GNU General Public License v3 (GPLv3)"