Skip to main content

Map Tickers to SecId: API Reference Data Guide

Because tickers can change over time due to corporate events, you should rely on algoseek's unique SecId for historical accuracy. This tutorial shows how to query the Lookup File, along with other critical reference datasets.

Identifier Lookups​

Endpoint: GET /v1/data/us-equity-ref/lookup-files

What it does: Provides an efficient way to identify the corresponding SecId based on a ticker-date pair, supporting accurate identifier normalization across time.

Request Example (Fetching a limited list of SecIds with specific columns):

curl --get \
     'https://api.algoseek.com/v1/data/us-equity-ref/lookup-files' \
     --data-urlencode 'columns=Ticker,EndDate,SecId' \
     --data-urlencode 'limit=5' \
     -H "X-API-KEY: YOUR_API_KEY"

Response Example:

{
    "data": [
        {
            "Ticker": "SLF",
            "EndDate": "2099-12-31",
            "SecId": 2234
        },
        {
            "Ticker": "ASTSF",
            "EndDate": "2008-05-30",
            "SecId": 9470
        },
        {
            "Ticker": "PGLA",
            "EndDate": "2010-07-01",
            "SecId": 10729
        },
        {
            "Ticker": "CTTY",
            "EndDate": "2007-08-24",
            "SecId": 11019
        },
        {
            "Ticker": "SFM",
            "EndDate": "2008-05-22",
            "SecId": 11895
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 5,
        "next_offset": 5
    }
}

Endpont: GET /v1/data/us-equity-ref/secid-chains-lookup

What it does: Provides the mapping between ASID (a persistent security identifier) and SecId, along with ticker symbols and their effective date ranges. It enables continuous tracking of the same security across ticker, name, and internal identifier changes throughout its lifecycle.

Request Example (Fetching a limited list of ASID with specific columns):

curl --get \
     'https://api.algoseek.com/v1/data/us-equity-ref/secid-chains-lookup' \
     --data-urlencode 'columns=Ticker,EndDate,ASID' \
     --data-urlencode 'limit=5' \
     -H "X-API-KEY: YOUR_API_KEY"

Response Example:

{
  "data": [
    {
      "Ticker": "A",
      "EndDate": "2149-06-06",
      "ASID": 1010000000001000
    },
    {
      "Ticker": "AAA",
      "EndDate": "2007-05-21",
      "ASID": 1010000000001002
    },
    {
      "Ticker": "YHOO",
      "EndDate": "2017-06-16",
      "ASID": 1010000000001006
    },
    {
      "Ticker": "AACC",
      "EndDate": "2013-06-13",
      "ASID": 1010000000001009
    },
    {
      "Ticker": "AAI",
      "EndDate": "2011-05-02",
      "ASID": 1010000000001016
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 5,
    "next_offset": 5
  }
}

Security Master File​

Endpoint: GET /v1/data/us-equity-ref/sec-master

What it does: Provides a comprehensive, centralized reference record for all listed and delisted U.S. equity securities from 2007 to the present. It serves as the authoritative foundation for security identification, classification, and lifecycle tracking.

Request Example:

curl --get \
     'https://api.algoseek.com/v1/data/us-equity-ref/sec-master' \
     --data-urlencode 'columns=SecId,Ticker,Name,PrimaryExchange,Industry' \
     --data-urlencode 'limit=1' \
     -H "X-API-KEY: YOUR_API_KEY"

Response Example:

{
    "data": [
        {
            "SecId": 2234,
            "Ticker": [
                "SLF"
            ],
            "Name": [
                "Sun Life Financial, Inc."
            ],
            "PrimaryExchange": [
                "NYSE"
            ],
            "Industry": "Life Insurance"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 1,
        "next_offset": 1
    }
}

Corporate Action Data​

Corporate action data alters historical price and volume. Similar to Reference Data, the path ends at the dataset name, and you apply advanced query parameters (such as EffectiveDate or Ticker) to retrieve the adjustment factors.

Endpoint: GET /v1/data/us-equity-ref/adj-factors-basic

What it does: Provides basic adjustment factors that affect price, volume, or both for corporate events (e.g., dividends, splits) that impact historical equity time series.

Example Request:

curl --get \
     'https://api.algoseek.com/v1/data/us-equity-ref/adj-factors-basic' \
     --data-urlencode 'Ticker=WFC' \
     --data-urlencode 'EffectiveDate.gt=2023-01-01' \
     --data-urlencode 'limit=2' \
     -H "X-API-KEY: YOUR_API_KEY"

Example Output:

{
    "data": [
        {
            "ASID": 1010000000019026,
            "Ticker": "WFC",
            "EffectiveDate": "2023-02-02",
            "AdjustmentFactor": 0.993661525459539,
            "AdjustmentReason": "CashDiv",
            "EventId": "2849820"
        },
        {
            "ASID": 1010000000019026,
            "Ticker": "WFC",
            "EffectiveDate": "2023-05-04",
            "AdjustmentFactor": 0.992238033635188,
            "AdjustmentReason": "CashDiv",
            "EventId": "2957451"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 2,
        "next_offset": 2
    }
}

Fundamentals: Shares Outstanding​

Endpoint: GET /v1/data/us-equity-ref/shares-outst-basic

What it does: Delivers a structured historical record of share count changes over time, supporting accurate valuation, market capitalization analysis, and regulatory calculations.

Example Request:

curl --get \
     'https://api.algoseek.com/v1/data/us-equity-ref/shares-outst-basic' \
     --data-urlencode 'Ticker=CLNE' \
     --data-urlencode 'limit=1' \
     -H "X-API-KEY: YOUR_API_KEY"

Example Output:

{
    "data": [
        {
            "SecId": 589463,
            "Ticker": "CLNE",
            "ASID": 1010000000004317,
            "CreatedDate": "2007-05-28",
            "ChangedDate": "2007-05-28",
            "Revision": 0,
            "EffectiveDate": "2007-05-25",
            "SharesOutstanding": 44449555
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 1,
        "next_offset": 1
    }
}

Market Events: Trading Halts​

Endpoint: GET /v1/data/us-equity-ref/trading-halts

What it does: Provides comprehensive reference information on trading halt events affecting U.S. exchange-listed equities, including reason codes, initiation timestamps, and resumption timestamps.

Example Request:

curl --get \
     'https://api.algoseek.com/v1/data/us-equity-ref/trading-halts' \
     --data-urlencode 'Symbol=BOWN' \
     --data-urlencode 'limit=1' \
     -H "X-API-KEY: YOUR_API_KEY"

Example Output:

{
    "data": [
        {
            "Date": "2025-01-13",
            "SecId": 8139569,
            "ASID": 1010000000025154,
            "Symbol": "BOWN",
            "OrigExch": "Nasdaq",
            "Plan": "UTP",
            "EodStatus": "Trading",
            "HaltDate": "2025-01-13",
            "HaltTimeExch": "14:10:39.301068469",
            "HaltTimeSip": "14:10:39.301126956",
            "CtaLastPricePreHalt": null,
            "ResumeDate": "2025-01-13",
            "UtpQuoteResumeTimeExch": "",
            "UtpQuoteResumeTimeSip": "",
            "TradeResumeTimeExch": "14:15:39.301275468",
            "TradeResumeTimeSip": "14:15:39.301367249",
            "AsNormRsnCode": "V",
            "AsNormRsn": "Volatility Pause",
            "ExchRsnCode": "LUDP",
            "HaltCaseSeq": 1,
            "TotalMessages": 2
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 1,
        "next_offset": 1
    }
}