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 amateriality 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 thisBASE_URL and headers:
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.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.
segments are ordered most material first, then by name. In each segment:
materialityis the company’s rating of the segment.segmentGroupis the group the segment belongs to, with itsindustriesper taxonomy. It isnullwhen the segment belongs to no group. Such a segment still lists itspeers.peers.countis the number of other companies with the segment.peers.topnames the first 8 of them: most material first, then by market cap, then by name. Each peer’smaterialityis 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.
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.peers.top lists, and opens that segment’s group.
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 ratecore. 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.
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.
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.
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 inerrornames the reason.You are not subscribed to these companies.: subscribe to the companies in the response’scompanyIds, 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 hasavailable, the subscriptions your plan still has room for, andrequested, 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 isCompany not found.orSegment group not found.A subscribe names the companies it didn’t find incompanyIds. 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.companyIdmust be a UUID,companyIdsa list of at least one UUID,groupIdan integer,taxonomyone ofgics,naics, oricb, andlimitfrom 1 to 100. An endpoint also rejects a query parameter it doesn’t take, such aslimitonGET /segments/companies/{companyId}. - A request returns
401: your API key is missing or invalid. Recheck theAuthorizationheader and see Authentication.
error, or in detail when the request failed validation: