GET /api/v1/gyms

Retrieves a list of gyms, with support for filtering by location, owner, major, and more. Results can be sorted by proximity, marketing boosts, or recency.

No authentication required.

Permissions

Query Parameters

Results are sorted by marketing boosts first, then by proximity (if lat/lng provided), otherwise by newest.

If you specify location parameters, pagination is removed and all results within the radius are returned in one page.

Response

200 OK

Returns a paginated list of gym resources.

Schema

{
  "data": [
    { /* Gym Resource */ }
  ],
  "links": { /* Pagination Data */ },
  "meta": { /* Pagination Data */ }
}

Example

{
  "data": [
    {
      "id": 123,
      "name": "Iron Paradise",
      "address": "123 Main St",
      "location_lat": 35.6892,
      "location_lng": 51.3890,
      "is_active": true,
      "description": "A premium gym with modern equipment.",
      "created_at": "2023-01-01 10:00:00",
      "updated_at": "2023-01-01 10:00:00",
      "show_crowd": false,
      "crowd": null,
      "city": {
        "id": 5,
        "name": "Tehran",
        "state": {
          "id": 1,
          "name": "Tehran Province"
        }
      },
      "majors": [
        { "id": 1, "title": "Bodybuilding" },
        { "id": 2, "title": "Crossfit" }
      ],
      "working_periods": [],
      "working_status": null,
      "boost": null,
      "media": [],
      "rating_count": 0,
      "rating_average": 0
    }
  ],
  "links": {
    "first": "https://api.example.com/api/v1/gyms?page=1",
    "last": "https://api.example.com/api/v1/gyms?page=10",
    "prev": null,
    "next": "https://api.example.com/api/v1/gyms?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "path": "https://api.example.com/api/v1/gyms",
    "per_page": 30,
    "to": 30,
    "total": 300
  }
}

For a full schema, see Gym Resource and Pagination Data.

Error Responses