---
title: "A written comparison"
method: GET
path: "/compare/{a}-vs-{b}.json"
---

# A written comparison

`GET /compare/{a}-vs-{b}.json`

## Request

- Base URL: `https://tickerinside.com/api/v1`
- URL: `https://tickerinside.com/api/v1/compare/{a}-vs-{b}.json`
- Auth: none required

One of the 15 written comparisons, the pairs listed in index.json written_comparisons: overlap measured three ways, correlation over one, three and five years, and a summary of each fund. The file is written in the order listed there (voo-vs-vti); the other order answers 301 to it. Any other pair answers 404, reason no_written_comparison, with the two fund files. From them, compute the overlap by weight: the sum, over the tickers both hold, of the smaller of the two weights, as the overlap example does.

## Path parameters

- `a` string, required
- `b` string, required

## Response `200`

The file. The example is a real answer, shortened: long lists and maps keep their first entries.

- Compare
  - `pair` string[], nullable, required: The two tickers, in the order of the file's address and of index.json written_comparisons: this file is /compare/{a}-vs-{b}.json with a first. The other order answers 301 to this file.
  - `as_of` string, nullable, required: The price date.
  - `holdings_as_of` object, nullable, required: The date of each fund's holdings file, keyed by ticker. The two are often weeks apart.
  - `overlap` object, required: Holdings overlap, measured three ways; its fields are described below.
    - `by_weight` number, nullable: The sum, over every ticker both funds hold, of the smaller of its two weights. Symmetric: the headline figure. Tickers are compared as keys, so GOOG and GOOGL count as two.
    - `share_of_a` number, nullable: The part of the first fund's weight that sits in tickers the second also holds, in percent of the first fund's listed total weight, which can differ a little from 100. Not symmetric.
    - `share_of_b` number, nullable: The same measure from the second fund's side. When share_of_a is far above share_of_b, the first fund is mostly contained in the second.
    - `n_shared` integer, nullable: How many tickers appear in both funds. The Python client calls it companies_in_both.
    - `n_a` integer, nullable: How many positions the first fund holds, as positions in its fund file.
    - `n_b` integer, nullable: How many positions the second fund holds.
    - `top` object[], nullable: The largest shared positions: ticker, name, wa and wb, the weight in each fund rounded to two decimals, and min, the smaller of the two. pa and pb are the same weights scaled so that the largest in the list is 100, for drawing bars.
      - `ticker` string, nullable
      - `wa` number, nullable
      - `wb` number, nullable
      - `min` number, nullable
      - `pa` number, nullable
      - `pb` number, nullable
      - `name` string, nullable
    - `only_a` object[], nullable: The largest positions of the first fund that the second does not hold: ticker, name and w, the weight.
      - `ticker` string, nullable
      - `w` number, nullable
      - `name` string, nullable
    - `only_b` object[], nullable: The largest positions of the second fund that the first does not hold, in the same shape.
      - `ticker` string, nullable
      - `w` number, nullable
      - `name` string, nullable
    - `method` string, nullable: ti-overlap/1, in methods.json.
    - `method_url` string, nullable: Its address.
  - `correlation` object, nullable, required: Correlation of weekly total returns, and the annualised covariance; its fields are described below.
    - `c1y` number, nullable: Correlation of weekly total returns over one year, 52 weeks.
    - `c3y` number, nullable: Correlation over three years, 156 weeks: the figure the comparison pages quote.
    - `c5y` number, nullable: Correlation over five years, 260 weeks.
    - `cov` number, nullable: Annualised covariance of the weekly returns over three years, in percent squared. Divided by the two funds' vol, it gives c3y back, which is how a reader can check it.
    - `weeks` string[], nullable: The 52 weekly dates of the one-year spark series in funds. They are not the weeks of c3y or c5y.
  - `funds` object, required: A summary of each fund, keyed by ticker, as the comparison page shows it; its fields are described below. The full file of each fund, with its holdings, is /api/v1/fund/{ticker}.json.
  - `page_url` string, nullable, required: The written comparison's page, to link when you quote a figure.
  - `cite_as` string, nullable, required: A citation line for a quoted figure: the pair, both holdings file dates, the page, and the licence.
  - `cite_html` string, nullable, required: The credit as HTML: a link to the page cite_as names, then its address.
  - `source` string, nullable, required: The written comparison's page, which this data belongs to.
  - `license` string, nullable, required: The licence the data is published under.
  - `attribution` string, nullable, required: How to credit the data: a link to the page cite_as names where the medium allows one, the name where it does not.

## Other responses

- `301`: The address was not written the way the file is: an upper case ticker, a share class written BRK-B or BRK/B, a missing .json, or punctuation at the end. Follow the Location header (curl -L). A written comparison asked for in the other order answers 301 to its file.
- `304`: Not modified: the ETag of your copy, sent in If-None-Match, is still current. Files are cached five minutes.
- `404`: reason no_written_comparison: no comparison file for this pair in either order. fund_files gives the two fund files to compute the overlap from; the other order of a written pair answers 301 to its file.
- `503`: The file could not be served just then: retry after a minute. uptime says whether the site fails its own checks.

---

[API](https://skmtc.dev/tickerinside/apis/tickerinside-api.md) · [All operations](https://skmtc.dev/tickerinside/apis/tickerinside-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tickerinside/apis/tickerinside-api/revisions/4dae3d8c4119?raw)