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

# Get Reviews NPS By Location

> Compare review-derived Net Promoter Score and customer loyalty across locations.

```
get_reviews_nps_by_location
```

## Description

Returns **review-derived** NPS and promoter, passive, and detractor data for each business location.

<Note>
  **This is review-derived NPS.** It is computed from Birdeye **review** data, served by the review service. The population is review records and can be narrowed with `reviewSites`. Present the figure as review-based NPS so the source of the number is unambiguous.
</Note>

## 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`.
* The population is **review records**, filterable with `reviewSites`.
* Choose the intended server-side sort and use the first result for best, worst, or highest-count questions.


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