API Documentation

You are implementing Google reviews display for a website using the Overunity Reviews API.

## Service
Overunity Reviews (https://reviews.overunity.ca) fetches, caches, and serves Google Maps
business reviews via a simple JSON API. No Google API key is needed on your end. All Google API
calls happen server-side at Overunity. Reviews are kept fresh automatically.

## Credentials
Add to .env — value provided by the site owner / Overunity:
  OVERUNITY_KEY=your-key            # 32-char key derived from Place ID + website URL

## Endpoint
  GET https://reviews.overunity.ca/api/reviews/{OVERUNITY_KEY}

No API key header. The key in the URL authenticates the request.

CRITICAL: Always fetch server-side. Never call this from browser/client JavaScript.
Use a Next.js server component, SvelteKit +page.server.ts, API route, or serverless function.

## Query Parameters (all optional)
  ?limit=N           Return at most N reviews (e.g. limit=3 for a reviews section)
  ?sort=latest       Newest first (default)
  ?sort=random       Random order — use with limit=1 for a rotating testimonial widget
  ?since=YYYY-MM-DD  Only reviews published on or after this ISO date

## Full Response Shape
{
  "key": "your-key",
  "placeId": "ChIJ...",
  "businessName": "Business Name",       // Official name from Google
  "rating": 4.8,                         // Google average rating (float, 1.0–5.0)
  "userRatingCount": 127,                // Total reviews on Google (often 100s)
                                         // NOTE: NOT the same as reviews.length
  "googleMapsPlaceUrl": "https://...",   // → "See all reviews on Google" / "View on Google Maps"
  "googleWriteReviewUrl": "https://...", // → "Write a review" CTA (opens Google review dialog)
  "fetchedAt": "2025-03-05T03:00:00Z",  // ISO timestamp of last Google fetch
  "stale": false,                        // true if cache couldn't be refreshed
  "source": "google_places",
  "poweredBy": { "text": "Powered by OverUnity", "url": "https://reviews.overunity.ca" },  // Display at bottom (required)
  "reviews": [
    {
      "author": "Jane S.",               // Reviewer's Google display name
      "rating": 5,                       // Integer 1–5
      "text": "Amazing service!",        // Full review text
      "relativeTime": "2 weeks ago",     // Human-readable string from Google — use for display
      "publishTime": "2025-02-15T12:00:00.000Z", // ISO date — use for filtering or sorting
      "authorPhotoUri": "https://...",   // Google profile photo URL; may be null
      "googleMapsUri": "https://..."     // Direct link to this specific review on Google
    }
  ]
}

## UI Implementation — What to Build

### Business summary / rating block
- Render the star rating visually (e.g. ★★★★★ filled/empty based on rating value)
- Display: "{rating} · {userRatingCount} Google reviews"
- Link "View all reviews on Google" → googleMapsPlaceUrl (target="_blank", rel="noopener")
- CTA button: "Write a Review" → googleWriteReviewUrl (target="_blank", rel="noopener")

### Review cards
- Show: author name + avatar (authorPhotoUri, circular, null-safe), star rating, review text, relativeTime
- Add a small "↗ View on Google" link per card using googleMapsUri — this builds trust
- Truncate long review text with a "Read more" toggle if needed

### "See all reviews" CTA
- Button or text link → googleMapsPlaceUrl — takes the user to the full Google listing

### Empty / error state (always handle this)
- Condition: !data || data.reviews.length === 0 || data.stale === true
- Show graceful fallback: "Reviews temporarily unavailable" or similar
- Never crash; the API will always return a valid JSON object

### Attribution (required)
Display a small "Powered by OverUnity" link at the bottom of the reviews section. The API returns `poweredBy: { text, url }`.
Use subtle styling: ~11px font, muted color (#6b7280 or similar). Example:
  <a href="https://reviews.overunity.ca" target="_blank" rel="noopener" style="font-size:11px;color:#6b7280;">Powered by OverUnity</a>

## Server-side Fetch Examples

### SvelteKit (+page.server.ts or +layout.server.ts)
import { env } from '$env/dynamic/private';
export async function load({ fetch }) {
  try {
    const res = await fetch(
      `https://reviews.overunity.ca/api/reviews/${env.OVERUNITY_KEY}`
    );
    if (!res.ok) return { reviews: null };
    return { reviews: await res.json() };
  } catch {
    return { reviews: null };
  }
}

### Next.js App Router (server component)
const res = await fetch(
  `https://reviews.overunity.ca/api/reviews/${process.env.OVERUNITY_KEY}`,
  { next: { revalidate: 3600 } } // Re-fetch at most every hour
);
const reviews = res.ok ? await res.json() : null;

### Next.js API Route (/app/api/reviews/route.js)
export async function GET() {
  const res = await fetch(
    `https://reviews.overunity.ca/api/reviews/${process.env.OVERUNITY_KEY}`
  );
  return Response.json(res.ok ? await res.json() : { reviews: [], stale: true });
}

### WordPress / PHP
$response = wp_remote_get(
  'https://reviews.overunity.ca/api/reviews/' . getenv('OVERUNITY_KEY')
);
$data = json_decode(wp_remote_retrieve_body($response), true);

### Node.js / Express
const res = await fetch(
  `https://reviews.overunity.ca/api/reviews/${process.env.OVERUNITY_KEY}`
);
const data = await res.json();

## HTTP Error Codes
  404 — Key not found (check OVERUNITY_KEY)
  503 — Service temporarily unavailable (show fallback UI)