Venues

Base path: /api/venues

Venue endpoints for browsing and searching futsal / sports venues. Most are public (no auth required).

Endpoints

GET /api/venues

List active venues with optional filters.

Auth: Not required for guests and customers (full public catalog of verified venues only). Authenticated venue_owner, manager, and staff are scoped to their own venues even if they send a Sanctum token (including unverified / pending). Super admins see the full catalog. owner_id is ignored unless the actor is a super admin.

Publishing rule: Venues with verification_status of unverified, pending, or rejected are hidden from the customer app until a super admin approves verification (is_verified: true).

Admin UI: venue owners/staff must use GET /api/venues/my-venues for the switcher and directory (includes inactive venues they can operate).

Query parameters:

Response 200:

{
  "data": [
    {
      "id": 1,
      "name": "Champions Futsal",
      "slug": "champions-futsal",
      "description": "Premium 5-a-side courts in Kathmandu.",
      "phone": "9801234567",
      "email": "info@champions.com",
      "address": "Thamel, Kathmandu",
      "city": "Kathmandu",
      "state": "Bagmati",
      "latitude": "27.71500000",
      "longitude": "85.31200000",
      "opening_time": "06:00:00",
      "closing_time": "22:00:00",
      "is_active": true,
      "is_verified": true,
      "distance": "2.41 km",
      "distance_km": 2.41,
      "currency": "NPR",
      "currency_symbol": "Rs",
      "images": [],
      "amenities": [],
      "courts_count": 3,
      "reviews_avg_rating": 4.5,
      "reviews_count": 28,
      "created_at": "2025-01-01 10:00:00"
    }
  ],
  "links": { ... },
  "meta": { ... }
}

GET /api/venues/my-venues

Venues the authenticated user can operate (owned or assigned). Includes inactive venues. Super admins receive every venue.

Auth: Required (auth:sanctum)

Response 200: Array of VenueResource (not paginated).

GET /api/venues/nearby

Find venues near a GPS coordinate.

Auth: Not required

Query parameters:

Response 200: Same as venue list. Each object includes "distance": "1.43 km".

GET /api/venues/{slug}

Get full details of a single venue including courts, images, and amenities.

Auth: Not required for guests and customers. Authenticated venue_owner, manager, and staff receive 403 if they do not own or are not assigned to the venue.

Path parameter: slug — the venue's URL-friendly identifier (e.g. champions-futsal)

Response 200:

{
  "data": {
    "id": 1,
    "name": "Champions Futsal",
    "slug": "champions-futsal",
    "description": "...",
    "phone": "9801234567",
    "email": "info@champions.com",
    "address": "Thamel, Kathmandu",
    "city": "Kathmandu",
    "state": "Bagmati",
    "latitude": "27.71500000",
    "longitude": "85.31200000",
    "opening_time": "06:00:00",
    "closing_time": "22:00:00",
    "is_active": true,
    "is_verified": true,
    "distance": null,
    "images": [
      { "id": 1, "url": "https://...", "is_primary": true }
    ],
    "amenities": [
      { "id": 1, "name": "Parking", "icon": "parking" }
    ],
    "courts": [
      {
        "id": 1,
        "name": "Court A",
        "type": "futsal",
        "description": "5-a-side turf court",
        "capacity": 10,
        "is_active": true
      }
    ],
    "courts_count": 1,
    "reviews_avg_rating": 4.5,
    "reviews_count": 28,
    "created_at": "2025-01-01 10:00:00"
  }
}

GET /api/venues/{venue}/reviews

Get all approved reviews for a venue.

Auth: Not required

Path: venue ID or slug

POST /api/venues/{venue}/reviews [Auth required]

Submit a review: { "rating": 5, "comment": "..." }

Response 200:

{
  "average_rating": 4.5,
  "reviews": [
    {
      "id": 3,
      "rating": 5,
      "comment": "Excellent courts!",
      "is_approved": true,
      "user": { "id": 12, "name": "John" },
      "images": [],
      "replies": [],
      "created_at": "2025-02-10 14:00:00"
    }
  ]
}

GET /api/venues/{venueId}/indoor-games

Public catalog of indoor games available at a venue.

Auth: Not required

Query parameters:

Response 200: Array of IndoorGameResource — see Indoor Games.

VenueResource — Field Reference

VenueImage fields

Create and update accept multipart fields thumbnail (single image) and gallery[] (up to 12 images). POST /api/venues/{venue}/images accepts image plus collection=thumbnail|gallery. DELETE /api/venues/{venue}/images/{id} removes a media item.

Venue verification flow

New venues start as verification_status: unverified (is_verified: false).

POST /api/venues/{venue}/verification/request [Auth: venue_owner]

Owner requests platform verification for a venue they own.

Body (optional): { "note": "We completed setup and added courts." }

Rules: Not allowed if already verified or pending.

GET /api/admin/venues/verification-requests [Auth: super_admin]

List venues with verification_status: pending.

POST /api/admin/venues/{venue}/verification/approve [Auth: super_admin]

Approve a pending request → verified / is_verified: true.

POST /api/admin/venues/{venue}/verification/reject [Auth: super_admin]

Reject a pending request → rejected / is_verified: false.

Body (optional): { "reason": "Missing photos / incomplete address." }

The owner can request again after rejection.