---
title: "Compare Etfs"
method: POST
path: "/api/etf/compare"
tags: ["etf"]
---

# Compare Etfs

`POST /api/etf/compare`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/etf/compare`
- Auth: API key in header `X-API-Key`

Compare two to five ETFs side by side.

Returns per-ETF summary data (holdings count, expense ratio, compliance
status, compliant/non-compliant weights) and identifies holdings that
overlap across multiple ETFs with their respective weights.

**curl example:**

    curl -X POST "http://localhost:8000/api/etf/compare" \
         -H "Content-Type: application/json" \
         -d '{"symbols": ["VTI", "SPY", "SCHB"]}'

**Python requests example:**

```python
import requests
resp = requests.post(
    "http://localhost:8000/api/etf/compare",
    json={"symbols": ["VTI", "SPY"]},
)
data = resp.json()
print(f"Overlap: {data['overlap_count']} holdings")
```

## Request body

- ETFCompareRequest: Request body to screen one ETF or compare up to six side by side.
  - `symbols` string[], required: List of 1-6 ETF ticker symbols. One symbol screens a single fund; two or more compare them side by side.

## Response `200`

Side-by-side ETF comparison with overlap analysis.

- ETFCompareResponse: Side-by-side comparison of multiple ETFs with overlap analysis.
  - `etfs` ETFCompareItem[]: Per-ETF comparison summaries.
    - `symbol` string, required: ETF ticker symbol.
    - `name` string: ETF fund name.
    - `holdings_count` integer: Number of holdings.
    - `total_assets` number, nullable: Total assets under management in USD.
    - `expense_ratio` number, nullable: Annual expense ratio as a decimal.
    - `compliance_status` string, nullable: Overall Shariah compliance status.
    - `compliant_weight` number, nullable: Summed weight of the compliant holdings, in percent.
    - `non_compliant_weight` number, nullable: Summed weight of the non-compliant holdings, in percent.
    - `holdings` ETFHoldingScreeningResult[]: Screened holdings (symbol, weight, compliance, purification), sorted by weight. Powers the full look-through and flagged-holdings filter. Per-holding financial ratios and methodology detail are fetched on demand via /api/screen/{symbol}.
      - `symbol` string, nullable: Ticker symbol of the holding, or null for a weighted line with no listing of its own.
      - `name` string: Company or security name.
      - `weight` number: Portfolio weight in percent: 6.5 means 6.5% of the fund.
      - `compliance_status` string: Shariah compliance status: 'compliant', 'non_compliant', or 'unscreened'.
      - `purification_rate` number, nullable: Purification rate for this holding, in percent: 0.88 means 0.88% of income. Null when the holding carries no rate of its own, which is the case on an unscreened line and on a holding that is compliant by nature.
  - `overlap_holdings` ETFOverlapHolding[]: Holdings that appear in multiple ETFs.
    - `symbol` string, required: Ticker symbol of the overlapping holding.
    - `name` string: Company or security name.
    - `etfs` string[]: ETF symbols containing this holding.
    - `weights` object: Mapping of ETF symbol to weight for this holding.
  - `overlap_count` integer: Total number of overlapping holdings.

## Other responses

- `404`: One or more ETF symbols not found.
- `422`: Validation Error

---

[API](https://skmtc.dev/halalterminal/apis/halal-terminal-api.md) · [All operations](https://skmtc.dev/halalterminal/apis/halal-terminal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/halalterminal/apis/halal-terminal-api/revisions/78768b250943?raw)