# Generated by tools/build_contracts.py from tools/algoseek_catalog.py -- do not edit by hand. # Open Data Contract Standard v3.2.0 (https://bitol-io.github.io/open-data-contract-standard/). apiVersion: v3.2.0 kind: DataContract id: urn:alphaswarm:datacontract:algoseek:us-equities-security-master-file name: AlgoSeek US Equities Security Master File version: 0.1.0 status: draft domain: market-data tags: - algoseek - licensed-data - equity - reference - us description: purpose: One row per algoseek SecId covering every listed and delisted US equity-type security since 2007, with each SecId's history of tickers, names, ISINs, US identifiers, primary exchanges and FIGIs packed into semicolon-delimited lists, plus current classification fields. Acts as the identifier crosswalk for the rest of the equity data. usage: Point-in-time security identity, corporate-action adjustment, and universe construction for US equities. limitations: 'Vendor-curated reference data: rows can be restated when AlgoSeek learns of a late or corrected event, so land each delivery as a snapshot rather than overwriting history. Identifier hierarchy: SecId is algoseek''s own key - stable across ticker/name changes but it can change after a restructuring such as a reclassification; ASID (see US Equities ASID Lookup) is the higher-level key that chains SecIds for one security''s economic life. Ticker is not a key: the same ticker can belong to different SecIds in different periods (guide example: S for Sprint Nextel, later Sprint), and ticker changes keep the SecId. Resolve Ticker+date to SecId through the Lookup File, not from this table alone. Cross-reference columns: ISIN (12-char, list), USIdentifier (9-char CUSIP-style, list), FIGI (12-char, list), SEDOL (deprecated, current only). SecId->ISIN/US identifier/FIGI is one-to-many over time; ISIN and USIdentifier carry their own date lists, FIGI does not. FIGI choice: algoseek uses the Primary Exchange Composite FIGI when available, otherwise the plain FIGI; some entries are blank when no FIGI matches a period. Guide best practice: use the LAST FIGI listed as the reference id.' authoritativeDefinitions: - type: businessDefinition url: https://algoseek.com/dataset/us-equities-security-master-file/ - type: implementation url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.Security.Master.File.pdf - type: implementation url: https://algoseek.com/docs/rest-api/reference context: instructions: Rows are effective-dated. Answer point-in-time questions with the row in force on the as-of date, never the latest row. SecId and ASID are both durable AlgoSeek security keys but different values (the ASID lookup links them); tickers are reused across companies, so resolve a ticker to a key with a trade date. constraints: - id: c1 constraint: 'Licensed vendor data: never export raw rows to a tenant-local destination or include them verbatim in a public artifact; serve only through entitlement-checked platform reads.' - id: c3 constraint: Do not treat the vendor's `Ticker` as a stable identity across time; join on an AlgoSeek security key (SecId or ASID, which are distinct) or the platform symbol mapping. servers: - server: algoseek-s3 type: s3 environment: vendor description: AlgoSeek flat-file delivery (the layout the schema below describes). location: s3://${ALGOSEEK_S3_BUCKET_EQ_SEC_MASTER}/ format: csv encoding: UTF-8 customProperties: - property: layout value: Single CSV file (guide names it equity_security_master.csv; published sample is eq_sec_master.csv), header row first, one row per security record. Delivered as one consolidated table. - property: compression value: gzip - property: header value: true - property: entitlement value: Bucket access is granted per subscription; bucket names arrive with license provisioning. - server: algoseek-rest-api type: api environment: vendor description: AlgoSeek Datasets REST API (X-API-KEY header; JSON, CSV or gzipped CSV). Returns AlgoSeek's normalized API layout, which differs from the flat-file columns in this contract's schema. location: https://api.algoseek.com/v1/data/us-equity-ref/sec-master customProperties: - property: auth value: X-API-KEY header issued by AlgoSeek - property: columnsEndpoint value: https://api.algoseek.com/v1/meta/datasets/{dataset_id}/columns - property: statusEndpoint value: https://api.algoseek.com/v1/meta/datasets/{dataset_id}/status - property: responseFormats value: - json - csv - csv_gzip - property: pagination value: offset + limit; tick endpoints take trade_date and identifier (Ticker or ASID) in the path schema: - name: us_equities_security_master_file physicalName: eq_sec_master physicalType: file logicalType: object businessName: US Equities Security Master File description: One row per algoseek SecId covering every listed and delisted US equity-type security since 2007, with each SecId's history of tickers, names, ISINs, US identifiers, primary exchanges and FIGIs packed into semicolon-delimited lists, plus current classification fields. Acts as the identifier crosswalk for the rest of the equity data. dataGranularityDescription: one SecId (one row per security record; historical attribute values packed into semicolon-delimited lists with parallel date-range lists) properties: - name: SecId logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: algoseek unique security identifier; stays the same through ticker and name changes. One row per SecId. primaryKey: true primaryKeyPosition: 1 required: true customProperties: - property: nullMeaning value: Never - property: evidence value: guide+sample - name: Tickers logicalType: string logicalTypeOptions: format: semicolon-delimited list, oldest first physicalType: string (ticker1;ticker2;...) (csv text) description: Every ticker symbol the SecId has used, in chronological order; entries align by position with TickersStartToEndDate. required: true customProperties: - property: nullMeaning value: Never - property: evidence value: guide+sample - name: TickersStartToEndDate logicalType: string logicalTypeOptions: format: yyyymmdd:yyyymmdd;yyyymmdd:yyyymmdd;... (29991231 = open-ended) physicalType: string (yyyymmdd:yyyymmdd;...) (csv text) description: Start:end date of each ticker in Tickers; end date 29991231 while the ticker is still in use. required: true customProperties: - property: nullMeaning value: Never - property: evidence value: guide+sample - name: Name logicalType: string logicalTypeOptions: format: semicolon-delimited list, oldest first physicalType: string (name1;name2;...) (csv text) description: Every security name used, chronological; positions align with NameStartToEndDate. Apostrophes appear as backticks in the sample. required: true customProperties: - property: nullMeaning value: Never - property: evidence value: guide+sample - name: NameStartToEndDate logicalType: string logicalTypeOptions: format: yyyymmdd:yyyymmdd;yyyymmdd:yyyymmdd;... (29991231 = open-ended) physicalType: string (yyyymmdd:yyyymmdd;...) (csv text) description: Start:end date of each name in Name; 29991231 = name still in use. required: true customProperties: - property: nullMeaning value: Never - property: evidence value: guide+sample - name: ISIN logicalType: string logicalTypeOptions: format: semicolon-delimited list of 12-char ISINs physicalType: string (ISIN1;ISIN2;...) (csv text) description: Every ISIN the SecId has carried, chronological; positions align with ISINStartToEndDate. customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: ISINStartToEndDate logicalType: string logicalTypeOptions: format: yyyymmdd:yyyymmdd;yyyymmdd:yyyymmdd;... (29991231 = open-ended) physicalType: string (yyyymmdd:yyyymmdd;...) (csv text) description: Start:end date of each ISIN; 29991231 = ISIN still in use. customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: ListStatus logicalType: string logicalTypeOptions: format: 1-char code physicalType: string (csv text) description: 'Current listing status only (not historical): A announced, D delisted, L listed.' required: true enum: - value: A label: Announced - value: D label: Delisted - value: L label: Listed customProperties: - property: nullMeaning value: Never - property: evidence value: guide+sample - name: SecurityDescription logicalType: string physicalType: string (csv text) description: Current security type, one of the 13 values in the guide's security-type table. enum: - value: Equity Shares label: Common stock - value: Structured Product label: Pre-packaged investment, normally assets linked to interest plus one or more derivatives - value: Bond label: Fixed-income instrument representing a loan from an investor to a borrower - value: Exchange Traded Fund label: Collection of securities that often tracks an underlying index - value: Depository Receipts label: Negotiable certificates issued by a bank representing shares in a foreign company traded locally - value: Preference Share label: Shares whose dividends are paid before common-stock dividends - value: Units label: Securities representing a collection of different (usually related) shares - value: Warrants label: Right to purchase a company's stock at a specific price and date - value: Preferred Security label: 'Same as Preference Share (guide: ''See Preference Share'')' - value: Tradeable Rights label: Invitation to existing shareholders to purchase additional new shares - value: Stapled Security label: Two or more securities contractually bound into a single unit that cannot be traded separately - value: Contingent Value Rights label: Security giving holders certain benefits if a specific event occurs, usually within a set time frame - value: When Issued label: Conditional transaction in a security that has been authorized but not yet issued customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: USIdentifier logicalType: string logicalTypeOptions: format: semicolon-delimited list of US identifiers (9-char CUSIP-style codes); treat as text physicalType: string (id1;id2;...) (csv text) description: Every US securities identifier the SecId has used, chronological; aligns with USIdentifierStartToEndDate. Sample drops leading zeros and has two corrupted values. customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: USIdentifierStartToEndDate logicalType: string logicalTypeOptions: format: yyyymmdd:yyyymmdd;yyyymmdd:yyyymmdd;... (29991231 = open-ended) physicalType: string (yyyymmdd:yyyymmdd;...) (csv text) description: Start:end date of each USIdentifier; 29991231 = still in use. customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: PrimaryExchange logicalType: string logicalTypeOptions: format: semicolon-delimited list of exchange names physicalType: string (exchange1;exchange2;...) (csv text) description: 'Every primary listing exchange the SecId has had, chronological; aligns with PrimaryExchangeStartToEndDate. Values seen: NASDAQ, NYSE, AMEX (guide example also ARCA).' customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: PrimaryExchangeStartToEndDate logicalType: string logicalTypeOptions: format: yyyymmdd:yyyymmdd;yyyymmdd:yyyymmdd;... (29991231 = open-ended) physicalType: string (yyyymmdd:yyyymmdd;...) (csv text) description: Start:end date of each primary exchange; 29991231 = still current. customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: SEDOL logicalType: string logicalTypeOptions: format: 7-char code physicalType: string (csv text) description: Current-value SEDOL; deprecated and no longer updated, so only historical values are populated (blank in 40 of 100 sample rows, all delisted). customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: Sic logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: Current Standard Industrial Classification code (single value, not historical). customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: Sector logicalType: string physicalType: string (csv text) description: Current SIC-based sector label (one of nine listed in the guide). enum: - value: Finance Insurance And Real Estate label: SIC sector label - value: Services label: SIC sector label - value: Retail Trade label: SIC sector label - value: Manufacturing label: SIC sector label - value: Transportation Communications Electric Gas And Sanitary Service label: SIC sector label - value: Wholesale Trade label: SIC sector label - value: Construction label: SIC sector label - value: Mining label: SIC sector label - value: Agriculture Forestry And Fishing label: SIC sector label customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: Industry logicalType: string physicalType: string (csv text) description: Current SIC industry description (single value, not historical); free text such as 'Electronic Computers'. customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample - name: FIGI logicalType: string logicalTypeOptions: format: semicolon-delimited list of 12-char FIGIs; empty slots appear as ';;' or leading/trailing ';' physicalType: string (FIGI1;FIGI2;...) (csv text) description: 'Financial Instrument Global Identifier(s): Primary Exchange Composite FIGI when available. Several entries when the security changed; last entry is the recommended reference.' customProperties: - property: nullMeaning value: Blank - property: evidence value: guide+sample quality: - id: row_count_positive metric: rowCount mustBeGreaterThan: 0 dimension: completeness severity: error description: Every delivered partition (trade date, or snapshot) carries at least one row. - id: primary_key_unique metric: duplicateValues mustBe: 0 arguments: properties: - SecId dimension: uniqueness severity: error description: The declared primary key is unique within each delivered partition (one file or table snapshot). support: - channel: algoseek-support tool: email url: mailto:support@algoseek.com scope: issues description: Vendor support for data defects, missing days, and entitlement problems. team: name: AlphaSwarm data engineering slaProperties: - id: history_start property: generalAvailability value: '2007-01-01' description: First trade date of the vendor history. - id: update_frequency property: frequency value: 1 unit: d driver: analytics - id: retention property: retention value: license-term description: Retention of landed copies is bounded by the AlgoSeek license; purge on termination. driver: regulatory customProperties: - property: vendor value: AlgoSeek - property: vendorDataGroup value: us-equity-ref - property: vendorDatasetTextId value: eq_sec_master - property: vendorSampleUrl value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_sec_master.csv - property: assetClass value: equity - property: venues value: - NASDAQ - NYSE - AMEX - ARCA - property: coverage value: All listed and delisted US equity securities (stocks, ETFs, ETNs, ADRs, warrants, preferred stock and similar) from 2007 to present. Page says it is a single consolidated table updated daily for new listings, delistings and reference-data changes. A separate Lookup File dataset resolves ticker/FIGI/ASID to SecId. - property: timezone value: America/New_York - property: timestampFormat value: yyyymmdd date strings; periods written yyyymmdd:yyyymmdd, joined by ';'; end date 29991231 = open-ended - property: priceAdjustment value: n/a - property: licensedData value: true - property: evidenceGrade value: vendor-doc - property: knownIssues value: - Primary key is inferred; AlgoSeek's guide does not name one. - 'Doc discrepancy: Sic: guide types it integer (Table 2 shows e.g. 3350, 3571) but every sample row serializes it as float-style text (''3571.0'', ''5812.0'').' - 'Doc discrepancy: USIdentifier: guide Table 1 shows AAPL as 037833100 (9 chars); sample/JSON delivers 37833100 - leading zeros stripped when the code looks numeric (of 129 sample entries, 79 are 9 chars incl. the 2 corrupted ones below, 48 are 8 chars, 2 are 7 chars).' - 'Doc discrepancy: USIdentifier for SecId 33551 and 33619 is spreadsheet-corrupted in both sample CSV and JSON preview (''4,27E+110'' and ''4,62E+211'', i.e. scientific-notation mangling of 04269E107 and 04622E208); do not treat as valid codes.' - 'Doc discrepancy: Guide never names the ''USIdentifier'' type; values and the ISIN embedding (US ISIN = ''US'' + 9-char code + check digit) match CUSIP format, so CUSIP is inferred, not documented. The word CUSIP does not appear in the guide.' - 'Doc discrepancy: Guide describes FIGI as a list with no StartToEndDate column; in all 100 sample rows the FIGI entry count equals the ISIN and USIdentifier entry counts, so FIGI appears positionally aligned to ISIN/USIdentifier periods (inferred, not stated).' - 'Doc discrepancy: Guide says the file is named equity_security_master.csv; published sample file is eq_sec_master.csv (naming of the sample differs from the delivered file name).' contractCreatedTs: '2026-11-02T00:00:00Z'