Skip to main content
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 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 to get one.
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: 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:
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.
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.
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.
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.
A trimmed response, with placeholder values:
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.
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.
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.
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.
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.
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.
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.
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.
Error responses carry the message in error, or in detail when the request failed validation: