# GET /api/v1/diversify?have={have}&try={try}

One endpoint of the TickerInside API, with data through 2026-10-16. Contents of the reference, each section and endpoint as a file: https://tickerinside.com/api/sections/index.md. The whole reference as Markdown: https://tickerinside.com/api/index.md

`GET /diversify?have={have}&try={try}`: each fund of `try` against those of `have` (QQQ:40 for a weight): overlap, correlations, mega-cap tech, sectors, countries, a sentence each. With `have` alone, the 30 large US ETFs of a published list ranked by weekly correlation with the portfolio, one per group first. Page: /diversify/. The list and its weekly returns: /diversify/candidates.json; one ETF's: /diversify/weekly/{ticker}.json. https://tickerinside.com/api/v1/diversify?have=QQQ,SMH&try=AVUV and https://tickerinside.com/api/v1/diversify?have=VOO

## Response

With have alone, Find: the large US ETFs of a fixed, published list, in six groups, ranked by the correlation of their weekly returns with the portfolio's over up to 156 weeks, compared before rounding, leaving out any ETF held; the answer opens on the ETF of lowest correlation in each of the 3 groups where it is lowest, with its correlation on the weeks the portfolio fell, its volatility, the portfolio's volatility with 10% in it, what it holds, and its overlap with the portfolio when the files fit the limits of Find; every ETF of the list follows, ranked (mode find, the fields below). A sort of measurements by a published rule. For each fund of try, a list separated by commas, against the portfolio of the funds of have, each with its weight after a colon or none for equal weights: the overlap by weight with the portfolio looked through, the correlation of weekly returns with the portfolio's over up to three years and on the weeks it fell, the part in mega-cap tech, and the sectors and countries of its lines, with one sentence to quote for each, ranked by overlap, then by correlation. A trust, a derivative-based or a bond fund has no overlap by shares and counts in the correlation from its own weekly prices. /diversify/ with the same query renders the answer as a page, which share_url gives. No CSV. 1 to 6 funds in have and 1 to 6 in try. The files read weigh at most 90 KB, a compact file for half its size and a file of the other layers for a third, and hold at most 20,000 lines between them; each fund to try is compared with each fund held in at most 16,000 comparisons of lines in all, about the lines of the shorter of each pair. With have alone, Find ranks the list for any portfolio of up to 6 funds with weekly returns; the overlap of its 3 runs when the files of both sides fit the lower limits of Find, and overlap says whether it ran.

```json
{
  "…": "2 more fields",
  "question": "Does VXUS or SPMO diversify a portfolio of QQQ 60%, SMH 20% and GLD 20%?",
  "…": "1 more field",
  "answers": ["VXUS has an overlap of 0.6% by weight with a portfolio of QQQ 60%, SMH 20% and GLD 20%, by the issuer files of 2026-08-31 for VXUS and 2026-10-10 for QQQ, and the Form N-PORT filing of 2026-06-30 for SMH; its weekly returns had a 0.75 correlation over 156 weeks to 2026-10-09, and 0.65 over the 57 weeks the portfolio fell.", "… 1 more"],
  "…": "1 more field",
  "candidates": [{"ticker": "VXUS", "…": "5 more fields", "overlap": {"by_weight_pct": 0.6, "…": "1 more field", "companies_in_both": 4, "…": "1 more field"}, "correlation": {"weekly": 0.75, "weeks": 156, "from": "2023-10-20", "to": "2026-10-09", "down_weeks": 0.65, "down_weeks_count": 57, "with": ["QQQ", "SMH", "GLD"]}, "…": "2 more fields", "mega_cap_tech_pct": 0, "…": "2 more fields", "rank": 1, "…": "1 more field"}],
  "…": "1 more field",
  "prices_as_of": "2026-10-09",
  "…": "1 more field",
  "share_url": "https://tickerinside.com/diversify/?have=QQQ:60,SMH:20,GLD:20&try=VXUS,SPMO",
  "…": "6 more fields"
}
```

- `kind` (string): Always diversify.
- `mode` (string): compare, the check of the funds of try against the funds of have. With have alone the answer is Find, mode find, another shape (DiversifyFind).
- `question` (string): The question answered, in words: the funds to try and the portfolio of the funds held, with their weights.
- `answer` (string): The answer in one sentence, to quote as it is: of the funds to try, the one with the lowest overlap and the one with the lowest weekly correlation, with the figures and their period, or for one fund to try its two figures; the line /diversify/ prints under the question.
- `answers` (array of string): One sentence per fund to try, in the order of candidates, to quote as it is: its overlap with the portfolio, the correlation of weekly returns with the portfolio's over the weeks both have and on the weeks the portfolio fell, and the holdings dates, or why a figure is not measured.
- `have` (object): The portfolio of the funds held: each fund (funds) with its weight_pct, name, holdings_as_of, holdings_source, holds_shares and weekly_returns, the number of weekly returns its file has; weights, given or equal; looked_through_pct, the part of the portfolio in funds that hold shares; holds_no_shares; returns_from, the funds its weekly returns are computed from, and no_price_history; no_breakdown, the funds holding shares whose file gives no breakdown; mega_cap_tech_pct, sectors and countries as each candidate has them, its funds' at their weights, in percent of the whole portfolio; and its sentence.
- `candidates` (array of object): Each fund to try, ranked (see ranking).
- `ranking` (string): The rule of the order of candidates, in words.
- `prices_as_of` (string): The last week of the weekly returns, the date of the prices.
- `definitions` (object): How each figure is computed, in the words /diversify/ prints: overlap, share_of_candidate (the part of the candidate in companies the portfolio holds), correlation, down_weeks, sectors and countries; the companies counted as mega-cap tech (mega_cap_tech: rule and companies, each with its name and tickers), the fixed list every fund file's breakdown counts; and sectors_stated_from_pct.
- `skipped` (object): The tickers not covered, under not_covered, left out of the answer. Absent when every ticker is covered.
- `renamed` (object): Each ticker asked that a fund had before it was renamed, with its ticker now, under which the answer reads and names it. Absent when there is none.
- `share_url` (string): The page of this answer, /diversify/ with the same query, which renders it for a person or an assistant that fetches it.
- `api_url` (string): This answer's own address.
- `source` (object): The files the answer is computed from: each fund's page_url, null without a page, api_url and holdings_source; reference_url, the file of mega-cap tech and the names of the sectors and countries; license; and cite_as.
- `note` (string): Measurement, not investment advice.
- `license` (string): The licence the data is published under.
- `attribution` (string): How to credit the data: a link to the page of a fund the figure comes from, or to this address, where the medium allows one, the name where it does not.
- `docs` (string): The reference of this endpoint.

A fund to try, in candidates:

