# Public reviews API

> Read a location's or your whole organisation's public reviews, average rating and disclosure as JSON, with no key, for your own review section or app.

Source: https://docs.bifrostorbit.com/presence/developers/reviews-api/

The public reviews API is what the [review widget](https://docs.bifrostorbit.com/presence/developers/widgets/) reads. Call it yourself when you want your own markup, such as review cards in your shop's design or reviews in an app. It is in every plan.

```text
GET https://app.bifrostorbit.com/presence/api/public/{business}/reviews
```

`{business}` is the **Short name** under **Settings**, such as `northwilds`.

**Key:** none. The answer holds only what review sites show publicly anyway.

**Websites:** when an Admin lists websites under **Settings**, **Your website**, a browser on any other website gets `403`. Calls from a server, which send no `Origin` header, always work.

## Query parameters

| Parameter | What it does | Default |
| --- | --- | --- |
| `location` | One location, by its slug, such as `northwilds-oslo` | Every location |
| `group` | Every location in one location group, by the group's id. Ignored when `location` is given | Every location |
| `sources` | Review sites, comma separated: `google`, `facebook`, `trustpilot`, `import`, `sandbox`. Others are ignored | All of them |
| `min` | Only show reviews with this many stars or more: `2` to `5`. Reviews that only say "recommends" count as 5, "doesn't recommend" as 1 | Every rating |
| `limit` | How many reviews to return, `1` to `30` | `10` |

A location's slug comes from its name: Northwilds Oslo becomes `northwilds-oslo`. It changes when the location is renamed, so check your pages after renaming one.

Reviews from Tripadvisor, Apple Business Connect and Bing Places, and private feedback, never come through this API.

## The answer

```json
{
  "data": {
    "business": "Northwilds Oslo",
    "average": 4.6,
    "total": 131,
    "reviews": [
      {
        "id": "6aee50892701b762d4918729",
        "source": "google",
        "sourceName": "Google",
        "rating": 5,
        "recommends": null,
        "text": "Great advice on boots for the Lofoten trip.",
        "author": "Ingrid B.",
        "date": "2026-11-03T16:00:00.000Z",
        "url": "https://www.google.com/maps/…",
        "location": "Northwilds Oslo",
        "reply": { "text": "Thank you, Ingrid. Enjoy Lofoten.", "date": "2026-11-04T08:12:00.000Z" }
      }
    ],
    "disclosure": "Reviews from Google, Facebook, Trustpilot and Imported, the newest first, none left out. 1 of 131 shown. Published as written by customers; we reply but never edit them.",
    "howUrl": "https://app.bifrostorbit.com/presence/l/northwilds/northwilds-oslo"
  }
}
```

| Field | What it holds |
| --- | --- |
| `business` | The location's name when you asked for one location, otherwise your **Business name** |
| `average` | The average rating of every matching review, rounded to one decimal, or `null` when there are none. `min` doesn't change it |
| `total` | How many reviews match `location`, `group` and `sources`, before `min` and `limit` |
| `reviews` | The newest matching reviews first |
| `reviews[].source`, `sourceName` | The review site, as a key and as its name |
| `reviews[].rating` | 1 to 5, or `null` on sites that only ask for a recommendation, such as Facebook |
| `reviews[].recommends` | `true` or `false` on those sites, otherwise `null` |
| `reviews[].text` | The review as the customer wrote it. Can be empty |
| `reviews[].author` | First name and initial, such as `Ingrid B.` |
| `reviews[].date` | When the review was written, in UTC |
| `reviews[].url` | The review on its own site, or `null` |
| `reviews[].location` | The location's name |
| `reviews[].reply` | Your reply when it is published, with its date, otherwise `null`. Drafts and replies waiting for approval never show |
| `disclosure` | A sentence that says where the reviews come from, whether any ratings are left out and how many are shown. Show it with the reviews |
| `howUrl` | Your **How we collect reviews** page for the location, when you asked for one location, otherwise `null`. Link to it |

Rules in the EU and the UK ask anyone who shows reviews to say how they were collected and whether any are left out. Showing `disclosure` and linking to `howUrl` does both. See [Show reviews on your website](https://docs.bifrostorbit.com/presence/everyone/widgets/).

## Caching and limits

Answers are cached for 60 seconds in browsers and 5 minutes in shared caches, and can be served stale for an hour while they refresh (`Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=3600`). A new review or reply shows within about 5 minutes.

Each address can make 120 requests a minute. After that the API answers `429` with `Retry-After: 60`. A website with many visitors should cache on its own server, or use the widget, which browsers cache.

## Errors

Errors have the shape `{ "error": { "code": "…", "message": "…" } }`.

| Status | Code | When |
| --- | --- | --- |
| `404` | `not_found` | The short name doesn't exist, or `location` or `group` matches no location |
| `403` | `forbidden` | The browser's website isn't one of the websites under **Settings** |
| `402` | `subscription_inactive` | Your organisation's Presence Orbit trial or plan has ended |
| `429` | `rate_limited` | More than 120 requests a minute from one address |

See [Troubleshooting](https://docs.bifrostorbit.com/presence/developers/troubleshooting/) for what to do about each one.

## Stars in search

The API returns data, not markup. Before you add review structured data to a page, read [Review stars and structured data](https://docs.bifrostorbit.com/presence/developers/review-stars-and-structured-data/): for reviews of your own business, Google shows no stars, whatever the markup.
