Shadow Ingest API Reference¶
shadow-ingest exposes thirteen stable public Python APIs.
The SDK is intentionally split into:
- three task-oriented APIs for fetching core market and financial tables
- three general-purpose APIs for discovering valid inputs
- three industry APIs for taxonomy lookup and industry membership queries
- four Hong Kong APIs for HK market-data discovery and daily price queries
Task-Oriented APIs¶
| API | Use it for | Return type |
|---|---|---|
gather_daily_price(...) |
daily price history over trade_date x stock_code |
polars.DataFrame |
gather_daily_snapshot(...) |
one-date cross-sectional market snapshot | polars.DataFrame |
gather_financial_snapshot(...) |
latest financial snapshot by statement type | polars.DataFrame |
General-Purpose APIs¶
| API | Use it for | Return type |
|---|---|---|
list_fields(...) |
discovering supported fields values for gather_daily_price(...) |
list[str] |
list_market_calendar(...) |
discovering valid trading dates | list[datetime.date] |
list_universe(...) |
discovering valid stock codes for a specific date | list[str] |
Industry APIs¶
| API | Use it for | Return type |
|---|---|---|
get_industry_standards() |
listing the available industry classification standards | list[str] |
get_industry_mapping(...) |
mapping stock codes to industry rows for one standard and date | polars.DataFrame |
get_industry_members(...) |
mapping an industry code or name to member stock rows | polars.DataFrame |
Hong Kong APIs¶
| API | Use it for | Return type |
|---|---|---|
list_hk_market_calendar(...) |
discovering valid Hong Kong trading dates | list[datetime.date] |
list_hk_universe(...) |
discovering valid Hong Kong stock codes for a date | list[str] |
gather_hk_daily_price(...) |
Hong Kong daily price history | polars.DataFrame |
gather_hk_daily_snapshot(...) |
one-date Hong Kong daily snapshot rows | polars.DataFrame |
Recommended Flow¶
If you are not sure what to query yet, use the APIs in this order:
list_market_calendar(...)list_universe(...)list_fields(...)when you are querying daily pricesget_industry_standards()if you need a taxonomy such asswsorcitics- one of the dataframe-returning APIs
For Hong Kong data, use the HK-specific flow:
list_hk_market_calendar(...)list_hk_universe(...)list_fields(si.gather_hk_daily_price)when you are querying HK daily pricesgather_hk_daily_price(...)orgather_hk_daily_snapshot(...)
Which API Should I Use?¶
- use gather_daily_price for time-series daily price history
- use gather_daily_snapshot for one-date cross-sectional market snapshots
- use gather_financial_snapshot for the latest financial snapshot by statement type
- use list_fields when you want the documented supported price fields
- use list_market_calendar when you need valid trading dates
- use list_universe when you need valid stock codes for a date
- use get_industry_standards when you need the available taxonomy names
- use get_industry_mapping when you already have stock codes and need their industry rows
- use get_industry_members when you have an industry and need its member stock rows
- use list_hk_market_calendar when you need valid Hong Kong trading dates
- use list_hk_universe when you need valid Hong Kong stock codes for a date
- use gather_hk_daily_price for Hong Kong daily price history
- use gather_hk_daily_snapshot for one-date Hong Kong cross sections
Pandas Users¶
The SDK is dataframe-first with polars.DataFrame as the default return type for the table APIs.
If you prefer pandas:
pdf = df.to_pandas()