> ## Documentation Index
> Fetch the complete documentation index at: https://birdeye-0229a3ce-responsetools.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get NPS By Location

> Compare Net Promoter Score and customer loyalty across locations.

```
get_nps_by_location
```

## Description

Returns NPS and promoter, passive, and detractor data for each business location.

## Parameters

| Parameter         | Type           | Required | Default                                   | Description                                                                                                                    |
| ----------------- | -------------- | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `startDate`       | string         | No       | 12 months ago when no period is requested | Start date in `MM/DD/YYYY` format                                                                                              |
| `endDate`         | string         | No       | Today when no period is requested         | End date in `MM/DD/YYYY` format                                                                                                |
| `reviewSites`     | list\[integer] | No       | All sources                               | Review source IDs to include                                                                                                   |
| `businessNumbers` | list\[integer] | No       | All locations                             | Location IDs to include                                                                                                        |
| `sortBy`          | string         | No       | `"review-count"`                          | Sort by `"nps"`, `"review-count"`, `"positive-review-count"`, `"negative-review-count"`, `"neutral-review-count"`, or `"name"` |
| `order`           | string         | No       | `"desc"`                                  | `"asc"` for lowest first or `"desc"` for highest first                                                                         |
| `size`            | integer        | No       | `25`                                      | Locations per page                                                                                                             |
| `page`            | integer        | No       | `0`                                       | Zero-based page number                                                                                                         |

## Example Usage

```
Which location has the worst NPS this year?
```

## Example Response

```json theme={null}
{
  "totalCount": 120,
  "avgNpsScore": "42",
  "promoters": "62",
  "passives": "18",
  "detractors": "20",
  "dataPoints": [
    {
      "label": "Acme Dental - Downtown",
      "detractorPercentile": 15,
      "passivePercentile": 17,
      "promoterPercentile": 68,
      "npsScore": 53,
      "positiveCount": 41,
      "negativeCount": 9,
      "neutralCount": 10,
      "totalCount": 60,
      "businessNumber": 78901
    },
    {
      "label": "Acme Dental - Westlake",
      "detractorPercentile": 25,
      "passivePercentile": 18,
      "promoterPercentile": 57,
      "npsScore": 32,
      "positiveCount": 34,
      "negativeCount": 15,
      "neutralCount": 11,
      "totalCount": 60,
      "businessNumber": 78902
    }
  ],
  "totalPages": 1,
  "page": 0,
  "size": 25
}
```

## Response Fields

The response includes account-level `totalCount`, `avgNpsScore`, promoter, passive, and detractor percentages. Each `dataPoints` entry contains the location `label`, `businessNumber`, `npsScore`, response counts, and segment percentages. Pagination is described by `totalPages`, `page`, and `size`.

## Notes

* `order` uses the strings `"asc"` and `"desc"`, unlike report tools that use `0` and `1`.
* NPS ranges from `-100` to `100`.
* Choose the intended server-side sort and use the first result for best, worst, or highest-count questions.
* **`size` was not honored in testing.** Passing `size: 5` still returned every location (900+ entries) with `totalPages: 1` and an echoed `size` far larger than requested. Do not rely on `size`/`page` to bound the response on large accounts — scope with `businessNumbers` instead.
* When `startDate`/`endDate` are both omitted, the live API does **not** default to 12 months back — it returned full account history (`dateDiff` of \~19,900 days) in testing. Pass explicit dates for a bounded window.