{"id":16909856,"url":"https://github.com/jadchaar/sec-cik-mapper","last_synced_at":"2025-04-13T05:13:38.614Z","repository":{"id":41132999,"uuid":"437380811","full_name":"jadchaar/sec-cik-mapper","owner":"jadchaar","description":"🗺 Generate mappings between SEC identifiers using Python","archived":false,"fork":false,"pushed_at":"2025-02-28T08:13:43.000Z","size":42156,"stargazers_count":67,"open_issues_count":1,"forks_count":14,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T05:13:31.676Z","etag":null,"topics":["cik","edgar","etfs","finance","financial-data","funds","markets","mutual-funds","python","sec-edgar","stock-market","stocks","trading"],"latest_commit_sha":null,"homepage":"https://sec-cik-mapper.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jadchaar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-11T20:21:34.000Z","updated_at":"2025-04-12T07:55:42.000Z","dependencies_parsed_at":"2023-12-09T09:24:33.831Z","dependency_job_id":"ead3343d-c55a-4dc3-ac4a-541e4d252031","html_url":"https://github.com/jadchaar/sec-cik-mapper","commit_stats":null,"previous_names":["jadchaar/cik-mapper"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jadchaar%2Fsec-cik-mapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jadchaar%2Fsec-cik-mapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jadchaar%2Fsec-cik-mapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jadchaar%2Fsec-cik-mapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jadchaar","download_url":"https://codeload.github.com/jadchaar/sec-cik-mapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665746,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cik","edgar","etfs","finance","financial-data","funds","markets","mutual-funds","python","sec-edgar","stock-market","stocks","trading"],"created_at":"2024-10-13T18:58:04.618Z","updated_at":"2025-04-13T05:13:38.588Z","avatar_url":"https://github.com/jadchaar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sec-cik-mapper\n\n[![Tests](https://github.com/jadchaar/sec-cik-mapper/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/jadchaar/sec-cik-mapper/actions/workflows/continuous_integration.yml)\n[![Update Mappings Daily CRON Job](https://github.com/jadchaar/cik-mapper/actions/workflows/update_mappings_daily_cron_job.yml/badge.svg?event=schedule)](https://github.com/jadchaar/sec-cik-mapper/actions/workflows/update_mappings_daily_cron_job.yml)\n[![Documentation Status](https://readthedocs.org/projects/sec-cik-mapper/badge/?version=latest)](https://sec-cik-mapper.readthedocs.io/en/latest/?badge=latest)\n[![Coverage](https://codecov.io/gh/jadchaar/sec-cik-mapper/branch/main/graph/badge.svg)](https://pypi.org/project/sec-cik-mapper/)\n\n[![PyPI Version](https://img.shields.io/pypi/v/sec-cik-mapper.svg)](https://pypi.org/project/sec-cik-mapper/)\n[![Supported Python Versions](https://img.shields.io/pypi/pyversions/sec-cik-mapper.svg)](https://pypi.org/project/sec-cik-mapper/)\n[![License](https://img.shields.io/pypi/l/sec-cik-mapper.svg)](https://pypi.org/project/sec-cik-mapper/)\n[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)\n\n**sec-cik-mapper** is a Python package for generating mappings between stock and mutual fund identifier data provided by the SEC.\n\n## Features\n\n- Generate up-to-date mappings from the SEC as native Python dictionaries\n- Mappings for both stocks and mutual funds\n- Mapping data exposed as a raw pandas dataframe for custom data processing and usage\n- Full support for PEP 484-style type hints and the [mypy type checker](https://mypy.readthedocs.io/en/stable/)\n- [Pre-generated mappings](https://github.com/jadchaar/sec-cik-mapper/tree/main/mappings), updated daily, available from GitHub and jsDelivr for use outside of Python\n- Support for Python 3.6+\n\n## Quick Start\n\n### Installation\n\nInstall and update this package using [pip](https://pip.pypa.io/en/stable/getting-started/):\n\n```console\n$ pip install -U sec-cik-mapper\n```\n\n### Basic Usage\n\n#### Stocks\n\n```python\n\u003e\u003e\u003e from sec_cik_mapper import StockMapper\n\u003e\u003e\u003e from pathlib import Path\n\n# Initialize a stock mapper instance\n\u003e\u003e\u003e mapper = StockMapper()\n\n# Get mapping from CIK to tickers\n\u003e\u003e\u003e mapper.cik_to_tickers\n{'0000320193': {'AAPL'}, '0000789019': {'MSFT'}, '0001652044': {'GOOG', 'GOOGL'}, ...}\n\n# Get mapping from ticker to CIK\n\u003e\u003e\u003e mapper.ticker_to_cik\n{'AAPL': '0000320193', 'MSFT': '0000789019', 'GOOG': '0001652044', ...}\n\n# Get mapping from CIK to company name\n\u003e\u003e\u003e mapper.cik_to_company_name\n{'0000320193': 'Apple Inc.', '0000789019': 'Microsoft Corp', '0001652044': 'Alphabet Inc.', ...}\n\n# Get mapping from ticker to company name\n\u003e\u003e\u003e mapper.ticker_to_company_name\n{'AAPL': 'Apple Inc.', 'MSFT': 'Microsoft Corp', 'GOOG': 'Alphabet Inc.', ...}\n\n# Get mapping from ticker to exchange\n\u003e\u003e\u003e mapper.ticker_to_exchange\n{'AAPL': 'Nasdaq', 'MSFT': 'Nasdaq', 'GOOG': 'Nasdaq', ...}\n\n# Get mapping from exchange to tickers\n\u003e\u003e\u003e mapper.exchange_to_tickers\n{'Nasdaq': {'CYRN', 'OHPAW', 'SANW', ...}, 'NYSE': {'PLAG', 'TDW-WTB', 'RS', ...}, 'OTC': {'ZICX', 'LTGJ', 'AVNI', ...}, ...}\n\n# Get mapping from CIK to exchange\n\u003e\u003e\u003e mapper.cik_to_exchange\n{'0000320193': 'Nasdaq', '0000789019': 'Nasdaq', '0001652044': 'Nasdaq', ...}\n\n# Get mapping from exchange to CIKs\n\u003e\u003e\u003e mapper.exchange_to_ciks\n{'Nasdaq': {'0000779544', '0001508171', '0001060955', ...}, 'NYSE': {'0000764478', '0000008818', '0001725057', ...}, 'OTC': {'0001044676', '0001592411', '0001284452', ...}, ...}\n\n# Save CIK, ticker, exchange, and company name mappings to a CSV file\n\u003e\u003e\u003e csv_path = Path(\"example_mappings.csv\")\n\u003e\u003e\u003e mapper.save_metadata_to_csv(csv_path)\n\n# Get raw pandas dataframe\n\u003e\u003e\u003e mapper.raw_dataframe\n              CIK Ticker                               Name Exchange\n0      0000001750    AIR                           Aar Corp     NYSE\n1      0000001800    ABT                Abbott Laboratories     NYSE\n2      0000001961   WDDD                         Worlds Inc      OTC\n3      0000002098    ACU                   Acme United Corp     NYSE\n4      0000002178     AE     Adams Resources \u0026 Energy, Inc.     NYSE\n...           ...    ...                                ...      ...\n13167  0001894057   PPYA  Papaya Growth Opportunity Corp. I\n13168  0001894370   HMAC   Hainan Manaslu Acquisition Corp.\n13169  0001894630   GHIX            Gores Holdings Ix, Inc.\n13170  0001897941   GTEN             Gores Holdings X, Inc.\n13171  0001898416   ALVO       Alvotech Lux Holdings S.A.S.\n\n[13172 rows x 4 columns]\n```\n\n#### Mutual Funds\n\n```python\n\u003e\u003e\u003e from sec_cik_mapper import MutualFundMapper\n\u003e\u003e\u003e from pathlib import Path\n\n# Initialize a mutual fund mapper instance\n\u003e\u003e\u003e mapper = MutualFundMapper()\n\n# Get mapping from CIK to tickers\n\u003e\u003e\u003e mapper.cik_to_tickers\n{'0000002110': {'CRBYX', 'CEFZX', 'CSSRX', ...}, '0000002646': {'IIBPX', 'IPISX', 'IIBTX', ...}, '0000002663': {'IMSXX', 'VMTXX', 'IVMXX', ...}, ...}\n\n# Get mapping from ticker to CIK\n\u003e\u003e\u003e mapper.ticker_to_cik\n{'LACAX': '0000002110', 'LIACX': '0000002110', 'ACRNX': '0000002110', ...}\n\n# Get mapping from CIK to series ID\n\u003e\u003e\u003e mapper.cik_to_series_ids\n{'0000002110': {'S000009184', 'S000033622', 'S000009185', ...}, '0000002646': {'S000008760'}, '0000002663': {'S000008702'}, ...}\n\n# Get mapping from ticker to series ID\n\u003e\u003e\u003e mapper.ticker_to_series_id\n{'LACAX': 'S000009184', 'LIACX': 'S000009184', 'ACRNX': 'S000009184', ...}\n\n# Get mapping from series ID to CIK\n\u003e\u003e\u003e mapper.series_id_to_cik\n{'S000009184': '0000002110', 'S000009185': '0000002110', 'S000009186': '0000002110', ...}\n\n# Get mapping from series ID to tickers\n\u003e\u003e\u003e mapper.series_id_to_tickers\n{'S000009184': {'CEARX', 'CRBYX', 'ACRNX', ...}, 'S000009185': {'ACINX', 'CACRX', 'CAIRX', ...}, 'S000009186': {'LAUCX', 'LAUAX', 'CUSAX', ...}, ...}\n\n# Get mapping from series ID to class IDs\n\u003e\u003e\u003e mapper.series_id_to_class_ids\n{'S000009184': {'C000024956', 'C000122737', 'C000024957', ...}, 'S000009185': {'C000024958', 'C000122739', 'C000097733', ...}, 'S000009186': {'C000024962', 'C000024964', 'C000122740', ...}, ...}\n\n# Get mapping from ticker to class ID\n\u003e\u003e\u003e mapper.ticker_to_class_id\n{'LACAX': 'C000024954', 'LIACX': 'C000024956', 'ACRNX': 'C000024957', ...}\n\n# Get mapping from CIK to class IDs\n\u003e\u003e\u003e mapper.cik_to_class_ids\n{'0000002110': {'C000024958', 'C000024969', 'C000024957', ...}, '0000002646': {'C000023849', 'C000074893', 'C000028785', ...}, '0000002663': {'C000023718', 'C000028786', 'C000076529', ...}, ...}\n\n# Get mapping from class ID to CIK\n\u003e\u003e\u003e mapper.class_id_to_cik\n{'C000024954': '0000002110', 'C000024956': '0000002110', 'C000024957': '0000002110', ...}\n\n# Get mapping from class ID to ticker\n\u003e\u003e\u003e mapper.class_id_to_ticker\n{'C000024954': 'LACAX', 'C000024956': 'LIACX', 'C000024957': 'ACRNX', ...}\n\n# Save CIK, ticker, series ID, and class ID mappings to a CSV file\n\u003e\u003e\u003e csv_path = Path(\"mutual_fund_mappings.csv\")\n\u003e\u003e\u003e mapper.save_metadata_to_csv(csv_path)\n\n# Get raw pandas dataframe\n\u003e\u003e\u003e mapper.raw_dataframe\n              CIK Ticker   Series ID    Class ID\n0      0000002110  ACFFX  S000009188  C000024973\n1      0000002110  ACINX  S000009185  C000024961\n2      0000002110  ACRNX  S000009184  C000024957\n3      0000002110  ACTWX  S000009187  C000024969\n4      0000002110  AUSAX  S000009186  C000024965\n...           ...    ...         ...         ...\n29236  0001860434   INNO  S000073580  C000230585\n29237  0001860434   SIFI  S000072556  C000228889\n29238  0001860434   SIHY  S000072555  C000228888\n29239  0001877493    BTF  S000074058  C000231452\n29240  0001877493    VBB  S000075054  C000233857\n\n[29241 rows x 4 columns]\n```\n\n## Supported Mappings\n\nMappings can be formed between the following SEC identifiers and metadata:\n\n|     Key     |       Value       | `StockMapper` | `MutualFundMapper` |\n| :---------: | :---------------: | :-----------: | :----------------: |\n|    `CIK`    |  `Set(Tickers)`   |       ✅       |         ✅          |\n|    `CIK`    |  `Company Name`   |       ✅       |                    |\n|    `CIK`    |    `Exchange`     |       ✅       |                    |\n| `Exchange`  |    `Set(CIKs)`    |       ✅       |                    |\n| `Exchange`  |  `Set(Tickers)`   |       ✅       |                    |\n|  `Ticker`   |       `CIK`       |       ✅       |         ✅          |\n|  `Ticker`   |  `Company Name`   |       ✅       |                    |\n|  `Ticker`   |    `Exchange`     |       ✅       |                    |\n|    `CIK`    | `Set(Series IDs)` |               |         ✅          |\n|    `CIK`    | `Set(Class IDs)`  |               |         ✅          |\n| `Class ID`  |       `CIK`       |               |         ✅          |\n| `Class ID`  |     `Ticker`      |               |         ✅          |\n| `Series ID` |       `CIK`       |               |         ✅          |\n| `Series ID` | `Set(Class IDs)`  |               |         ✅          |\n| `Series ID` |  `Set(Tickers)`   |               |         ✅          |\n|  `Ticker`   |    `Class ID`     |               |         ✅          |\n|  `Ticker`   |    `Series ID`    |               |         ✅          |\n\n## Pre-generated Mappings\n\nPre-generated mappings are also available for download and use outside of Python (e.g. manually or via automated scripts/curl requests). These mappings are updated daily via a [fully automated daily CRON job](https://github.com/jadchaar/sec-cik-mapper/actions/workflows/update_mappings_daily_cron_job.yml), which fetches, transforms, validates, and uploads the latest mapping data from the SEC to GitHub (save location: [sec-cik-mapper/mappings · GitHub](https://github.com/jadchaar/sec-cik-mapper/tree/main/mappings)). These mappings are available for download and usage from both GitHub and the [jsDelivr CDN](https://www.jsdelivr.com).\n\n### Example Usage\n\nExample [curl](https://curl.se/) commands, which download the specified mapping files and saves them to the current working directory:\n\n#### Stocks\n\nHosted via GitHub:\n\n```console\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/mappings.csv -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/cik_to_exchange.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/cik_to_tickers.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/ticker_to_exchange.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/cik_to_company_name.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/ticker_to_cik.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/ticker_to_company_name.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/exchange_to_tickers.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/stocks/exchange_to_ciks.json -O\n```\n\nHosted via jsDelivr CDN:\n\n```console\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/mappings.csv -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/cik_to_exchange.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/cik_to_tickers.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/ticker_to_exchange.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/cik_to_company_name.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/ticker_to_cik.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/ticker_to_company_name.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/exchange_to_tickers.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/stocks/exchange_to_ciks.json -O\n```\n\n#### Mutual Funds\n\nHosted via GitHub:\n\n```console\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/ticker_to_class_id.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/series_id_to_class_ids.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/mappings.csv -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/cik_to_class_ids.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/cik_to_series_ids.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/series_id_to_cik.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/ticker_to_series_id.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/cik_to_tickers.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/class_id_to_cik.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/series_id_to_tickers.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/class_id_to_ticker.json -O\n$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/mappings/mutual_funds/ticker_to_cik.json -O\n```\n\nHosted via jsDelivr CDN:\n\n```console\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/ticker_to_class_id.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/series_id_to_class_ids.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/mappings.csv -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/cik_to_class_ids.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/cik_to_series_ids.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/series_id_to_cik.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/ticker_to_series_id.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/cik_to_tickers.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/class_id_to_cik.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/series_id_to_tickers.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/class_id_to_ticker.json -O\n$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/mappings/mutual_funds/ticker_to_cik.json -O\n```\n\n### Contributing\n\nIf you encounter a bug or would like to see a new company filing or feature added to **sec-cik-mapper**, please [file an issue](https://github.com/jadchaar/sec-cik-mapper/issues) or [submit a pull request](https://help.github.com/en/articles/creating-a-pull-request).\n\n### Documentation\n\nFor full documentation, please visit [sec-cik-mapper.readthedocs.io](https://sec-cik-mapper.readthedocs.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjadchaar%2Fsec-cik-mapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjadchaar%2Fsec-cik-mapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjadchaar%2Fsec-cik-mapper/lists"}