Bulk Matchups

​

Overview

​

Authentication

​

Request

​

Response

​

Error Responses

​

Possible Errors

• 401 Unauthorized - User not authenticated or session expired
  {"error": "User not authenticated or session expired."}
  
• 400 Bad Request - No league selected
  {"error": "No league selected. Please select a league first."}
  
• Yahoo API Errors - Passes through Yahoo’s error messages with status code
  {
    "error": "Yahoo error description",
    "yahoo_status_code": 404
  }
  
• 500 Internal Server Error - Unexpected error
  {"error": "Error details"}
  

​

Example Requests

curl -X GET "https://your-domain.com/api/bulk_matchups?weeks=1-5" \
  -H "Cookie: session=your-session-cookie"

​

Example Response

{
  "fantasy_content": {
    "league": [
      {
        "league_key": "423.l.12345",
        "name": "My League",
        "season": "2024"
      },
      {
        "teams": {
          "count": 10,
          "0": {
            "team": [
              [
                {
                  "team_key": "423.l.12345.t.1",
                  "name": "Thunder Squad"
                }
              ],
              {
                "matchups": {
                  "count": 5,
                  "0": {
                    "matchup": {
                      "week": "1",
                      "teams": {
                        "0": {"team": [{"team_key": "423.l.12345.t.1"}]},
                        "1": {"team": [{"team_key": "423.l.12345.t.2"}]}
                      }
                    }
                  }
                }
              }
            ]
          }
        }
      }
    ]
  }
}

​

Implementation Details

1. Validates user authentication (checks for active session token)
2. Validates league selection (checks for league_key in session)
3. Retrieves the weeks parameter from query string (defaults to "1-5")
4. Constructs the Yahoo API path: fantasy/v2/league/{league_key}/teams;out=matchups;weeks={weeks}
5. Calls the Yahoo Fantasy API via the yahoo_api() helper function
6. Returns the complete Yahoo API response as JSON
7. Handles errors with detailed logging and appropriate HTTP status codes

​

Error Handling

• HTTP errors from Yahoo: Extracts error description from Yahoo’s JSON response when available
• Network errors: Returns 500 with exception details
• Logging: All requests and errors are logged with request parameters for debugging

​

Yahoo API Format

• Range syntax: weeks=1-5 fetches weeks 1, 2, 3, 4, 5
• List syntax: weeks=13,14,15 fetches only weeks 13, 14, 15
• Mixed syntax: While not tested, Yahoo may support weeks=1-3,5,7-9

​

Use Cases

• Build complete season matchup calendars
• Display remaining schedule for each team
• Analyze strength of schedule (who plays who when)
• Identify playoff matchup opponents in advance
• Calculate potential tiebreaker scenarios
• Show head-to-head records between specific teams
• Plan roster moves based on upcoming opponent strength

​

Performance Considerations

• This endpoint fetches data for all teams in the league for the specified weeks
• Requesting many weeks (e.g., 1-24) returns significantly more data than a single week
• Consider requesting only the weeks you need to minimize response size
• Yahoo API rate limits apply; avoid excessive requests
• Response parsing may take longer for large week ranges in large leagues

​

Notes

• Week numbers must be valid for the current season (typically 1-24 for NBA fantasy)
• Invalid week numbers may cause Yahoo API errors
• Playoff weeks are included in the range if specified
• Bye weeks (if any) will show no matchup or special matchup status
• The response structure is complex due to Yahoo’s nested array/object format

​

Related Endpoints

• Scoreboard - Get detailed results for a single week’s matchups
• Season Averages - Compare team performance across the season