sec-cik-mapper is a Python package for obtaining mappings between stock and mutual fund identifier data provided by the SEC.
- Up-to-date mappings from the SEC provided as native Python dictionaries
- Mappings for both stocks and mutual funds
- Mapping data exposed as a raw pandas dataframe for custom data processing and usage
- Support for Python 3.6+
- Full support for PEP 484-style type hints and the mypy type checker
- Auto-generated mappings, updated daily, available from GitHub for use outside of Python
Mappings can be formed between the following SEC identifiers and company metadata:
Stocks
- CIK
- Ticker
- Exchange
- Company Name
Mutual Funds
- CIK
- Ticker
- Series ID
- Class ID
Install and update this package using pip:
$ pip install -U sec-cik-mapper
Stocks
>>> from sec_cik_mapper import StockMapper
>>> from pathlib import Path
# Initialize a stock mapper instance
>>> mapper = StockMapper()
# Get mapping from CIK to tickers
>>> cik_to_tickers = mapper.cik_to_tickers
{'0000320193': {'AAPL'}, '0000789019': {'MSFT'}, '0001652044': {'GOOG', 'GOOGL'}, ...}
# Get mapping from ticker to CIK
>>> ticker_to_cik = mapper.ticker_to_cik
{'AAPL': '0000320193', 'MSFT': '0000789019', 'GOOG': '0001652044', ...}
# Get mapping from CIK to company name
>>> cik_to_company_name = mapper.cik_to_company_name
{'0000320193': 'Apple Inc.', '0000789019': 'Microsoft Corp', '0001652044': 'Alphabet Inc.', ...}
# Get mapping from ticker to company name
>>> ticker_to_company_name = mapper.ticker_to_company_name
{'AAPL': 'Apple Inc.', 'MSFT': 'Microsoft Corp', 'GOOG': 'Alphabet Inc.', ...}
# Get mapping from ticker to exchange
>>> ticker_to_exchange = mapper.ticker_to_exchange
{'AAPL': 'Nasdaq', 'MSFT': 'Nasdaq', 'GOOG': 'Nasdaq', ...}
# Get mapping from exchange to tickers
>>> exchange_to_tickers = mapper.exchange_to_tickers
{'Nasdaq': {'CYRN', 'OHPAW', 'SANW', ...}, 'NYSE': {'PLAG', 'TDW-WTB', 'RS', ...}, 'OTC': {'ZICX', 'LTGJ', 'AVNI', ...}, ...}
# Get mapping from CIK to exchange
>>> cik_to_exchange = mapper.cik_to_exchange
{'0000320193': 'Nasdaq', '0000789019': 'Nasdaq', '0001652044': 'Nasdaq', ...}
# Get mapping from exchange to CIKs
>>> exchange_to_ciks = mapper.exchange_to_ciks
{'Nasdaq': {'0000779544', '0001508171', '0001060955', ...}, 'NYSE': {'0000764478', '0000008818', '0001725057', ...}, 'OTC': {'0001044676', '0001592411', '0001284452', ...}, ...}
# Save CIK, ticker, exchange, and company name mappings to a CSV file
>>> csv_path = Path("example_mappings.csv")
>>> mapper.save_metadata_to_csv(csv_path)
# Get raw pandas dataframe
>>> mapper.raw_dataframe
CIK Ticker Name Exchange
0 0000320193 AAPL Apple Inc. Nasdaq
1 0000789019 MSFT Microsoft Corp Nasdaq
2 0001652044 GOOG Alphabet Inc. Nasdaq
3 0001018724 AMZN Amazon Com Inc Nasdaq
4 0001318605 TSLA Tesla, Inc. Nasdaq
... ... ... ... ...
13184 0001866816 OLITU Omnilit Acquisition Corp. Nasdaq
13185 0001870778 OHAAU Opy Acquisition Corp. I Nasdaq
13186 0001873324 PEPLW Pepperlime Health Acquisition Corp Nasdaq
13187 0001877557 WEL-UN Integrated Wellness Acquisition Corp NYSE
13188 0001877787 ZGN-WT Ermenegildo Zegna Holditalia S.P.A. NYSE
[13189 rows x 4 columns]
Mutual Funds
>>> from sec_cik_mapper import MutualFundMapper
>>> from pathlib import Path
# Initialize a mutual fund mapper instance
>>> mapper = MutualFundMapper()
# Get mapping from CIK to tickers
>>> cik_to_tickers = mapper.cik_to_tickers
{'0000002110': {'CRBYX', 'CEFZX', 'CSSRX', ...}, '0000002646': {'IIBPX', 'IPISX', 'IIBTX', ...}, '0000002663': {'IMSXX', 'VMTXX', 'IVMXX', ...}}
# Get mapping from ticker to CIK
>>> ticker_to_cik = mapper.ticker_to_cik
{'LACAX': '0000002110', 'LIACX': '0000002110', 'ACRNX': '0000002110', ...}
# Get mapping from CIK to series ID
>>> cik_to_series_ids = mapper.cik_to_series_ids
{'0000002110': {'S000009184', 'S000033622', 'S000009185', ...}, '0000002646': {'S000008760'}, '0000002663': {'S000008702'}, ...}
# Get mapping from ticker to series ID
>>> ticker_to_series_id = mapper.ticker_to_series_id
{'LACAX': 'S000009184', 'LIACX': 'S000009184', 'ACRNX': 'S000009184', ...}
# Get mapping from series ID to CIK
>>> series_id_to_cik = mapper.series_id_to_cik
{'S000009184': '0000002110', 'S000009185': '0000002110', 'S000009186': '0000002110', ...}
# Get mapping from series ID to tickers
>>> series_id_to_tickers = mapper.series_id_to_tickers
{'S000009184': {'CEARX', 'CRBYX', 'ACRNX', ...}, 'S000009185': {'ACINX', 'CACRX', 'CAIRX', ...}, 'S000009186': {'LAUCX', 'LAUAX', 'CUSAX', ...}, ...}
# Get mapping from series ID to class IDs
>>> series_id_to_class_ids = mapper.series_id_to_class_ids
{'S000009184': {'C000024956', 'C000122737', 'C000024957', ...}, 'S000009185': {'C000024958', 'C000122739', 'C000097733', ...}, 'S000009186': {'C000024962', 'C000024964', 'C000122740', ...}, ...}
# Get mapping from ticker to class ID
>>> ticker_to_class_id = mapper.ticker_to_class_id
{'LACAX': 'C000024954', 'LIACX': 'C000024956', 'ACRNX': 'C000024957', ...}
# Get mapping from CIK to class IDs
>>> cik_to_class_ids = mapper.cik_to_class_ids
{'0000002110': {'C000024958', 'C000024969', 'C000024957', ...}, '0000002646': {'C000023849', 'C000074893', 'C000028785', ...}, '0000002663': {'C000023718', 'C000028786', 'C000076529', ...}, ...}
# Get mapping from class ID to CIK
>>> class_id_to_cik = mapper.class_id_to_cik
{'C000024954': '0000002110', 'C000024956': '0000002110', 'C000024957': '0000002110', ...}
# Get mapping from class ID to ticker
>>> class_id_to_ticker = mapper.class_id_to_ticker
{'C000024954': 'LACAX', 'C000024956': 'LIACX', 'C000024957': 'ACRNX', ...}
# Save CIK, ticker, series ID, and class ID mappings to a CSV file
>>> csv_path = Path("mutual_fund_mappings.csv")
>>> mapper.save_metadata_to_csv(csv_path)
# Get raw pandas dataframe
>>> mapper.raw_dataframe
CIK Ticker Series ID Class ID
0 0000002110 LACAX S000009184 C000024954
1 0000002110 LIACX S000009184 C000024956
2 0000002110 ACRNX S000009184 C000024957
3 0000002110 CEARX S000009184 C000122735
4 0000002110 CRBRX S000009184 C000122736
... ... ... ... ...
29237 0001860434 SIHY S000072555 C000228888
29238 0001860434 SIFI S000072556 C000228889
29239 0001860434 INNO S000073580 C000230585
29240 0001877493 BTF S000074058 C000231452
29241 0001877493 VBB S000075054 C000233857
[29242 rows x 4 columns]
Auto-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, which fetches, transforms, validates, and uploads the latest mapping data from the SEC to GitHub (save location: github.com/jadchaar/sec-cik-mapper/auto_generated_mappings). These mappings are available for download and usage from both GitHub and the jsDelivr CDN.
Example curl commands, which download the specified mapping files and saves them to the current working directory:
GitHub
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/mappings.csv -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/cik_to_exchange.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/cik_to_tickers.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/ticker_to_exchange.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/cik_to_company_name.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/ticker_to_cik.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/ticker_to_company_name.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/exchange_to_tickers.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/stocks/exchange_to_ciks.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/ticker_to_class_id.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/series_id_to_class_ids.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/mappings.csv -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/cik_to_class_ids.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/cik_to_series_ids.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/series_id_to_cik.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/ticker_to_series_id.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/cik_to_tickers.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/class_id_to_cik.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/series_id_to_tickers.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/class_id_to_ticker.json -O
$ curl https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings/mutual_funds/ticker_to_cik.json -O
jsDelivr CDN
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/mappings.csv -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/cik_to_exchange.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/cik_to_tickers.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/ticker_to_exchange.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/cik_to_company_name.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/ticker_to_cik.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/ticker_to_company_name.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/exchange_to_tickers.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/stocks/exchange_to_ciks.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/ticker_to_class_id.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/series_id_to_class_ids.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/mappings.csv -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/cik_to_class_ids.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/cik_to_series_ids.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/series_id_to_cik.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/ticker_to_series_id.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/cik_to_tickers.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/class_id_to_cik.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/series_id_to_tickers.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/class_id_to_ticker.json -O
$ curl https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings/mutual_funds/ticker_to_cik.json -O
If you encounter a bug or would like to see a new company filing or feature added to sec-cik-mapper, please file an issue or submit a pull request.
For full documentation, please visit sec-cik-mapper.readthedocs.io.