Skip to content

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.

Reference4 min read

The public reviews API is what the review widget 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

location
What it does
One location, by its slug, such as northwilds-oslo
Default
Every location
group
What it does
Every location in one location group, by the group's id. Ignored when location is given
Default
Every location
sources
What it does
Review sites, comma separated: google, facebook, trustpilot, import, sandbox. Others are ignored
Default
All of them
min
What it does
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
Default
Every rating
limit
What it does
How many reviews to return, 1 to 30
Default
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"  }}
business
What it holds
The location's name when you asked for one location, otherwise your Business name
average
What it holds
The average rating of every matching review, rounded to one decimal, or null when there are none. min doesn't change it
total
What it holds
How many reviews match location, group and sources, before min and limit
reviews
What it holds
The newest matching reviews first
reviews[].source, sourceName
What it holds
The review site, as a key and as its name
reviews[].rating
What it holds
1 to 5, or null on sites that only ask for a recommendation, such as Facebook
reviews[].recommends
What it holds
true or false on those sites, otherwise null
reviews[].text
What it holds
The review as the customer wrote it. Can be empty
reviews[].author
What it holds
First name and initial, such as Ingrid B.
reviews[].date
What it holds
When the review was written, in UTC
reviews[].url
What it holds
The review on its own site, or null
reviews[].location
What it holds
The location's name
reviews[].reply
What it holds
Your reply when it is published, with its date, otherwise null. Drafts and replies waiting for approval never show
disclosure
What it holds
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
What it holds
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.

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": "…" } }.

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

See Troubleshooting for what to do about each one.

The API returns data, not markup. Before you add review structured data to a page, read Review stars and structured data: for reviews of your own business, Google shows no stars, whatever the markup.

Was this page helpful?

Read next