Reviews API

Retrieve a paginated list of reviews. Filter by lot, platform, rating, date range, and publication status.

QUERY PARAMETERS

curl -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/reviews?page=1&limit=10&platform=airbnb&minRating=4"

{
  "success": true,
  "reviews": [
    {
      "_id": "664f1a2b3c4d5e6f7a8b9c0d",
      "lotId": { "_id": "...", "name": "Suite 201", "lotNo": "A201", "lodgifyId": "499029" },
      "platform": "airbnb",
      "guestName": "John D.",
      "rating": 5,
      "comment": "Amazing stay! The view was incredible...",
      "reviewDate": "2025-03-15T00:00:00.000Z",
      "isPublished": true,
      "categories": { "cleanliness": 5, "communication": 5, "checkIn": 5, "accuracy": 4.5, "location": 5, "value": 4.5 },
      "createdAt": "2025-03-16T10:30:00.000Z"
    }
  ],
  "total": 245,
  "page": 1,
  "limit": 10,
  "totalPages": 25
}

Get aggregated statistics: total count, average rating, platform breakdown, rating distribution, and category averages.

{
  "success": true,
  "stats": {
    "totalReviews": 245,
    "publishedReviews": 230,
    "unpublishedReviews": 15,
    "averageRating": 4.6,
    "ratingDistribution": { "1": 2, "2": 3, "3": 10, "4": 45, "5": 185 },
    "platformBreakdown": [
      { "platform": "airbnb", "count": 120, "avgRating": 4.7 },
      { "platform": "vrbo", "count": 85, "avgRating": 4.5 }
    ],
    "categoryAverages": {
      "cleanliness": 4.8, "communication": 4.7, "checkIn": 4.6,
      "accuracy": 4.5, "location": 4.9, "value": 4.4
    }
  }
}

Get detailed review statistics for a specific lot: averages, platform breakdown, rating distribution, and category scores.

curl -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/reviews/stats/664f1a2b3c4d5e6f7a8b9c0d"

Retrieve the full details of a single review by its MongoDB ID.

curl -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/reviews/664f1a2b3c4d5e6f7a8b9c0d"

Toggle the isPublished flag on a review. If published, it will be unpublished and vice versa.

curl -X PATCH -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/reviews/664f1a2b3c4d5e6f7a8b9c0d/toggle-published"

{
  "success": true,
  "message": "Review deactivated",
  "review": { "_id": "...", "isPublished": false, ... }
}

Set isPublished for multiple reviews at once.

REQUEST BODY (JSON)

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"reviewIds": ["id1", "id2", "id3"], "isPublished": true}' \
  "https://listings.4u-realestate.org/reviews/bulk-toggle-published"

{
  "success": true,
  "message": "3 review(s) activated",
  "modifiedCount": 3
}

Automatically activates all 5★ reviews and deactivates all ≤3★ reviews. 4★ reviews are left untouched for manual validation.

curl -X POST -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/reviews/bulk-activate-high-rated"

{
  "success": true,
  "message": "12 5★ activated, 3 ≤3★ deactivated, 5 4★ pending",
  "activated": 12,
  "deactivated": 3,
  "pending4Stars": 5
}

Permanently removes a review from the database. This action cannot be undone.

curl -X DELETE -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/reviews/664f1a2b3c4d5e6f7a8b9c0d"

{ "success": true, "message": "Review deleted" }

Permanently removes multiple reviews. This action cannot be undone.

REQUEST BODY (JSON)

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"reviewIds": ["id1", "id2"]}' \
  "https://listings.4u-realestate.org/reviews/bulk-delete"

{ "success": true, "message": "2 review(s) deleted", "deletedCount": 2 }