Get Reviews NPS By Location - Birdeye Developer Portal

get_reviews_nps_by_location

Description

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

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.

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

{
  "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.