API Reference

Complete reference documentation for all Squad Golf API endpoints with request/response examples and parameter details.

Base URL

https://api.squad.golf

All API requests should be made to this base URL. Append the endpoint path to form the complete URL.

Tournaments

Access comprehensive tournament data, leaderboards, and real-time updates

GET

List all tournaments

/api/v1/tournaments

Get a list of tournaments with optional status filtering

Parameters

statusstringFilter by tournament status (upcoming, active, completed)

Response Example

{
  "data": [
    {
      "_id": "t_abc123",
      "name": "The Masters Tournament",
      "status": "upcoming",
      "startDate": "2024-04-11T00:00:00Z",
      "endDate": "2024-04-14T23:59:59Z",
      "location": {
        "name": "Augusta National Golf Club",
        "city": "Augusta",
        "state": "Georgia",
        "country": "USA"
      },
      "playerCount": 87,
      "lastUpdated": "2024-04-10T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 47
  }
}

GET

Get tournament details

/api/v1/tournaments/{id}

Get comprehensive tournament data including leaderboard and field

Parameters

idstringrequiredTournament ID

Response Example

{
  "data": {
    "tournamentId": "t_abc123",
    "name": "The Masters Tournament",
    "status": "active",
    "currentRound": 2,
    "leaderboard": [
      {
        "position": 1,
        "player": {
          "_id": "p_player123",
          "fullName": "Tiger Woods",
          "country": "USA"
        },
        "score": -8,
        "total": 136,
        "rounds": [68, 68]
      }
    ],
    "field": [
      {
        "player": {
          "_id": "p_player123",
          "fullName": "Tiger Woods"
        },
        "status": "active",
        "currentRound": 2
      }
    ]
  }
}

GET

Get tournament leaderboard

/api/v1/tournaments/{id}/leaderboard

Get the current leaderboard for a specific tournament

Parameters

idstringrequiredTournament ID

limitnumberLimit number of players returned

Response Example

{
  "data": {
    "tournamentId": "t_abc123",
    "lastUpdated": "2024-04-12T15:30:00Z",
    "players": [
      {
        "position": 1,
        "player": {
          "_id": "p_player123",
          "fullName": "Tiger Woods"
        },
        "score": -8,
        "total": 136,
        "status": "playing"
      }
    ]
  }
}

GET

Search tournaments

/api/v1/tournaments/search

Search tournaments with advanced filtering options

Parameters

namestringTournament name search

statusstring[]Filter by status array

yearstringFilter by year

locationstringFilter by location

limitnumberLimit results

Response Example

{
  "data": [
    {
      "_id": "t_abc123",
      "name": "The Masters Tournament",
      "status": "upcoming",
      "startDate": "2024-04-11T00:00:00Z",
      "location": {
        "name": "Augusta National Golf Club",
        "city": "Augusta",
        "state": "Georgia"
      }
    }
  ]
}

Players

Player profiles, search functionality, and detailed statistics

GET

List all players

/api/v1/players

Get a list of players with optional filtering

Parameters

countrystringFilter by country

amateurbooleanFilter amateur players

owgrRankstringFilter by OWGR rank range

fedexRankstringFilter by FedEx Cup rank range

Response Example

{
  "data": [
    {
      "_id": "p_player123",
      "fullName": "Tiger Woods",
      "firstName": "Tiger",
      "lastName": "Woods",
      "country": "USA",
      "countryFlag": "🇺🇸",
      "currentRankings": {
        "owgr": {
          "rank": 15,
          "pointsTotal": 4.2583,
          "pointsAverage": 2.1291
        },
        "fedexCup": {
          "rank": 25,
          "points": 1250
        }
      }
    }
  ]
}

GET

Get player details

/api/v1/players/{id}

Get detailed information about a specific player

Parameters

idstringrequiredPlayer ID

Response Example

{
  "data": {
    "_id": "p_player123",
    "fullName": "Tiger Woods",
    "firstName": "Tiger",
    "lastName": "Woods",
    "country": "USA",
    "dateOfBirth": "1975-12-30",
    "turnedPro": "1996",
    "currentRankings": {
      "owgr": {
        "rank": 15,
        "pointsTotal": 4.2583,
        "movementDirection": "up",
        "movementAmount": 2
      }
    },
    "careerStats": {
      "pgatourWins": 82,
      "majorWins": 15,
      "fedexCupWins": 2
    }
  }
}

GET

Search players

/api/v1/players/search

Search for players by name and other criteria

Parameters

namestringPlayer name search

countryCodestringISO country code

countrystringCountry name

limitnumberLimit results (default: 10)

Response Example

{
  "data": [
    {
      "_id": "p_player123",
      "fullName": "Tiger Woods",
      "country": "USA",
      "matchScore": 0.95,
      "currentRankings": {
        "owgr": {
          "rank": 15
        }
      }
    }
  ]
}

GET

Get player statistics

/api/v1/players/{id}/stats

Get detailed statistics for a specific player

Parameters

idstringrequiredPlayer ID

seasonstringSeason year (default: current)

statCategorystringCategory: scoring, driving, putting, short_game, all

Response Example

{
  "data": {
    "playerId": "p_player123",
    "season": "2024",
    "scoring": {
      "averageScore": 69.8,
      "scoringAverage": 69.8,
      "roundsPlayed": 45
    },
    "driving": {
      "drivingDistance": 310.5,
      "drivingAccuracy": 68.2
    }
  }
}

Rankings

OWGR and FedEx Cup rankings with historical data and comparisons

GET

Get current rankings

/api/v1/players/rankings

Get current OWGR and FedEx Cup rankings

Parameters

sortBystringSort by owgr or fedex

limitnumberLimit results

Response Example

{
  "data": [
    {
      "player": {
        "_id": "p_player123",
        "fullName": "Scottie Scheffler"
      },
      "owgr": {
        "rank": 1,
        "pointsTotal": 15.2583,
        "pointsAverage": 7.6291
      },
      "fedexCup": {
        "rank": 1,
        "points": 4250
      }
    }
  ]
}

GET

Get OWGR rankings

/api/v1/players/rankings/owgr

Get Official World Golf Ranking data

Parameters

limitnumberLimit results (default: 50)

countrystringFilter by country

Response Example

{
  "data": {
    "lastUpdated": "2024-04-15T00:00:00Z",
    "rankings": [
      {
        "rank": 1,
        "player": {
          "_id": "p_player123",
          "fullName": "Scottie Scheffler"
        },
        "pointsTotal": 15.2583,
        "pointsAverage": 7.6291,
        "movementDirection": "same",
        "eventsPlayed": 12
      }
    ]
  }
}

Authentication

User management, API key operations, and usage statistics

POST

Register new user

/api/v1/auth/register

Create a new user account and generate API key

Parameters

emailstringrequiredUser email address

clerkUserIdstringClerk user ID for integration

Response Example

{
  "data": {
    "user": {
      "id": "user_abc123",
      "email": "user@example.com",
      "createdAt": "2024-04-15T10:00:00Z",
      "subscriptionTier": "free"
    },
    "apiKey": {
      "id": "key_def456",
      "name": "Default Key",
      "key": "sk_live_abc123...",
      "permissions": ["read"],
      "createdAt": "2024-04-15T10:00:00Z"
    }
  }
}

GET

Get usage statistics

/api/v1/auth/usage

Get current API usage statistics and limits

Response Example

{
  "data": {
    "currentPeriod": {
      "startDate": "2024-04-01T00:00:00Z",
      "endDate": "2024-04-30T23:59:59Z",
      "requestCount": 1250,
      "limit": 5000,
      "remainingRequests": 3750
    },
    "rateLimitInfo": {
      "tier": "pro",
      "requestsPerMinute": 100,
      "requestsPerHour": 1000,
      "requestsPerDay": 5000
    }
  }
}

POST

Generate API key

/api/v1/auth/keys

Generate a new API key for the authenticated user

Parameters

namestringrequiredKey name for identification

permissionsstring[]Key permissions (default: ["read"])

Response Example

{
  "data": {
    "id": "key_xyz789",
    "name": "Production Key",
    "key": "sk_live_xyz789...",
    "permissions": ["read", "write"],
    "createdAt": "2024-04-15T10:00:00Z",
    "isActive": true
  }
}

DELETE

Delete API key

/api/v1/auth/keys/{id}

Delete an API key and revoke access

Parameters

idstringrequiredAPI key ID to delete

Response Example

{
  "data": {
    "message": "API key deleted successfully",
    "deletedAt": "2024-04-15T10:30:00Z"
  }
}

Squads

Golf community management, member operations, and social features

GET

List user's squads

/api/squads

Get a list of squads where the authenticated user is a member

Parameters

limitnumberLimit number of squads returned (default: 20)

offsetnumberOffset for pagination (default: 0)

searchstringSearch squad names and descriptions

isPublicbooleanFilter by public/private squads

Response Example

{
  "squads": [
    {
      "id": "squad_abc123",
      "name": "Golf Legends",
      "description": "Professional golfers and enthusiasts",
      "isPublic": false,
      "inviteCode": "golfhero",
      "imageUrl": "https://example.com/squad-image.jpg",
      "createdAt": "2024-04-10T12:00:00Z",
      "updatedAt": "2024-04-15T10:30:00Z",
      "memberCount": 15,
      "notificationCount": 3,
      "poolShareCount": 8,
      "userRole": "ADMIN",
      "stats": {
        "totalPoolsCreated": 12,
        "totalPoolsJoined": 25,
        "totalTournaments": 8,
        "averagePosition": 3.2,
        "bestPosition": 1,
        "totalWins": 4,
        "totalTopThreeFinishes": 8,
        "activeMembers": 12,
        "lastActivityAt": "2024-04-15T09:15:00Z"
      },
      "settings": {
        "requireApproval": false,
        "maxMembers": 50,
        "allowMemberPoolSharing": true,
        "autoNotifyNewPools": true,
        "showMemberList": true,
        "showPerformanceStats": true
      }
    }
  ],
  "meta": {
    "limit": 20,
    "offset": 0,
    "total": 3,
    "hasMore": false
  }
}

POST

Create a new squad

/api/squads

Create a new golf squad with settings and automatically join as admin

Parameters

namestringrequiredSquad name (1-100 characters)

descriptionstringSquad description (max 500 characters)

isPublicbooleanWhether squad is publicly discoverable (default: false)

imageUrlstringSquad image URL

settingsobjectSquad configuration settings

Response Example

{
  "squad": {
    "id": "squad_xyz789",
    "name": "Weekend Warriors",
    "description": "Casual golfers who play on weekends",
    "isPublic": false,
    "inviteCode": "weekend",
    "imageUrl": null,
    "createdAt": "2024-04-15T14:00:00Z",
    "updatedAt": "2024-04-15T14:00:00Z"
  }
}

GET

Get squad details

/api/squads/{id}

Get detailed information about a specific squad

Parameters

idstringrequiredSquad ID

Response Example

{
  "squad": {
    "id": "squad_abc123",
    "name": "Golf Legends",
    "description": "Professional golfers and enthusiasts",
    "isPublic": false,
    "inviteCode": "golfhero",
    "imageUrl": "https://example.com/squad-image.jpg",
    "createdAt": "2024-04-10T12:00:00Z",
    "updatedAt": "2024-04-15T10:30:00Z",
    "memberCount": 15,
    "userRole": "ADMIN",
    "stats": {
      "totalPoolsCreated": 12,
      "totalPoolsJoined": 25,
      "averagePosition": 3.2,
      "bestPosition": 1,
      "totalWins": 4,
      "activeMembers": 12
    },
    "settings": {
      "requireApproval": false,
      "maxMembers": 50,
      "allowMemberPoolSharing": true,
      "autoNotifyNewPools": true,
      "showMemberList": true,
      "showPerformanceStats": true
    }
  }
}

GET

Get squad members

/api/squads/{id}/members

Get list of squad members with their roles and statistics

Parameters

idstringrequiredSquad ID

rolestringFilter by role (ADMIN, MODERATOR, MEMBER)

limitnumberLimit number of members returned

Response Example

{
  "members": [
    {
      "id": "member_123",
      "userId": "user_abc456",
      "role": "ADMIN",
      "joinedAt": "2024-04-10T12:00:00Z",
      "user": {
        "id": "user_abc456",
        "name": "Tiger Woods",
        "imageUrl": "https://example.com/avatar.jpg",
        "email": "tiger@example.com"
      },
      "stats": {
        "poolsCreated": 5,
        "poolsJoined": 12,
        "averagePosition": 2.1,
        "bestPosition": 1,
        "totalWins": 3
      }
    }
  ],
  "meta": {
    "total": 15,
    "limit": 20,
    "offset": 0
  }
}

GET

Get squad leaderboard

/api/squads/{id}/leaderboard

Get performance leaderboard for squad members

Parameters

idstringrequiredSquad ID

periodstringTime period (LAST_30_DAYS, LAST_6_MONTHS, ALL_TIME)

typestringLeaderboard type (WINS, AVERAGE_POSITION, TOTAL_EARNINGS)

Response Example

{
  "leaderboard": {
    "period": "LAST_30_DAYS",
    "type": "AVERAGE_POSITION",
    "lastUpdated": "2024-04-15T10:00:00Z",
    "entries": [
      {
        "rank": 1,
        "member": {
          "userId": "user_abc456",
          "name": "Tiger Woods",
          "imageUrl": "https://example.com/avatar.jpg"
        },
        "stats": {
          "averagePosition": 1.8,
          "poolsPlayed": 5,
          "wins": 2,
          "topThreeFinishes": 4
        },
        "change": {
          "direction": "up",
          "amount": 2
        }
      }
    ]
  }
}

GET

Get squad analytics

/api/squads/{id}/analytics

Get comprehensive analytics data for squad performance

Parameters

idstringrequiredSquad ID

periodstringAnalysis period (30d, 90d, 1y, all)

Response Example

{
  "analytics": {
    "period": {
      "type": "30d",
      "start": "2024-03-15T00:00:00Z",
      "end": "2024-04-15T23:59:59Z"
    },
    "performance": {
      "totalPools": 25,
      "averageScore": 285.4,
      "winRate": 0.16,
      "topThreeRate": 0.48,
      "memberParticipation": 0.85
    },
    "engagement": {
      "activeMembers": 12,
      "newMembers": 3,
      "poolShares": 18,
      "notifications": 45
    },
    "trends": {
      "scoreImprovement": -2.1,
      "participationChange": 0.05,
      "memberGrowth": 0.25
    }
  }
}

GET

Discover public squads

/api/squads/discover

Find public squads to join based on search criteria

Parameters

searchstringSearch squad names and descriptions

categorystringSquad category filter

limitnumberLimit results (default: 20)

Response Example

{
  "squads": [
    {
      "id": "squad_public123",
      "name": "Public Golf Community",
      "description": "Open community for all golf enthusiasts",
      "memberCount": 45,
      "isJoinable": true,
      "stats": {
        "averagePosition": 3.8,
        "totalTournaments": 15,
        "activeMembers": 32
      },
      "preview": {
        "recentActivity": "2024-04-15T08:30:00Z",
        "topPerformers": ["user1", "user2", "user3"]
      }
    }
  ]
}

POST

Join squad by invite code

/api/squads/join

Join a squad using its invite code

Parameters

inviteCodestringrequiredSquad invite code

Response Example

{
  "success": true,
  "squad": {
    "id": "squad_abc123",
    "name": "Golf Legends",
    "userRole": "MEMBER",
    "joinedAt": "2024-04-15T14:30:00Z"
  },
  "message": "Successfully joined Golf Legends"
}

WebSocket Real-time UpdatesFront Nine+

Subscribe to real-time tournament updates via WebSocket connections

WebSocket URL

wss://api.squad.golf

Available Subscriptions

Tournament Leaderboard Updates

Subscribe to real-time leaderboard changes during active tournaments

leaderboard:{tournamentId}

javascript

import { SquadGolfClient } from '@squad-golf/api-client';

const client = new SquadGolfClient({
  apiKey: 'your-api-key',
  enableWebSocket: true
});

// Subscribe to tournament leaderboard updates
const unsubscribe = client.tournaments.subscribeToLeaderboard(
  't_masters2024',
  (update) => {
    console.log('Leaderboard update:', update);
    // Update your UI with new leaderboard data
    updateLeaderboardUI(update.leaderboard.players);
  },
  {
    onError: (error) => console.error('WebSocket error:', error),
    onReconnect: () => console.log('WebSocket reconnected'),
    onDisconnect: () => console.log('WebSocket disconnected')
  }
);

// Clean up subscription when done
// unsubscribe();

Error Handling

All API responses follow consistent error formats

Error Response Format

{
  "error": {
    "code": "TOURNAMENT_NOT_FOUND",
    "message": "Tournament not found",
    "details": "No tournament found with ID: t_invalid123",
    "timestamp": "2024-04-15T10:00:00Z",
    "requestId": "req_abc123"
  }
}

Common HTTP Status Codes

200Success

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

500Server Error

SDKs and Libraries

Official and community-maintained libraries for easy integration

Official

TypeScript/JavaScript Client

Full-featured client with caching, WebSocket support, and React hooks

npm install @squad-golf/api-client

GitHub Docs

Community

Python SDK

Community-maintained Python wrapper (coming soon)

pip install squadgolf-python

Ready to Get Started?

Everything you need to integrate the Squad Golf API

Quick Start GuideGet started in minutes AuthenticationAPI keys and security Code ExamplesReal-world use cases