> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noonum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Find comparable companies

> Find peer companies by business overlap with the REST API. Start from a company or an industry taxonomy, rank peers, and list every company in a segment group.

**Comparable companies**, or **comps**, are companies whose products, services, customers, and business activities overlap with those of the company you're studying. Finding peers by business overlap helps when a single industry classification or a company's reported segments are too broad to pick out the right peers.

Each REST call comes with a `curl` command and the equivalent Python snippet using the [`requests`](https://requests.readthedocs.io/) library. All REST paths are relative to `https://api.noonum.ai/v2`. Every request needs an `Authorization: Bearer <token>` header, where `<token>` is your Noonum API key. See [Authentication](https://docs.noonum.ai/v2/getting-started/authentication.md) to get one.

> [!NOTE]
>
> The segment endpoints are available through the REST API only. The MCP server has no matching tools.

## How Noonum identifies peers

Industry systems such as GICS, NAICS, and ICB generally give a company one primary sector or industry. That label can hide the range of a diversified company's activities, and it can lag behind changes in its business. Reported segments have limits too. Management defines them for financial reporting, so their boundaries differ from company to company, and one segment can combine businesses with different economics.

Noonum's AI knowledge engine analyzes language across a variety of information sources to identify a company's products and services, its operating activities, the relationships among its businesses, and how important each business is. When necessary, it also uses reported segment revenue to judge that importance. The result is a set of **business segments** for each company.

Each business segment has a `materiality` rating of how important it is to the company: `core` for a main business, then `significant`, then `minor`. Each company has its own rating, so the same segment can be `core` for one company and `minor` for another.

Noonum ranks peers by their aggregate weighted overlap with the company's business segments: how many segments overlap, and how important each one is to each company. The peer set does not depend on stock price performance, valuation multiples, the company's primary industry classification, or management's segment labels alone.

Noonum organizes business segments into **segment groups** and maps each group to the standard sector and industry taxonomies. A company can fall in several mapped categories when its operations warrant it. For example, Noonum places Amazon in Information Technology through AWS, Consumer Discretionary through e-commerce, Communication Services through streaming media, and Industrials through freight and logistics.

In responses, a segment group's `industries` has at most one tag per taxonomy. Each tag has a `sector`, a `path` of the levels in between, an `industry`, and `codes`:

| Taxonomy | `sector` | `path` | `industry` | `codes` |
| - | - | - | - | - |
| `gics` | GICS sector | The industry group | GICS industry | Empty |
| `naics` | NAICS sector | Empty | NAICS subsector | NAICS codes |
| `icb` | ICB industry | The supersector and sector | ICB subsector | The ICB subsector code |

You can start from a company or from an industry taxonomy. Either way, each response carries the IDs the next request takes.

## Setup

Every snippet below reuses this `BASE_URL` and `headers`:

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.noonum.ai/v2"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
```

Your plan must include segment data. Without it, every segment read returns `403`.

## Company to peer analysis

Start from a company ID. Step 2 subscribes you to the company, Step 3 returns its segments with their group IDs, Step 4 ranks its peers, and Step 5 takes a group ID and lists every company in that group.

### 1. Find the company ID

The segment endpoints identify a company by its Noonum company ID, a UUID. Search by name, ticker, ISIN, or FIGI to get it.

```bash theme={null}
curl -X POST "https://api.noonum.ai/v2/helper/companies/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "TSLA", "limit": 5}'
```

```python theme={null}
search = requests.post(
    f"{BASE_URL}/helper/companies/search",
    json={"query": "TSLA", "limit": 5},
    headers=headers,
)
search.raise_for_status()

results = search.json()["results"]
for match in results:
    print(match["id"], match["name"], [s["symbol"] for s in match["securities"]])

company_id = results[0]["id"]
```

Exact matches rank above partial matches. Each result has the company's `id`, `name`, `sector`, `industry`, and the `securities` most relevant to your query, each with a `symbol`, `exchange`, and `is_primary`. When two results have similar names, compare their securities to pick the right one. Pass its `id` as `{companyId}` in the steps below.

### 2. Subscribe to the company

You read a company's segment data with a subscription to that company. `POST /segments/subscriptions` subscribes you to each company in `companyIds`. With taxonomy access you need no subscription, so you can skip this step.

```bash theme={null}
curl -X POST "https://api.noonum.ai/v2/segments/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyIds": ["{companyId}"]}'
```

```python theme={null}
resp = requests.post(
    f"{BASE_URL}/segments/subscriptions",
    json={"companyIds": [company_id]},
    headers=headers,
)
resp.raise_for_status()

