# 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-detailed-shares-outstanding name: AlgoSeek US Equities Detailed Shares Outstanding version: 0.1.0 status: draft domain: market-data tags: - algoseek - licensed-data - equity - reference - us description: purpose: Event-level history of shares-outstanding figures for US exchange-listed equities, extending the Basic file with security name, the change versus the prior figure, a unique event id, listing date and security status. Supports capitalization, valuation and regulatory-reporting work needing event attribution. 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. Three dates, as-of semantics: EffectiveDate = effective date of the SO value change (the as-of date of the figure); CreatedDate = trading date on which algoseek created the SO event; ChangedDate = date (optionally with an _n version suffix) on which the event was last changed. In the samples CreatedDate is never earlier than EffectiveDate (gap 1-93 days), so CreatedDate (or ChangedDate if revised) is the date a figure could have been known - use it, not EffectiveDate, to avoid look-ahead (infer… Event/step data, not a daily series: a row is a new SO figure. SO on a date D is the SharesOutstanding of the latest row with EffectiveDate <= D (and CreatedDate <= D for point-in-time use); it persists until the next row (inferred from the ''event'' wording). SharesOutstanding is ''the new shares outstanding figure'' (a level, not a change) captured from stock exchanges and company websites as soon as the official source publishes it; official update frequency varies from daily to annual, so gaps of months or years between rows are normal. Values are as reported, not restated for later splits (inferred from samples): AAPL 861,874,894 effective 20070124 versus 16,687,631,000 effective 20210416 (guide Table 1), and ARCI drops from 8,472,651 (effective 20181229) to 1,694,530 (effective 20190422), about one fifth, consistent with a reverse split. Recent figures are often rounded to thousands (ending in 000). Combine with the Adjustment Factors datasets if a split-consistent share count is needed.' authoritativeDefinitions: - type: businessDefinition url: https://algoseek.com/dataset/us-equities-detailed-shares-outstanding/ - type: implementation url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.Shares.Outstanding.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_SHARES_OUTST_DETAIL}/ format: csv encoding: UTF-8 customProperties: - property: layout value: 'Plain-text CSV with fixed header row, one row per shares-outstanding (SO) change event. Two aggregation options with identical fields: ''all'' (a single CSV for all symbols) and ''secid'' (one CSV per SecId, e.g. 33449/AAPL holds all its data). Guide mentions files so_basic.csv, so_detailed.csv and a per-SecId file being refreshed; Basic and Detailed share one guide.' - 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/shares-outst-detail 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_detailed_shares_outstanding physicalName: eq_shares_outst_detail physicalType: file logicalType: object businessName: US Equities Detailed Shares Outstanding description: Event-level history of shares-outstanding figures for US exchange-listed equities, extending the Basic file with security name, the change versus the prior figure, a unique event id, listing date and security status. Supports capitalization, valuation and regulatory-reporting work needing event attribution. dataGranularityDescription: one shares-outstanding change event (EventId) for one SecId properties: - name: SecId logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: algoseek unique security identifier. customProperties: - property: evidence value: guide+sample - name: Ticker logicalType: string physicalType: string (csv text) description: Symbol name for the security. customProperties: - property: evidence value: guide+sample - name: CreatedDate logicalType: date logicalTypeOptions: format: yyyymmdd physicalType: string (yyyymmdd) (csv text) description: Trading date when the SO event was created (first captured by algoseek); can fall on a Saturday in the sample. customProperties: - property: evidence value: guide+sample - name: ChangedDate logicalType: string logicalTypeOptions: format: yyyymmdd with optional _n version suffix (no suffix appears in the sample) physicalType: string (yyyymmdd[_n]) (csv text) description: Date, plus version number when suffixed, on which the SO event was last changed; equals CreatedDate in 70 of 76 Detailed sample rows. customProperties: - property: evidence value: guide+sample - name: EffectiveDate logicalType: date logicalTypeOptions: format: yyyymmdd physicalType: string (yyyymmdd) (csv text) description: Effective date of the SO value change; the figure's as-of date. customProperties: - property: evidence value: guide+sample - name: Name logicalType: string physicalType: string (csv text) description: Security name. customProperties: - property: evidence value: guide+sample - name: SharesOutstanding logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: New shares outstanding figure effective from EffectiveDate (a level, not a delta). customProperties: - property: unit value: shares - property: evidence value: guide+sample - name: SharesOutstandingDiff logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: Change in shares outstanding versus the previous figure; negative for reductions such as buybacks. customProperties: - property: unit value: shares - property: evidence value: guide+sample - name: EventId logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: Unique identifier of the shares-outstanding event. primaryKey: true primaryKeyPosition: 1 required: true customProperties: - property: evidence value: guide+sample - name: ListDate logicalType: date logicalTypeOptions: format: yyyymmdd physicalType: string (yyyymmdd) (csv text) description: Date the security was listed (AAPL sample shows 19801212, i.e. before the 2007 coverage start). customProperties: - property: evidence value: guide+sample - name: Status logicalType: string logicalTypeOptions: format: 1-char code physicalType: string (csv text) description: 'Security status: A active, D in default, I inactive.' enum: - value: A label: Active - value: D label: In default - value: I label: Inactive customProperties: - 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: - EventId 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_shares_outst_detail - property: vendorSampleUrl value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_shares_outst_detail.csv - property: assetClass value: equity - property: coverage value: US exchange-listed equity securities from 2007 to present (product page); official shares-outstanding figures from exchanges and company websites. Sample is AAPL only (76 events, 20070124-20220415). - property: timezone value: America/New_York - property: timestampFormat value: yyyymmdd date strings (ChangedDate may add an _n version suffix) - property: priceAdjustment value: n/a - property: licensedData value: true - property: evidenceGrade value: vendor-doc - property: knownIssues value: - 'Doc discrepancy: Guide Table 2/3 documents CreatedDate as a ''trading date'', but 12 of 76 Detailed sample rows (17 of 109 in Basic) have a Saturday CreatedDate (20071117, 20090124, 20171104, 20200104, ...); in 6 Detailed rows ChangedDate is the following Monday.' - 'Doc discrepancy: ChangedDate is documented as yyyymmdd[_n] with a version suffix, but none of the 76 sample rows carries a suffix.' - 'Doc discrepancy: Update cadence: guide says ''a couple of times a day'' (starting 04:00 AM EST); the Detailed page says the dataset is ''updated continuously throughout the trading day''.' - 'Doc discrepancy: File names: guide mentions so_basic.csv / so_detailed.csv; published samples are eq_shares_outst_basic.csv / eq_shares_outst_detail.csv.' - 'Doc discrepancy: Guide gives no Missing/null column; the sample has no blank values (Name, ListDate and Status are constant for AAPL).' - 'Doc discrepancy: Detailed sample ends 20220415 for AAPL while the Basic sample for AAPL runs to 20230721 (82 rows vs 76); the 76 shared rows match exactly on EffectiveDate and SharesOutstanding.' contractCreatedTs: '2026-11-02T00:00:00Z'