API Documentation

Authentication

The datawiser API uses API keys to authenticate requests. You can manage your API keys from your account dashboard. Include your key in the Authorization header as a Bearer token.

# Example HTTP headers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

All requests are made over HTTPS. The current base URL is:
https://api.datawiser.ai
Swagger docs: https://api.datawiser.ai/docs

Endpoints & Quick Start

The initial API focuses on capital structure data. Each endpoint exposes a versioned, event-driven dataset derived from public disclosures. Endpoints are organized by resource:

• GET /v1/free-float/{ticker} - free float time series for a given security.
• GET /v1/free-float-events/{ticker} - event-level free float changes (flat or nested detail).
• GET /v1/shares-outstanding/{ticker} - shares outstanding history.
• GET /v1/reference/{ticker} - core reference data for the security.
• GET /v1/{endpoint}/manifest - discover available tickers and metadata for any endpoint.

Once you have an API key, you can call these endpoints directly over HTTPS. Here are some simple examples.

# Get free float data for Apple
curl -X GET "https://api.datawiser.ai/v1/free-float/AAPL" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.datawiser.ai"

def get_free_float(ticker: str):
    response = requests.get(
        f"{BASE_URL}/v1/free-float/{ticker}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

# Example usage
data = get_free_float("AAPL")
print(f"Free float: {data['free_float_pct']}%")

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.datawiser.ai";

async function getFreeFloat(ticker: string) {
  const response = await fetch(`${BASE_URL}/v1/free-float/${ticker}`, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }

  return response.json();
}

// Example usage
const data = await getFreeFloat("AAPL");
console.log(`Free float: ${data.free_float_pct}%`);

SDKs & Libraries

The official Python client library is available on PyPI and GitHub.

Installation

pip install datawiserai

# with pandas support
pip install 'datawiserai[pandas]'

Quick Start

import datawiserai as dw

TICKER = "OLP"
client = dw.Client(api_key="pk_live_...")

# Discover available tickers for an endpoint
u = client.universe("free-float")
print(u.tickers)          # ['OLP', ...]
print(TICKER in u)        # True
print(u.to_dataframe())   # DataFrame of tickers, ids, timestamps

# Fetch free-float data
ff = client.free_float(TICKER)
print(ff.latest())
df = ff.to_dataframe()

# Shares outstanding
so = client.shares_outstanding(TICKER)
df = so.to_dataframe()

# Reference / identifier data
ref = client.reference(TICKER)
print(ref.company_name, ref.cik)
print(ref.company_info)
print(ref.raw)            # full JSON payload

# Free-float events — high-level event summary (one row per date)
ffe = client.free_float_events(TICKER)
df_events = ffe.to_event_summary_dataframe()
print(df_events.head())

# Free-float events — flat summary (one row per owner per date)
df = ffe.to_dataframe()

# Free-float events — full drill-down (typed OwnerDetail)
detail = client.free_float_events_detail(TICKER)
ev = detail[0]                          # FreeFloatEventDetail
ev.owner_names                          # {id: "Name", ...}
owner = ev.owner(ev.owner_ids[0])       # OwnerDetail
owner.components                        # List[Component]
owner.restrictions                      # List[Restriction]
owner.options                           # List[Option]
owner.event_details                     # EventDetails or None

For runnable scripts and a Jupyter notebook that walk through every endpoint, see the examples folder in the GitHub repository.

Caching

The client automatically caches responses under ~/.datawiserai/cache/. Before fetching data it checks the endpoint's manifest — if the server-side last_update timestamp matches the cached copy, the local version is returned instantly.

client = dw.Client(api_key="...", cache_dir="/tmp/dw_cache")  # custom location
client = dw.Client(api_key="...", use_cache=False)             # disable

client.clear_cache()                # clear everything
client.clear_cache("free-float")    # clear one endpoint

Available Endpoints

The table below maps each Python client method to its REST endpoint and return type.

Data Access Model

Access to datasets varies by plan and reflects differences in coverage universe, historical depth, and data freshness.

• Free plans provide limited universe coverage with delayed data.
• Paid plans expand coverage, extend historical windows, and provide access to additional datasets.
• Enterprise access supports full history, broader universes, and custom delivery options.

Refer to the pricing page for current plan details and availability.

For identifier handling, ticker normalization, and entity resolution, see Data & Identifiers.

Error Handling

Errors are returned with standard HTTP status codes and a JSON body describing the problem:

{
  "error": {
    "type": "invalid_request",
    "message": "Ticker symbol is required",
    "request_id": "req_1234567890"
  }
}

Common status codes:

• 400 - Invalid request parameters
• 401 - Missing or invalid API key
• 403 - Not allowed for your plan
• 404 - Resource not found
• 500 - Unexpected server error

Methodologies

datawiser methodologies document how financial datasets are derived from public disclosures, with a focus on auditability, reproducibility, identity resolution, and temporal correctness.

• How insiders, beneficial owners, and related entities are aggregated into excluded shares.
• How changes in those holdings drive free float events and free float factors over time.
• How owners, filers, securities and issuers are connected through the Master Owner Identity Graph.
• Field-by-field explanations of top-level metrics, deltas, and owner-level events.
• Worked examples showing how filings translate into event records and free-float changes.

Dedicated references can be used alongside the website, API and historical data products:

Read the Free Float Events methodology

Read the Master Owner Identity Graph methodology