for sub in resp.json()["results"]:
    print(sub["symbol"] or sub["name"] or sub["companyId"], "until", sub["expiresAt"])
```

`results` has your subscription to each company of the request, with its `companyId`, `name`, `symbol`, `subscribedAt`, and `expiresAt`.

* A subscription lasts 365 days. You can't cancel it or move it to another company.
* A company you are already subscribed to is left as it is and does not count again, so you can send the same request twice.
* Your plan limits how many subscriptions you hold at once. The request is all or nothing: when the new subscriptions don't fit under the limit, none is made and the response is `429`.
* A subscription covers the reads of that company. Its peers appear in those responses, but to read a peer's own segments, subscribe to the peer too.

`GET /segments/subscriptions` lists the subscriptions you hold and what your plan allows.

```bash theme={null}
curl -X GET "https://api.noonum.ai/v2/segments/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python theme={null}
resp = requests.get(f"{BASE_URL}/segments/subscriptions", headers=headers)
resp.raise_for_status()
mine = resp.json()

print(len(mine["results"]), "subscriptions, limit", mine["limit"])
print("taxonomy access:", mine["taxonomyAccess"])
```

`results` lists your running subscriptions, oldest first, and leaves out the ones that ended. `limit` is the number of companies you can be subscribed to at once: `0` when your plan has no segment data, and `null` when it has no limit. `taxonomyAccess` is `true` when your plan has taxonomy access.

### 3. Read the company's segments and peers

`GET /segments/companies/{companyId}` returns the company's business segments, each with its segment group and its peers in that segment.

```bash theme={null}
curl -X GET "https://api.noonum.ai/v2/segments/companies/{companyId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python theme={null}
resp = requests.get(f"{BASE_URL}/segments/companies/{company_id}", headers=headers)
resp.raise_for_status()
company = resp.json()

for seg in company["segments"]:
    group = seg["segmentGroup"]["name"] if seg["segmentGroup"] else "no group"
    top = [c["symbol"] or c["name"] or c["id"] for c in seg["peers"]["top"]]
    print(seg["materiality"], seg["name"], "|", group)
    print("  ", seg["peers"]["count"], "peers:", ", ".join(top))
```

A trimmed response, with placeholder values:

```json theme={null}
{
  "company": {"id": "{companyId}", "name": "Example Corp", "symbol": "EXMPL"},
  "segments": [
    {
      "id": 1201,
      "name": "Segment A",
      "description": "...",
      "materiality": "core",
      "segmentGroup": {
        "id": 340,
        "name": "Segment group X",
        "description": "...",
        "industries": {
          "gics": {"sector": "...", "path": ["..."], "industry": "...", "codes": []},
          ...
        }
      },
      "peers": {
        "count": 23,
        "top": [
          {"id": "...", "name": "Peer One Inc", "symbol": "PONE", "materiality": "core"},
          ...
        ]
      }
    },
    ...
  ],
  "nonMarketItems": [{"name": "Item B", "materiality": "minor"}]
}
```

`segments` are ordered most material first, then by name. In each segment:

* `materiality` is the company's rating of the segment.
* `segmentGroup` is the group the segment belongs to, with its `industries` per taxonomy. It is `null` when the segment belongs to no group. Such a segment still lists its `peers`.
* `peers.count` is the number of other companies with the segment.
* `peers.top` names the first 8 of them: most material first, then by market cap, then by name. Each peer's `materiality` is its own rating of the segment.

`nonMarketItems` lists items found for the company that are not a market for products or services, each with a `name` and the company's `materiality`. They have no ID, group, or peers, so they add no comps.

Each segment group has its own industry tags, so one company's segments can fall in several industries. A group's `industries` has a key for each taxonomy the group is tagged in and leaves out the others. With those tags you can regroup the segments by GICS, NAICS, or ICB without another request.

A company with no business segments returns `200` with empty `segments` and `nonMarketItems`. `name` and `symbol` can be `null` for any company in a response. `id` is always set, so key your data on it.

### 4. Rank similar companies

`GET /segments/companies/{companyId}/similar` ranks peers by their weighted overlap with the company's business segments, as described in [How Noonum identifies peers](#how-noonum-identifies-peers).

```bash theme={null}
curl -X GET "https://api.noonum.ai/v2/segments/companies/{companyId}/similar?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python theme={null}
resp = requests.get(
    f"{BASE_URL}/segments/companies/{company_id}/similar",
    params={"limit": 20},
    headers=headers,
)
resp.raise_for_status()
similar = resp.json()["results"]

