Crate indexkit 

indexkit – index constituent service for Rust, sourced from SEC EDGAR N-PORT filings.

Monthly snapshots of the S&P 500, S&P MidCap 400, S&P SmallCap 600, Nasdaq-100, and Dow Jones Industrial Average, served from parquet files with runtime GitHub fetch and local cache. No API keys. Public domain data. Offline after the first successful fetch.

Quick start – one-off scripts

use indexkit::{ym, IndexId};

#[tokio::main]
async fn main() -> indexkit::Result<()> {
    // Free functions -- no client setup needed
    let sp500 = indexkit::sp500_latest().await?;
    let ndx   = indexkit::constituents_for(IndexId::Ndx, ym!(2024, 1)).await?;

    println!("S&P 500 latest: {} holdings", sp500.len());
    println!("Top: {} at {:.2}%", sp500[0].name, sp500[0].weight * 100.0);
    println!("NDX Jan 2024: {} holdings", ndx.len());
    Ok(())
}

Client pattern – connection pool + cache reuse

use indexkit::{Indexkit, ym, YearMonth};

#[tokio::main]
async fn main() -> indexkit::Result<()> {
    let client = Indexkit::new();   // infallible, no ?

    // Any month form works -- no chrono import needed
    let a = client.sp500("2024-01").await?;
    let b = client.sp500(202401u32).await?;
    let c = client.sp500((2024i32, 1u32)).await?;
    let d = client.sp500(ym!(2024, 1)).await?;
    let e = client.sp500(YearMonth::new(2024, 1)?).await?;

    // All equivalent
    assert_eq!(a.len(), b.len());
    assert_eq!(c.len(), d.len());
    let _ = e;
    Ok(())
}

Major types

• Indexkit – stateful client; create once, call many times.
• YearMonth – year-month newtype; accepts strings, integers, tuples.
• Constituent – one holding.
• IndexSnapshot – constituents + metadata for one month.
• IndexId – typed index identifier (Sp500, Sp400, Sp600, Ndx, Dji).
• Error – unified error type; match on this, never on sub-types.

Environment overrides

Variable	Effect
INDEXKIT_BASE_URL	Replace the GitHub raw origin URL
INDEXKIT_CACHE_DIR	Override ~/.cache/indexkit/
INDEXKIT_MIRROR_URL	CDN mirror fallback URL (default: jsDelivr)

Limitations (v1.0)

• No ticker: N-PORT does not include ticker symbols. Every Constituent::ticker is None. Use CUSIP (always present) as the join key and enrich downstream via OpenFIGI or a CUSIP->ticker map.
• No GICS sector: reserved for v1.1 via SIC -> GICS cross-walk.
• 60-90 day filing lag: ETFs file N-PORT ~60 days after each month’s period end, so “latest” is typically two months behind today. This is a regulatory constraint, not a crawler limitation.
• Coverage starts 2019-11: SEC Rule 30b1-9 N-PORT public filing effective date.

Modules

• client – Indexkit async client with blocking wrappers.
• date – YearMonth newtype for month inputs.
• types – Constituent, IndexSnapshot, IndexId.
• nport – N-PORT primary_doc.xml parser.
• cik – ETF -> CIK / series mapping (verified against live SEC).
• parquet_io – parquet writer + reader.
• sec – SEC EDGAR client used by the CLI for backfill.
• error – unified Error enum and Result alias.

Re-exports

pub use client::Indexkit;

pub use date::IntoYearMonth;

pub use date::YearMonth;

pub use date::YearMonthError;

pub use error::Error;

pub use error::IndexkitError;

pub use error::Result;

pub use nport::holdings_to_constituents;

pub use nport::parse_nport;

pub use nport::NportFiling;

pub use nport::NportHeader;

pub use nport::RawHolding;

pub use sec::FilingRef;

pub use sec::SecClient;

pub use sponsor::parse_invesco_csv;

pub use sponsor::parse_ishares_csv;

pub use sponsor::SponsorClient;

pub use types::Constituent;

pub use types::DailySnapshot;

pub use types::DataSource;

pub use types::IndexId;

pub use types::IndexSnapshot;

pub use types::Resolution;

pub use types::Sector;

pub use wayback::WaybackClient;

pub use wayback::WaybackMatch;

Modules

cik

ETF -> CIK / series mapping for the five supported indices.

client

Stateful Indexkit client – flat async endpoint methods.

coalesce

Merge rows from multiple sources into a single coherent snapshot.

date

YearMonth – month resolution for index constituent snapshots.

error

Unified error type for indexkit.

nport

SEC N-PORT primary_doc.xml parser.

parquet_io

Parquet reader / writer for monthly index constituent snapshots.

sec

SEC EDGAR client for N-PORT filings.

sponsor

Sponsor-CDN holdings-file parsers (iShares, Invesco, SPDR) and the Internet Archive Wayback Machine bridge.

types

Core domain types – Constituent, IndexSnapshot, IndexId, DataSource, Resolution.

wayback

Internet Archive Wayback Machine client.

Macros

ym

Terse literal form for a YearMonth.

Functions

constituents_for

Constituents for any index at any month (uses shared global client).

dji_latest

Latest DJIA snapshot (uses shared global client).

ndx_latest

Latest Nasdaq-100 snapshot (uses shared global client).

sp500_latest

Latest S&P 500 snapshot (uses shared global client).

sp500_tickers_latest

Latest S&P 500 ticker list (uses shared global client).