# 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-lookup-file name: AlgoSeek US Equities Lookup File version: 0.1.0 status: draft domain: market-data tags: - algoseek - licensed-data - equity - reference - us description: purpose: Date-ranged mapping from a ticker symbol (or, in a sibling file, a FIGI) to the algoseek SecId it identified during a start/end window. Used to resolve a ticker and trade date to SecId before joining to other algoseek datasets or to the Security Master. 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. To find the SecId for a ticker you need a trading date: a ticker can map to different SecIds over time (guide examples: AAC maps to three securities in 20070103-20100205, 20101213-20121015 and 20141002-20191025; S was Sprint Nextel and later Sprint). Resolve with StartDate <= date <= EndDate. Date-window semantics: dates are yyyymmdd; EndDate 29991231 means the ticker still maps to the SecId. In the sample, adjacent windows for one ticker are back-to-back (AA: 33008 to 20161031, 4920498 from 20161101) so EndDate acts as an inclusive last date; there are gaps (AAC 20100205 to 20101213) where the ticker was unassigned. In the 100-row sample, windows for the same ticker never overlap, so (Ticker, date) resolves to at most one SecId; (Ticker, StartDate) was unique, but the same Ticker+SecId pair can appear in two windows (AAUK / 75522 twice, with a gap), so the safer key includes SecId and StartDate. One security can span several SecIds (guide cites GOOG and GOOGL as a case where two or more SecIds must be linked); use the ASID Lookup dataset to chain SecIds into one continuous security history.' authoritativeDefinitions: - type: businessDefinition url: https://algoseek.com/dataset/us-equities-lookup-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_LOOKUP_FILES}/ format: csv encoding: UTF-8 customProperties: - property: layout value: 'Guide lists three lookup CSV files: ticker_to_secid_lookup.csv (Ticker, SecId, StartDate, EndDate), figi_to_secid_lookup.csv (FIGI, SecId, StartDate, EndDate) and equity_asid_lookup.csv (ASID lookup, separate dataset). Published sample eq_lookup_files.csv is the ticker file. One row per mapping window, header row first.' - 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/lookup-files 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_lookup_file physicalName: eq_lookup_files physicalType: file logicalType: object businessName: US Equities Lookup File description: Date-ranged mapping from a ticker symbol (or, in a sibling file, a FIGI) to the algoseek SecId it identified during a start/end window. Used to resolve a ticker and trade date to SecId before joining to other algoseek datasets or to the Security Master. dataGranularityDescription: one ticker x SecId x validity period (one row per contiguous StartDate-EndDate window in which the ticker mapped to that SecId) properties: - name: Ticker logicalType: string logicalTypeOptions: format: algoseek ticker symbol; may carry suffixes such as .U, .WS, .A, p, w (observed) physicalType: string (csv text) description: Ticker symbol that referred to this SecId during the StartDate-EndDate window. primaryKey: true primaryKeyPosition: 1 required: true customProperties: - property: evidence value: guide+sample - name: SecId logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: algoseek unique security identifier that the ticker pointed to during the window. primaryKey: true primaryKeyPosition: 2 required: true customProperties: - property: evidence value: guide+sample - name: StartDate logicalType: date logicalTypeOptions: format: yyyymmdd physicalType: string (yyyymmdd) (csv text) description: First date the ticker was used for this SecId. primaryKey: true primaryKeyPosition: 3 required: true customProperties: - property: evidence value: guide+sample - name: EndDate logicalType: date logicalTypeOptions: format: yyyymmdd; 29991231 = still in use physicalType: string (yyyymmdd) (csv text) description: Last date the ticker was used for this SecId; 29991231 while the ticker is still in use. customProperties: - property: evidence value: guide+sample - name: FIGI logicalType: string logicalTypeOptions: format: 12-char FIGI physicalType: string (csv text) description: 'GUIDE-ONLY, not in the ticker-file sample: key of the separate figi_to_secid_lookup.csv, which has FIGI, SecId, StartDate, EndDate (FIGI replaces Ticker).' customProperties: - property: evidence value: guide-only 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: - Ticker - SecId - StartDate dimension: uniqueness severity: error description: The declared primary key is unique within each delivered partition (one file or table snapshot). - id: StartDate_before_EndDate type: sql description: StartDate is on or before EndDate. query: SELECT COUNT(*) FROM {object} WHERE EndDate IS NOT NULL AND EndDate < StartDate mustBe: 0 dimension: consistency severity: error 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: 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_lookup_files - property: vendorSampleUrl value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_lookup_files.csv - property: assetClass value: equity - property: coverage value: 'US listed and delisted equity securities from 2007 to present (guide intro for the Security Master/Lookup set; lookup file sample starts 20070103). Page describes two versions: Ticker-to-SecId and FIGI-to-SecId.' - property: timezone value: America/New_York - property: timestampFormat value: yyyymmdd date strings; EndDate 29991231 = still in use - 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. - Update cadence and publication latency are not stated in the guide; confirm with AlgoSeek (or GET /v1/meta/datasets/{id}/status). - 'Doc discrepancy: Page and guide describe two lookup versions (Ticker-to-SecId, FIGI-to-SecId) but only the Ticker file has a published sample header; the FIGI file''s columns are known only from the guide (Tables 7-8), so FIGI is listed as a guide-only column of a different file, not of the ticker file.' - 'Doc discrepancy: Guide intro says algoseek ''provides three versions of lookup files'', counting the ASID lookup; the page and this dataset cover only ticker and FIGI mappings (ASID is its own dataset).' - 'Doc discrepancy: Guide gives no ''Missing'' column for the lookup files, so null/blank behaviour is unstated (sample has no blanks).' - 'Doc discrepancy: Guide states no update frequency for the lookup files (only the Security Master and ASID Lookup are stated as updated daily).' - 'Doc discrepancy: Sample is ordered by ticker in ASCII order (lowercase suffix tickers such as AAp, AApB, AAw sort after uppercase), not by date or SecId.' contractCreatedTs: '2026-11-02T00:00:00Z'