for peer in similar:
    shared = [f"{s['name']} ({s['materiality']})" for s in peer["sharedSegments"]]
    print(peer["score"], peer["symbol"] or peer["id"], "|", ", ".join(shared))
```

`results` lists the most similar company first. Each result has an `id`, `name`, `symbol`, `score`, and `sharedSegments`. A higher `score` means a closer peer. It has no fixed scale, so compare scores within one response only. `sharedSegments` lists the segments both companies have, at the similar company's own rating, most material first. It tells you why each company made the list.

`limit` sets how many companies to keep, from 1 to 100 (default 20). The REST API also returns every company tied with the last one kept, so `results` can be longer than `limit`.

> [!TIP]
>
> Read the company's segments first. If `segments` is empty, or every `peers.count` is 0, no other company shares a segment with it, so this call returns an empty `results` and you can skip it.

### 5. Open a segment group for the full list

`peers.top` stops at 8 companies. When `peers.count` is higher, `GET /segments/groups/{groupId}` lists every company with one of the group's segments. Take the `groupId` from `segmentGroup.id` in Step 3, or from the [taxonomy tree](#industry-to-company-analysis).

> [!NOTE]
>
> This read needs taxonomy access in your plan. Without it, the response is `403`, and your peer set comes from `peers.top` in Step 3 and the ranking in Step 4.

The snippet picks the company's most material segment with more peers than `peers.top` lists, and opens that segment's group.

```bash theme={null}
curl -X GET "https://api.noonum.ai/v2/segments/groups/{groupId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python theme={null}
my_id = company["company"]["id"]

partial = [
    s for s in company["segments"]
    if s["segmentGroup"] and s["peers"]["count"] > len(s["peers"]["top"])
]
if not partial:
    raise SystemExit("peers.top already lists every peer")
segment = partial[0]

resp = requests.get(
    f"{BASE_URL}/segments/groups/{segment['segmentGroup']['id']}",
    headers=headers,
)
resp.raise_for_status()
group = resp.json()

tiers = {"core": [], "significant": [], "minor": []}
for c in group["companies"]:
    if c["id"] == my_id:
        continue
    for s in c["segments"]:
        if s["id"] == segment["id"]:
            tiers[s["materiality"]].append(c)

for materiality, peers in tiers.items():
    print(materiality, len(peers), [c["symbol"] or c["name"] or c["id"] for c in peers[:10]])
```

The response has the group's `id`, `name`, `description`, `industries`, `segments`, and `companies`. `segments` are ordered by name, and each has an `nCompanies`. `companies` are ordered most material first, then by market cap, then by name. Each company's `materiality` is its most material rating of the group's segments. Its `segments` lists each of the group's segments it has, as an `id` and its `materiality`.

To get every peer in one segment, filter `companies` on `segments[].id`, as the snippet does. The group's `companies` includes the company you started from, while `peers` in Step 3 leaves it out, so drop its ID. A segment's `nCompanies` counts that company as well.

A segment with no group (`segmentGroup` is `null`) has no group to open. Its peers can still appear in the similar ranking from Step 4: look for the segment's `id` in each result's `sharedSegments`, and raise `limit` if you need more of them.

### 6. Example: filter the peer set

Which peers count as comps depends on your analysis. This step shows one filter, which keeps the peers that overlap with a main business of the company you're studying. Such a peer shares a segment that both companies rate `core`. A shared segment that both rate `minor` is a weak overlap.

`sharedSegments` gives the peer's rating of each shared segment, and matching its `id` to `segments[].id` from Step 3 gives the company's. The snippet also flags the peers that appear in `peers.top` for one of the company's `core` segments.

```python theme={null}
my_rating = {s["id"]: s["materiality"] for s in company["segments"]}
core_peers = {
    c["id"]
    for s in company["segments"]
    if s["materiality"] == "core"
    for c in s["peers"]["top"]
}

