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

# Number tools

> Figures about a company computed on the server, beside its confirmed rivals, each with the rows behind it, its evidence and how it was built.

A number tool answers in figures, so you never page through thousands of reviews or do the sums yourself. Each is a `GET` under `/companies/{id}/numbers/`, for the target or a confirmed rival, and most compare the company with each of its confirmed rivals. A report's exhibit saves one tool's question, and the report asks it again each time it's read.

## The answer

Every tool answers in one shape:

| Field | What it holds |
| - | - |
| `numbers` | The tool's name |
| `params` | Its arguments as read, with the defaults filled in, a window as its two days |
| `figures` | Named figures, each with its `label`, `value`, `unit` (a `share` is 0 to 1), whose `company` it is, how many it rests on (`n`), a 95% `interval` for one from a sample, and `small` when that's under 30 |
| `columns`, `rows` | The table behind a chart: a row a company, a link, a star, a month, a topic or an event |
| `evidence` | The ids behind the figures, each with the confirmed link that ties it, its own day and its page, at most 200, with `total` and `more` |
| `basis` | The sources, how many are independent, the window and a second one, the method in words, the sample against the platform's own total, known breaks in the window, what was left out and why, and caveats |

## The tools

| Route | MCP tool | What it answers |
| - | - | - |
| `GET /companies/{id}/numbers/rating` | `numbers_rating` | A company's reviews from one `source` over a window: the average, the count, the share at each star and of one and two stars, each with its interval, and the platform's own all-time figures |
| `GET /companies/{id}/numbers/rating-by-link` | `numbers_rating_by_link` | The same for each confirmed place or product, weakest first |
| `GET /companies/{id}/numbers/rating-rivals` | `numbers_rating_rivals` | The same for the company and each confirmed rival, and the gap |
| `GET /companies/{id}/numbers/rating-windows` | `numbers_rating_windows` | The last few months against the months before, for the company and each rival |
| `GET /companies/{id}/numbers/complaints` | `numbers_complaints` | What low-rated reviews complain about, by the keywords you give in `topics`, with samples to check |
| `GET /companies/{id}/numbers/series` | `numbers_series` | One field of a source's records a period at a time, such as a casino's monthly gaming revenue, against as many periods before |
| `GET /companies/{id}/numbers/timeline` | `numbers_timeline` | A company's dated events, newest first: its records that happen on a day and its stories, a changed record with what it said before |
| `GET /companies/{id}/numbers/ads` | `numbers_ads` | A brand's ads in Meta's US library on one day against another: running, started, stopped, by platform |
| `GET /companies/{id}/numbers/ads-weeks` | `numbers_ads_weeks` | The ads running at each weekly pull, with what started and stopped since the one before |
| `GET /companies/{id}/numbers/site` | `numbers_site` | A company's own site beside its rivals': pages by kind, and what they say it sells, charges, serves, where it is and who leads it |
| `GET /companies/{id}/numbers/site-changes` | `numbers_site_changes` | What changed on each one's pages between two days |

Each route's parameters are in the API reference.

## As a file

Every tool takes `format=csv`: its rows under its columns, a number a cell. With `part=figures` as well, its named figures come as the file instead, a row each, with the label, value, unit, company, how many it rests on and the interval. A file holds counts and shares, never a review's words, and is named for the company, the tool and the day.

```bash theme={null}
curl -s 'https://api.poddata.ai/v1/companies/northwind-dental/numbers/rating-rivals?source=google-maps&format=csv&part=figures' \
  -H "Authorization: Bearer $PODDATA_API_KEY" -o northwind-dental-rating-rivals-figures.csv
```

`part` without `format=csv` is a `400`: the JSON holds both. An MCP tool answers JSON only.

## Read a figure as it's meant

1. **A window is the reviews' own days.** A pull of the newest 250 can be three months or three years, so `basis.sample` gives the first and last day read, and a window that starts before them says the days before aren't covered.
2. **Only through confirmed links.** A review counts only through a link a person confirmed, and a rival only once a person confirmed it. Everything else is counted in `basis.left_out`.
3. **Under 30 is small.** A figure from fewer than 30 reviews is `small`, comes with its interval, and the caveats say a gap means little.
4. **Missing is never zero.** A figure the source withholds stays null; a month with no reviews read is null, not 0.
5. **Cite it, don't copy it.** In a report, put the figure in braces from its exhibit, and the report fills it.

```bash theme={null}
curl -s 'https://api.poddata.ai/v1/companies/northwind-dental/numbers/rating-rivals?source=google-maps&from=2025-11-14&to=2026-11-14' \
  -H "Authorization: Bearer $PODDATA_API_KEY"
```


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