<!-- Google Reviews API Example: Quickstart in curl, Node, Python · https://prismareviews.com/docs/quickstart -->
> Google reviews API example in 5 minutes: get an API key, connect a location with OAuth, list reviews and post a reply. curl, Node and Python code.

# Google reviews API example: your first call in 5 minutes

This Google reviews API example takes you from zero to a posted reply in four steps: get a Prisma API key, connect a Google Business Profile location with OAuth, list its reviews, and reply to one. Every step has copy-paste code in curl, Node and Python. The same calls work for the App Store, Google Play, Trustpilot and the other platforms: only the `platform` value and how you connect change.

**What you need**

- A Google Business Profile you own or manage (or an App Store, Google Play or Trustpilot account). To try the API without one, use your test key: it works right away with sample data.
- curl, Node.js 18+ (built-in `fetch`) or Python 3 with `requests`.
- 5 minutes. You don't need your own Google Cloud project: Prisma uses its own for the Business Profile API.

## Step 1 — Get your API key

[Create a free account](https://app.prismareviews.com/signup) with your email and a password, or with Google, GitHub or Apple, confirm your email and answer four short questions about how you'll use Prisma. You then get two keys, shown in full only once, so copy them: a live key (`pk_live_…`) for your real accounts and a test key (`pk_test_…`) that works right away with sample data and never touches a real account. Lost a key? Roll it in the [dashboard](https://app.prismareviews.com/api-keys) to get a new one. Store the key as an environment variable so it never ends up in your code:

```bash
export PRISMA_API_KEY="pk_live_..."
```

Every request uses `https://api.prismareviews.com/v1` and the header `Authorization: Bearer $PRISMA_API_KEY`. Keys are secret: call Prisma from your server, never from a browser. More on [Authentication](/docs/api-reference/authentication).

## Step 2 — Connect a Google Business Profile location

Create a connection. Prisma returns an `authorization_url`; open it and approve access with the Google account that owns or manages the profile.

```bash
curl -X POST https://api.prismareviews.com/v1/connections \
  -H "Authorization: Bearer $PRISMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "google", "redirect_url": "https://yourapp.com/prisma/callback"}'
```
```javascript
const res = await fetch("https://api.prismareviews.com/v1/connections", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PRISMA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ platform: "google", redirect_url: "https://yourapp.com/prisma/callback" }),
});
const connection = await res.json();
console.log(connection.authorization_url);
```
```python
import os
import requests

resp = requests.post(
    "https://api.prismareviews.com/v1/connections",
    json={"platform": "google", "redirect_url": "https://yourapp.com/prisma/callback"},
    headers={"Authorization": f"Bearer {os.environ['PRISMA_API_KEY']}"},
    timeout=30,
)
print(resp.json()["authorization_url"])
```

**Response `201`**

```json
{
  "id": "con_01KJ8P7R5S3T1V9W7X5Y3Z1A2B",
  "platform": "google",
  "status": "pending",
  "metadata": {},
  "created_at": "2026-10-21T08:55:00.000Z",
  "updated_at": "2026-10-21T08:55:00.000Z",
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=..."
}
```

When the owner approves, Prisma sends them to your `redirect_url` with `connection_id`, `status=active` and `locations_created` in the query string. The connection becomes `active` and Prisma imports the locations that account can see. With a test key, the connection is `active` at once, with two sample locations, and there is no `authorization_url`.

List the locations to get your `location_id`:

```bash
curl https://api.prismareviews.com/v1/locations \
  -H "Authorization: Bearer $PRISMA_API_KEY"
```

```json
{
  "data": [
    {
      "id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N",
      "platform": "google",
      "connection_id": "con_01KJ8P7R5S3T1V9W7X5Y3Z1A2B",
      "name": "Café Ruzafa",
      "address": "Carrer de Sueca 10, Valencia",
      "url": "https://maps.google.com/?cid=1234567890",
      "external_id": "accounts/1234567890/locations/9876543210",
      "status": "active",
      "last_synced_at": "2026-10-21T08:57:03.000Z",
      "next_sync_at": "2026-10-22T08:57:03.000Z"
    }
  ],
  "next_cursor": null
}
```

Your first 2 connected locations are free. Other ways to connect (credentials for the App Store and Google Play, a listing URL for Yelp) are on [Connections](/docs/api-reference/connections).

## Step 3 — List reviews (Google reviews API example)

Fetch the latest reviews for the location. `since` is optional and accepts a date (`2026-10-01`, midnight UTC) or a full ISO 8601 timestamp with offset (`2026-10-01T00:00:00Z`).

```bash
curl "https://api.prismareviews.com/v1/reviews?location_id=loc_01KJ8P9W2C4D6F8G0H2J4K6M8N&platform=google&since=2026-10-01" \
  -H "Authorization: Bearer $PRISMA_API_KEY"
```
```javascript
const res = await fetch(
  "https://api.prismareviews.com/v1/reviews?location_id=loc_01KJ8P9W2C4D6F8G0H2J4K6M8N&platform=google",
  { headers: { Authorization: "Bearer " + process.env.PRISMA_API_KEY } }
);
if (!res.ok) throw new Error("Prisma error " + res.status);
const { data } = await res.json();
for (const review of data) {
  console.log(review.rating, review.author, review.text);
}
```

### Google reviews API Python example

```python
import os
import requests

resp = requests.get(
    "https://api.prismareviews.com/v1/reviews",
    params={"location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N", "platform": "google"},
    headers={"Authorization": f"Bearer {os.environ['PRISMA_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
for review in resp.json()["data"]:
    print(review["rating"], review["author"], review["text"])
```

**Response** (same shape for every platform)

```json
{
  "data": [
    {
      "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
      "platform": "google",
      "location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N",
      "rating": 4,
      "title": null,
      "text": "Great flat white, a bit slow at lunchtime.",
      "author": "Marta G.",
      "language": "en",
      "url": null,
      "created_at": "2026-10-19T12:41:07.000Z",
      "updated_at": "2026-10-19T12:41:07.000Z",
      "reply": null
    }
  ],
  "next_cursor": "MjAyNi0xMC0xOVQxMjo0MTowNy4wMDBafHJldl8wMUtKOFEyTTRUN0hYM1ZCOUNXRDZOUlo1RQ"
}
```

Pass `cursor=<next_cursor>` to get the next page. When `next_cursor` is `null`, you have everything. All fields and filters are on [Reviews](/docs/api-reference/reviews).

## Step 4 — Reply to a review

Replies to Google reviews are published through Google's API. Posting again replaces the existing reply.

```bash
curl -X POST https://api.prismareviews.com/v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply \
  -H "Authorization: Bearer $PRISMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1e2a90-4b1d-4e0a-9d55-1f6c0b7f2e31" \
  -d '{"text": "Thanks Marta! We have added a second barista at lunch. See you soon."}'
```
```javascript
import crypto from "node:crypto";

const res = await fetch("https://api.prismareviews.com/v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PRISMA_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ text: "Thanks Marta! We have added a second barista at lunch." }),
});
console.log(res.status, await res.json());
```
```python
import os
import uuid
import requests

resp = requests.post(
    "https://api.prismareviews.com/v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply",
    json={"text": "Thanks Marta! We have added a second barista at lunch."},
    headers={
        "Authorization": f"Bearer {os.environ['PRISMA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=30,
)
print(resp.status_code, resp.json())
```

**Response `202`**: the full review, with the reply queued for publishing.

```json
{
  "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
  "platform": "google",
  "location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N",
  "rating": 4,
  "title": null,
  "text": "Great flat white, a bit slow at lunchtime.",
  "author": "Marta G.",
  "language": "en",
  "url": null,
  "created_at": "2026-10-19T12:41:07.000Z",
  "updated_at": "2026-10-19T12:41:07.000Z",
  "reply": {
    "text": "Thanks Marta! We have added a second barista at lunch.",
    "created_at": null,
    "status": "queued",
    "error": null
  }
}
```

A background job publishes the reply on Google. When it is live, `reply.status` becomes `published` and you get a `reply.published` [webhook](/docs/api-reference/webhooks). If Google refuses it, `reply.status` becomes `failed` with the reason in `reply.error`, and you get `reply.failed`. With a test key the reply goes through the same steps but is never published anywhere.

That's it: you listed reviews and sent a reply. If this took more than 15 minutes, tell us at hello@prismareviews.com; it's a bug on our side.

## Next steps

- **Get reviews pushed to you.** Register a webhook for `review.created` with `POST /v1/webhooks` instead of polling. See [Webhooks](/docs/api-reference/webhooks).
- **Add more platforms.** Repeat step 2 with another `platform`: `trustpilot` uses OAuth too, while `app_store` and `google_play` use credentials. See [Platforms](/docs/api-reference/platforms).
- **Handle errors.** A connection that needs reauthorization and the per-key rate limit are the two you will meet first. See [Errors](/docs/errors).

## Common mistakes

- **Calling from the browser.** Your API key is a secret. Call Prisma from your server.
- **Connecting with the wrong Google account.** The account that approves OAuth must be an owner or manager of the profile, or no locations appear.
- **Replying to an unverified Google location.** Google only accepts replies on verified locations. The request is accepted, then the reply ends as `failed` with Google's answer in `reply.error`.
- **Bulk-replying in a tight loop.** Google limits edits per Business Profile (see [Google Business Profile API usage limits](https://developers.google.com/my-business/content/limits)). Prisma queues and retries, but space out large batches, and watch your own rate limit (`429 rate_limited`).
- **Expecting old Google Play reviews.** The Google Play API only returns reviews created or edited in the last 7 days. Prisma keeps every review it sees from the day you connect, but can't import older ones.

## FAQ

### Is there an official Google reviews API?

Yes. Reviews live in the Google Business Profile API (formerly Google My Business API). It requires a Google Cloud project with API access and OAuth on a profile you manage. Prisma uses its own Google Cloud project, so you only authorize your profile with OAuth.

### How many reviews does one call return?

Prisma pages results with `next_cursor`; the page size is 50 by default, and you can set it with `limit` up to 100. For reference, Google's own reviews.list returns up to 50 reviews per page.

### Can I use this Google reviews API Python example for Trustpilot or the App Store?

Yes. Steps 3 and 4 are identical: the response JSON has the same shape on every platform. Only step 2 changes: Trustpilot also needs the profile's domain, and the App Store connects with an App Store Connect API key instead of OAuth.

### Do I need a Google Cloud project?

No. Prisma uses its own Google Cloud project. You only approve access to your profile with OAuth.

### Can I read competitors' reviews?

No. Prisma only works on accounts you own or manage.

### What does it cost after the first 2 locations?

Plans start at €49 a month for up to 10 locations. See [pricing](/pricing).