for peer in similar:
    core_to_core = [
        s["name"]
        for s in peer["sharedSegments"]
        if s["materiality"] == "core" and my_rating.get(s["id"]) == "core"
    ]
    if core_to_core:
        both = "yes" if peer["id"] in core_peers else "no"
        print(peer["symbol"] or peer["id"], core_to_core, "top peer:", both)
```

If none of the company's segments is `core`, run the same filter with `significant` in place of `core`. Segments come most material first, so `company["segments"][0]["materiality"]` is the company's best rating.

If you opened a group in Step 5, also keep the companies that rate its segment `core` but that `similar` doesn't list. They can rank below `limit` when their overall overlap with the company is smaller.

```python theme={null}
ranked = {p["id"] for p in similar}
missed = [c for c in tiers["core"] if c["id"] not in ranked]
print([c["symbol"] or c["name"] or c["id"] for c in missed])
```

The same data supports other filters. The peers in the company's `minor` segments, for example, overlap with it outside its main businesses. To narrow the peer set by market cap or other financial criteria, filter it with your own data.

## Industry to company analysis

Start from a taxonomy instead of a company. `GET /segments/taxonomy/{taxonomy}` returns the tree for `gics`, `naics`, or `icb`: every sector and industry, with the segment groups tagged to each.

```bash theme={null}
curl -X GET "https://api.noonum.ai/v2/segments/taxonomy/gics" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python theme={null}
resp = requests.get(f"{BASE_URL}/segments/taxonomy/gics", headers=headers)
resp.raise_for_status()
tree = resp.json()

word = "battery"
for sector in tree["sectors"]:
    for industry in sector["industries"]:
        for g in industry["segmentGroups"]:
            hits = [n for n in g.get("segmentNames", []) if word in n.lower()]
            if word in g["name"].lower() or hits:
                where = f"{sector['name']} > {industry['industry']}"
                print(g["id"], g["name"], f"({g['nCompanies']} companies)", where, hits[:3])
```

The tree has `sectors`, each with a `name` and `industries`. Each industry has its `industry` name, `path`, `codes`, and `segmentGroups`. Each group in it has an `id`, `name`, `nSegments`, and `nCompanies`. With taxonomy access, it also has `segmentNames`. Every industry of the taxonomy appears, including industries with no segment group. Each segment group appears once per tree. A group with no industry in that taxonomy sits under a sector named `Unclassified`.

With taxonomy access, the tree lists every group's segment names, so you can search it for a product word without another request. To see every company with one of a matching group's segments, open the group as in Step 5. Without taxonomy access, the snippet matches on the group names alone.

## Error handling

* **A read returns `403`**: the message in `error` names the reason.
  * `You are not subscribed to these companies.`: subscribe to the companies in the response's `companyIds`, as in Step 2.
  * `Your plan does not include taxonomy access.`: a segment group needs taxonomy access in your plan.
  * `Your plan does not include segment data.`: contact support to add segment data.
* **A subscribe returns `429`**: the new subscriptions don't fit under your plan's limit, and none was made. The response has `available`, the subscriptions your plan still has room for, and `requested`, the new subscriptions the request needed. Send fewer companies, or contact support.
* **A request returns `404`**: the company or segment group doesn't exist, and the message is `Company not found.` or `Segment group not found.` A subscribe names the companies it didn't find in `companyIds`. Take company IDs from company search, and group IDs from a company response or the taxonomy tree.
* **A request returns `400`**: the request is malformed. `companyId` must be a UUID, `companyIds` a list of at least one UUID, `groupId` an integer, `taxonomy` one of `gics`, `naics`, or `icb`, and `limit` from 1 to 100. An endpoint also rejects a query parameter it doesn't take, such as `limit` on `GET /segments/companies/{companyId}`.
* **A request returns `401`**: your API key is missing or invalid. Recheck the `Authorization` header and see [Authentication](https://docs.noonum.ai/v2/getting-started/authentication.md).

Error responses carry the message in `error`, or in `detail` when the request failed validation:

```python theme={null}
resp = requests.get(f"{BASE_URL}/segments/companies/{company_id}", headers=headers)
if not resp.ok:
    body = resp.json()
    detail = body.get("error") or body.get("detail") or resp.text
    raise RuntimeError(f"Noonum REST API {resp.status_code}: {detail}")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.