# Security Performance Review (SPR) API

Open, no-auth Security Performance Review: returns, drawdowns and risk metrics for one or more symbols over a date range, computed with the open-source ffn library and returned as an HTML report plus downloadable CSVs.

## Quick start

One `POST`, no API key. Copy this, then change the symbols and the dates:

```
curl -X POST https://ffn.tigzig.com/v1/analyze -H 'Content-Type: application/json' -d '{"symbols": "AAPL,MSFT,GOOG", "start_date": "2023-01-01", "end_date": "2023-12-31", "risk_free_rate": 5.0}'
```

## What you send

`POST /v1/analyze` with a JSON body containing `symbols`, `start_date` and `end_date`. Symbols follow the Yahoo Finance convention, so non-US listings carry an exchange suffix: RELIANCE.NS (India NSE), .BO (BSE), .L (London), .HK (Hong Kong), .T (Tokyo). Indices look like ^NSEI and FX like EURUSD=X. Broker, scheme or company names do not resolve. Dates are YYYY-MM-DD.

**Dates are strings, not numbers.** `start_date` and `end_date` must be written as `YYYY-MM-DD`. A bare number is rejected rather than guessed at: it could be a unix timestamp or a spreadsheet date serial, and guessing wrong produces a confidently incorrect date range. If your value came from a spreadsheet cell, wrap it as `TEXT(A1,"YYYY-MM-DD")`.

## What you get back

URLs to a generated HTML report and downloadable CSVs. The analysis lives in those files, not in the JSON.

## Public endpoints

`POST /v1/analyze`. `GET /v1/` returns the discovery block as JSON.

## Request limits

- **Report generation is serialised**, so parallel calls queue rather than finish sooner. Send them sequentially - firing them at once makes the whole set slower, not faster.
- A typical run takes **10-30 seconds**. Set your client timeout accordingly.
- At most **4 concurrent analyses per IP**; beyond that you get a 429 with `Retry-After`.
- **Read your budget off the response headers, do not hard-code a number**: `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` are on every response and come out of the running limiter, so they cannot go stale.

## Partial results

When a request is not served exactly as asked, the response carries an `X-Tigzig-Warnings` header holding a JSON array of plain-English notes - a symbol that returned no data and was excluded, or an analysis window narrowed to the range every security shares.

**The header is absent when the request was served in full, so its presence is the signal.** The report body is unaffected either way.

## Errors

Every 4xx and 5xx returns `{error: {code, message}, help: {docs, openapi, catalog}}`.

- A 4xx caused by the **shape** of the request - a missing field, or one that cannot be parsed - also carries `example`, a runnable curl built from this spec.
- A 4xx caused by a **value** does not, because the shape was already right and an example would only show you what you already sent. Read the message instead.

## Attribution

Drawdown and monthly-return analysis is computed with the open-source **ffn** library. Performance statistics are custom calculations.

More Tigzig tools: https://api.tigzig.com/.well-known/api-catalog

## Read Root

`GET /`

## Analyze

`POST /v1/analyze`

Generates a comprehensive SPR (Security Performance Review) portfolio analysis report using custom calculations and FFN metrics.

This endpoint performs detailed SPR portfolio analysis including:
- Performance statistics using custom calculations (returns, volatility, Sharpe ratio, etc.)
- Drawdown analysis using FFN library (maximum drawdown, drawdown periods)
- Monthly returns breakdown by security via FFN

Supports multiple stock symbols for SPR portfolio analysis. The risk-free rate is used in
custom Sharpe ratio and other risk-adjusted return calculations.

The SPR analysis is returned as an HTML report with:
- Data summary with date ranges and price information
- Comprehensive performance metrics table using custom calculations (including Sharpe ratios calculated with provided risk-free rate)
- Detailed drawdown analysis for each security via FFN
- Monthly return tables with color-coded performance via FFN

Example request:
{
    "symbols": "AAPL,MSFT,GOOG",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31",
    "risk_free_rate": 5.0
}

Parameters:
- symbols: Comma-separated Yahoo Finance ticker symbols (e.g., 'AAPL,MSFT,GOOG'). Supports multiple symbols for SPR analysis.
- start_date: SPR analysis start date (YYYY-MM-DD format)
- end_date: SPR analysis end date (YYYY-MM-DD format)
- risk_free_rate: Annual risk-free rate percentage (default: 0.0%). Used for custom Sharpe ratio calculations in SPR.

Returns:
- PortfolioAnalysisResponse with SPR HTML report URL and success message

Raises:
- HTTPException 400: Invalid parameters or insufficient data for SPR analysis
- HTTPException 500: Data fetching or SPR processing errors

Note: a typical run takes 10-30 seconds, longer with more symbols or a wider range.
This figure is also published in the GET /v1/ discovery block; the two must agree.
Set a client timeout of at least 120s so a slow upstream fetch does not look like a failure.

Part of Tigzig: free interactive tools, open-source repos, APIs and MCP servers for
analytics and live data across global and Indian markets, macro indicators and
filings. Catalog: https://api.tigzig.com/.well-known/api-catalog
Guide: https://www.tigzig.com/llms.txt