Skip to main content

Overview

The PuckPerfect API provides access to comprehensive data about ice hockey in the UK, with initial focus on the Elite Ice Hockey League (EIHL). This guide explains the structure and organization of the data available through the API.

Base URL​

https://api.puckperfect.com/

Authentication​

All API requests require authentication using an API key. Include your API key in each request using the X-API-Key header:

X-API-Key: your_api_key_here

Core Resources​

The API is organized around the following core resources:

Teams​

Teams represent the clubs participating in the competitions.

GET /teams
GET /teams/{team_id}

Players​

Players represent athletes who are members of teams.

GET /players
GET /players/{player_id}

Staff​

Staff represent coaches, managers, and other team personnel.

GET /staff
GET /staff/{staff_id}

Officials​

Officials represent referees, linesmen, and other game officials.

GET /officials
GET /officials/{official_id}

Games​

Games represent matches between two teams.

GET /games
GET /games/{game_id}

Venues​

Venues represent arenas and facilities where games are played.

GET /venues
GET /venues/{venue_id}

Seasons​

Seasons represent time periods (typically annual) during which competitions are held.

GET /seasons
GET /seasons/{season_id}

Competitions​

Competitions represent tournaments or leagues, such as the EIHL League, Challenge Cup, or Playoffs.

GET /competitions
GET /competitions/{competition_id}

Standings​

Standings represent team rankings within competitions.

GET /standings
GET /standings/{standing_id}

Data Relationships​

The resources in the PuckPerfect API are interconnected in the following ways:

  • Teams participate in Competitions during Seasons
  • Players belong to Teams during specific Seasons
  • Staff are associated with Teams during specific Seasons
  • Games are played between two Teams at a Venue as part of a Competition in a Season
  • Officials officiate Games
  • Standings represent a Team's position in a Competition during a Season

Entity Relationship Diagram​

┌──────────┐     ┌────────────┐     ┌───────────┐
│  Seasons │─────┤Competitions├─────┤ Standings │
└────┬─────┘     └─────┬──────┘     └─────┬─────┘
     │                 │                  │
     │                 │                  │
     │             ┌───┴────┐             │
     └─────────────┤  Games ├─────────────┘
                   └───┬────┘
                       │
┌──────────┐       ┌───┴────┐       ┌─────────┐
│  Players │───────┤  Teams │───────┤  Staff  │
└──────────┘       └────────┘       └─────────┘
                        │
                   ┌────┴─────┐
                   │  Venues  │
                   └──────────┘
                        │
                   ┌────┴─────┐
                   │ Officials│
                   └──────────┘

Key Relationships​

  1. Teams and Players:

    • A player belongs to one team per season
    • A team has multiple players per season

  2. Games and Teams:

    • Each game has a home team and an away team
    • Teams play multiple games per season

  3. Standings Context:

    • A standing is uniquely identified by the combination of:
      • Team
      • Competition
      • Season
    • Multiple standings exist for each competition
    • A team can have standings in multiple competitions per season

Common Query Patterns​

Filtering by Season​

Most resources support filtering by season:

GET /teams?season_id=seas_123
GET /players?season_id=seas_123

Filtering by Team​

Many resources can be filtered by team:

GET /players?team_id=tea_456
GET /games?team_id=tea_456

Filtering Standings​

Standings can be filtered by various criteria:

Retrieving League Tables​

# Current season's EIHL league table
GET /standings?competition_id=comp_eihl_league&season_id=seas_current

# 2023/24 Challenge Cup standings
GET /standings?competition_id=comp_challenge_cup&season_id=seas_2023_24

# Full playoff standings from the current season
GET /standings?competition_id=comp_playoffs&season_id=seas_current

Team-Specific Standings​

# Cardiff Devils' standings across all competitions in the current season
GET /standings?team_id=tea_cardiff&season_id=seas_current

# Sheffield Steelers' historical performance in the EIHL League
GET /standings?team_id=tea_sheffield&competition_id=comp_eihl_league

# Nottingham Panthers' performance in the Challenge Cup over multiple seasons
GET /standings?team_id=tea_nottingham&competition_id=comp_challenge_cup

Combined Filters​

# Manchester Storm's position in the 2022/23 EIHL League
GET /standings?team_id=tea_manchester&competition_id=comp_eihl_league&season_id=seas_2022_23

# All Scottish teams' positions in the current season
GET /standings?team_id=tea_fife,tea_glasgow,tea_dundee&season_id=seas_current

# Historical performance of Belfast Giants and Cardiff Devils in the playoffs
GET /standings?team_id=tea_belfast,tea_cardiff&competition_id=comp_playoffs

Standings at a Specific Date​

# League table as it stood on January 15, 2025
GET /standings?competition_id=comp_eihl_league&season_id=seas_2024_25&date=2025-01-15

# Mid-season standings from last season
GET /standings?competition_id=comp_eihl_league&season_id=seas_2023_24&date=2024-01-01

Pagination​

List endpoints support pagination using the after and per_page parameters:

GET /players?per_page=25&after=player_100

Response Format​

All API responses follow a standard format:

{
  "data": [...],  // Resource data (array for lists, object for individual resources)
  "meta": {       // Metadata about the response
    "pagination": {  // Only for list endpoints
      "per_page": 25,
      "next": "https://api.puckperfect.com/v1/players?after=player_125"
    }
  }
}

Example Workflows​

Team Information​

Retrieving a Team's Current Roster​

GET /players?team_id=tea_cardiff&season_id=seas_current

Finding Team Staff​

GET /staff?team_id=tea_belfast&season_id=seas_current

Getting Team's Home Venue​

GET /venues?team_id=tea_sheffield

Game Information​

Finding Upcoming Games for a Team​

GET /games?team_id=tea_nottingham&status=scheduled

Finding Recent Results​

GET /games?team_id=tea_fife&status=completed&per_page=5

Finding Games at a Specific Venue​

GET /games?venue_id=ven_motorpoint&season_id=seas_current

Finding Games Officiated by a Specific Referee​

GET /games?official_id=off_123&season_id=seas_current

Player Information​

Finding a Player's Career History​

GET /players/play_123/teams

Getting Top Scorers​

GET /players?season_id=seas_current&sort=points&order=desc

Finding Players by Position​

GET /players?position=goalie&season_id=seas_current

Competition Information​

Getting Current League Standings​

GET /standings?competition_id=comp_eihl_league&season_id=seas_current

Getting Team Performance in Playoffs​

GET /standings?competition_id=comp_playoffs&season_id=seas_current&team_id=tea_cardiff

Comparing Two Teams​

GET /standings?competition_id=comp_eihl_league&season_id=seas_current&team_id=tea_belfast,tea_cardiff

Finding All Games in a Competition​

GET /games?competition_id=comp_challenge_cup&season_id=seas_current