- `ticker` (string): The fund to try.
- `name` (string): Its name.
- `holdings_as_of` (string): The date of its holdings: its issuer file, or the quarter end its filing describes.
- `holdings_source` (string): Its source: issuer file, SEC Form N-PORT, trust's own SEC filing, sponsor's own holdings file, or prospectus, no holdings yet.
- `fund_file` (string): The address of its fund file.
- `page_url` (string or null): Its page. Null without one.
- `overlap` (object or null): In percent: by_weight_pct, the sum over the companies it and the portfolio both hold of the smaller of its weight and the portfolio's, the portfolio looked through its funds at their weights; share_of_candidate_pct, the part of the fund in those companies; companies_in_both, the holdings both have, counted by ticker; and largest_shared, up to five, each with in_candidate_pct, in_have_pct and counted_pct. Null for a fund that holds no shares, or when no fund held does (see not_measured).
- `correlation` (object or null): Of weekly returns, the fund's against the portfolio's: weekly, over weeks weeks from from to to, each the last close of its week (weeks run Saturday to Friday: a week closes on its Friday, or on the Thursday when the exchange is shut that Friday, and the last week on the data's last close); down_weeks, the same on the down_weeks_count weeks the portfolio fell, null under 20 of them; and with, the funds held whose returns the portfolio's are computed from. Null without 52 weeks in common (see not_measured).
- `volatility_pct` (number): Its annualised weekly volatility over the weeks of its correlation, in percent; absent when the correlation is not measured.
- `with_10_pct` (object): The portfolio's annualised weekly volatility with 10% in this ETF and 90% in the ETFs held at their weights, rebalanced weekly (volatility_pct), against the portfolio alone (instead_of_pct), over the weeks of its correlation; absent when the correlation is not measured.
- `mega_cap_tech_pct` (number or null): The part of the fund in the companies definitions.mega_cap_tech lists, in percent to one decimal, from its fund file's breakdown. Null for a fund that holds no shares or has no breakdown.
- `sectors` (object or null): From its fund file's breakdown: known_pct, the part of the fund whose sector is found; coverage_pct, that part of its stock weight; stated, whether coverage_pct reaches definitions.sectors_stated_from_pct; and weights, when stated, each sector with its id (sector), name and pct of the fund, largest first. Null as mega_cap_tech_pct is.
- `countries` (object or null): From its fund file's breakdown, in percent of the fund: us_pct, the United States; weights, up to six countries, largest first, each with its ISO code (country), name and pct; and other_pct, the rest. Null as mega_cap_tech_pct is.
- `not_measured` (object): Why a figure is null, by figure: overlap, correlation, down_weeks or profile. Absent when every figure is given.
- `rank` (integer): Its place in the order of ranking, from 1.
- `sentence` (string): Its sentence, as answers gives it.

What have alone gives (mode find): /api/v1/diversify?have=VOO:60,QQQ:20,VXUS:20:

- `kind` (string): Always diversify.
- `mode` (string): Always find: have alone, no try.
- `question` (string): The question answered, in words: which ETF in each group of the list had the lowest weekly correlation with the portfolio of the funds held, with their weights; when a fund held has no price history here, with the funds of returns_from, at their weights among them, which every figure of weekly returns names.
- `answer` (string): The answer in one sentence, to quote as it is: the ETF of lowest weekly correlation in each of the 3 groups where it is lowest, each with its group and figure, and the weeks with their last date; the line /diversify/ prints under the question.
- `answers` (array of string): One sentence per ETF of lowest, to quote as it is: its weekly correlation with the portfolio over the weeks and on the weeks the portfolio fell, its place in its group, and its overlap by weight with the holdings dates when measured.
- `have` (object): The portfolio of the funds held: each fund (funds) with its weight_pct, name, weekly_returns, holdings_as_of, holdings_source, holds_shares and page_url; weights, given or equal; returns_from, the funds its weekly returns are computed from, and no_price_history; volatility_pct over its weeks, weeks and to, of the weekly returns of the funds of returns_from; looked_through_pct; and mega_cap_tech_pct, sectors and countries, its funds' breakdowns at their weights, each fund's from its own file whether it has a price history here or not, the same figures as the check of the same portfolio; null when one of its funds holding shares has none, or when a fund's file is more than the answer reads beside the ranking, which its note names.
- `list` (object): The list ranked: its name, list_date (the day it was chosen; a change of the list is a new date), about (the list in one sentence), left_out_on_purpose (what the list leaves out, in words), count, ranked (tonight, leaving out the funds held and any without weekly returns tonight), groups (id, label and tickers, in the order of the list), held_and_left_out, no_weekly_returns_tonight, and url, the list as a file.
- `rule` (string): The rule of the ranking, in words, as the page prints it.
- `lowest` (array of object): The ETF of lowest weekly correlation in each of the 3 groups where it is lowest, lowest first: a sort of the list's measurements by its published rule.
- `lowest_by_group` (array of object): The ETF of lowest weekly correlation in every group, lowest first: group, group_label, ticker, weekly and weeks.
- `ranked` (array of object): Every ETF of the list ranked, lowest weekly correlation first before rounding, an exact tie in the order of the list: rank, ticker, name, group, group_label, page_url, weekly, down_weeks and weeks.
- `overlap` (string): measured when the overlap of the 3 with the portfolio ran, the files of both sides within the limits of Find; not_measured otherwise, and overlap is null in lowest.
- `overlap_answered_by` (object): When overlap is not_measured, the check that answers it in one call: tickers, the ETFs of lowest that hold shares; page, the check's page; and diversify, its JSON answer, each with the overlap by weight of those ETFs with the portfolio. Absent when no check of them fits the limits of one call.
- `ties` (array of object): An ETF of lowest whose weekly correlation prints the same as others of its group: ticker, with, printed. The order is before rounding. Absent without one.
- `prices_as_of` (string): The last week of the weekly returns, the date of the prices.
- `definitions` (object): How each figure is computed, in the words /diversify/ prints: correlation, down_weeks, volatility, with_10_pct, overlap, mega_cap_tech, sectors and countries.
- `share_url` (string): The page of this answer, /diversify/?have=, which renders it for a person or an assistant that fetches it.
- `api_url` (string): This answer's own address.
- `source` (object): The files the answer is computed from: each fund's page_url and api_url; list_url, the list; license; and cite_as.
- `note` (string): Measurement, not investment advice.
- `license` (string): CC BY 4.0.
- `attribution` (string): How to credit the data.
- `docs` (string): This endpoint's reference.

An ETF of the list, in lowest:

- `rank` (integer): Its place among the 3, lowest first, from 1.
- `ticker` (string): The ETF of the list.
- `name` (string): Its name.
- `group` (string): Its group in the list, by id.
- `group_label` (string): Its group, in words.
- `page_url` (string or null): Its page. Null without one.
- `fund_file` (string): The address of its fund file.
- `holdings_as_of` (string): The date of its holdings.
- `holdings_source` (string): Its source: issuer file, SEC Form N-PORT or trust's own SEC filing.
- `correlation` (object): Of weekly returns, the ETF's against the portfolio's, as a candidate's in the check: weekly, weeks, from, to, down_weeks, down_weeks_count and with.
- `volatility_pct` (number): Its annualised weekly volatility over the same weeks, in percent.
- `with_10_pct` (object): The portfolio's annualised weekly volatility with 10% in this ETF and 90% in its funds at their weights, rebalanced weekly (volatility_pct), against the portfolio alone (instead_of_pct), over weeks to to.
- `overlap` (object): Its overlap by weight with the portfolio looked through, as a candidate's in the check, when measured; null otherwise, and for an ETF that holds no shares.
- `mega_cap_tech_pct` (number): Its part in mega-cap tech, from its fund file's breakdown; null for an ETF that holds no shares.
- `sectors` (object): Its sectors, from its fund file's breakdown, as a candidate's in the check.
- `countries` (object): Its countries, from its fund file's breakdown, as a candidate's in the check.
- `holds` (string): For an ETF that holds no shares, what it holds in two words.
- `composition` (array of object): For an ETF that holds no shares, what it holds by kind, up to three, each with label and pct.
- `sentence` (string): Its sentence, as answers gives it.

The list, /api/v1/diversify/candidates.json:

- `name` (string): The list's name.
- `list_date` (string): The day the list was chosen. A change of the list is a new date.
- `about` (string): The list in one sentence.
- `left_out_on_purpose` (array of string): What the list leaves out on purpose, in words.
- `weeks_end` (string): The last week of the weekly returns in w, the date of the prices.
- `rule` (string): The rule of the ranking, in words, as every answer prints it.
- `top` (integer): How many groups an answer opens on.
- `min_weeks` (integer): The fewest weekly returns a correlation is computed on.
- `groups` (array of object): The groups in the order of the list: id, label, one (an ETF of the group, in a sentence) and tickers.
- `unit` (string): How w is written.
- `left_out_tonight` (array of string): The ETFs of the list with no weekly returns in tonight's files, left out of every ranking until they have them.
- `funds` (array of object): Each ETF of the list with weekly returns tonight, in the order of the list.
- `license` (string): CC BY 4.0.
- `reference_weight` (integer): What /api/v1/diversify/reference.json counts for against the limits of an answer, in the units of size.

An ETF of the list, in funds:

- `t` (string): Its ticker.
- `g` (string): Its group, by id.
- `vol` (number): Its annualised weekly volatility over 156 weeks, in percent, as its fund file gives it.
- `n` (string): Its name.
- `page` (string or null): Its page on the site. Null without one.
- `size` (integer): What its file counts for against the limits of an answer: a file under /fund/ its length, its compact file under /diversify/funds/ half of that file's, a file under /etf/ a third.
- `lines` (integer): How many holdings the overlap reads of it; 0 for an ETF that holds no shares.
- `l` (string): Its source layer, as source_layer in its fund file: issuer, sec_nport, sec_nport_bonds, trust_filings and the others.
- `h` (string): The date of its holdings.
- `bd` (object): For an ETF that holds shares, its breakdown, the one its fund file gives: sectors_pct, no_sector_pct, sector_coverage_pct, sectors_stated, other_funds_pct, mega_cap_tech_pct and countries_pct.
- `comp` (array of object): For an ETF that holds no shares, what it holds by kind, up to three, each with label and pct of its net assets.
- `w` (array of integer): Its weekly returns as whole numbers of 0.0001 (divide by 10,000: 47 is 0.47%), oldest first, ending at weeks_end; null for a week without a return.

One ETF's weekly returns, /api/v1/diversify/weekly/{ticker}.json: /api/v1/diversify/weekly/voo.json:

- `t` (string): Its ticker.
- `n` (string): Its name.
- `page` (string or null): Its page on the site. Null without one.
- `size` (integer): What its file counts for against the limits of an answer: a file under /fund/ its length, its compact file under /diversify/funds/ half of that file's, a file under /etf/ a third.
- `lines` (integer): How many holdings the overlap reads of it; 0 for an ETF that holds no shares.
- `l` (string): Its source layer, as source_layer in its fund file: issuer, sec_nport, sec_nport_bonds, trust_filings and the others.
- `h` (string): The date of its holdings.
- `bd` (object): For an ETF that holds shares, its breakdown, the one its fund file gives: sectors_pct, no_sector_pct, sector_coverage_pct, sectors_stated, other_funds_pct, mega_cap_tech_pct and countries_pct.
- `comp` (array of object): For an ETF that holds no shares, what it holds by kind, up to three, each with label and pct of its net assets.
- `w` (array of integer): Its weekly returns as whole numbers of 0.0001 (divide by 10,000: 47 is 0.47%), oldest first, ending at end; null for a week without a return.
- `end` (string): The last week of w, the date of the prices.
- `solo` (object): Its own ranking against the list as a one-ETF portfolio, when the list ranks it: list_date, lowest (the 3 of the answer, in order) and rows, every ETF of the list not held as [ticker, weekly correlation, on down weeks, weeks, down weeks], the correlations in hundredths (divide by 100), lowest first before rounding.

The files Find reads, public like every file under /api/v1/. candidates.json is the list: its date, its groups, its rule in words, and each ETF of it with its weekly returns, its breakdown or what it holds, and what its file counts for against the limits of an answer. /api/v1/diversify/weekly/{ticker}.json, in lower case, is one ETF's weekly returns and breakdown, for every ETF with at least 52 weekly returns whose last week is the list's, with its own ranking against the list. An answer of have alone is a sort of these measurements by the published rule, the same list for every portfolio: a ranking can be recomputed from these files alone, as Pearson's correlation of w against the portfolio's weekly returns at its weights. The analytics record its tickers, never a weight. The answer, which repeats the weights, is kept in the edge cache for up to a day under its query, and served only to the same query.

## Errors and redirects

| Status | reason | Meaning | Next request |
|---|---|---|---|
| 200 |  | The file. | Read it. Every file carries its dates. |
| 204 |  | A browser's CORS preflight, an `OPTIONS` request, answered before any redirect: GET and HEAD from any origin, with the headers asked for, kept up to a day. | Nothing to do. |
| 301 |  | An upper case ticker, a share class written `BRK-B` or `BRK/B` (the file is `brk.b.json`), an address without `.json`, `/api/v1` alone, or punctuation copied from a sentence at its end. A key listed abroad with a hyphen, such as `SQM-B`, keeps it. A written comparison asked for in the other order leads to its file: `vym-vs-vig` to `vig-vs-vym.json`. A fund with no file under `/etf/` leads to its file under `/fund/`: `etf/voo.json` to `fund/voo.json`. `/stock/`, the name of the pages, leads to the stock files under `/sec/`: `stock/nvda.json` to `sec/nvda.json`. | Follow it (`curl -L`). `Location` gives the address. |
| 304 |  | Your `If-None-Match` matches the file's `ETag`. | Keep your copy. |
| 400 |  | A computed answer refused its query: `reason` (`missing_parameter`, `unknown_parameter`, `repeated_parameter`, `invalid_value`, `too_few_funds`, `too_many_funds`) and `parameter` say why. | Fix it as `message` says. |
| 400 | `too_large` | Past the limits of one call (fund files read, holdings compared or looked through): `limit` and `asked` give both figures. | Follow the address or tool `message` names first (`answered_by` gives them as fields), or ask for fewer funds per call. |
| 404 | `no_such_endpoint` | No endpoint at this address. | `covered`: `index.json`. |
| 404 |  | Under `/overlap`, `/lookthrough` and `/diversify`: a fund the answer needs is not covered; `not_covered` lists the tickers and `reasons` their codes. | `covered`: `index.json`. |
| 405 |  | A computed answer asked with another method than GET or HEAD (`method_not_allowed`). | Use GET. |
| 503 |  | The file could not be served just then. The body's `error` is `unavailable`, with `Retry-After: 60`. | Retry after a minute. `uptime`: `uptime.json` says whether the site fails its own checks. |

Every 404 body is JSON. It holds `error`, always `not_covered`; `reason`, a code /contract/ lists; `ticker`, as asked for, or null when the address names no ticker; `message`; `docs`; and the follow-up address named above. Under /history/, it also holds `date` when a date was asked for. `before_history`, for a date before a fund's first file, is answered only once holdings at a date are served. A 400 body holds `error` (`bad_request`), `reason`, `message`, `docs`, and `parameter`, or `limit` and `asked`.