Prerequisites

Before you begin, make sure you have:

• A MatchGraph account (sign up at matchgraph.io)
• An API key from your dashboard
• Basic knowledge of HTTP requests and JSON

Step 1: Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

Step 2: Your First Request

Let's start with a simple request to get player statistics:

curl -X GET "https://api.matchgraph.io/v1/players/9/stats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

This request will return player statistics for player ID 9. The response will include performance metrics, match data, and more.

Step 3: Natural Language Query

For a more intuitive approach, try our Natural Language API:

{
  "query": "Show me all goals and assists by player 9 in the last 5 matches",
  "format": "json"
}

Send this to the Natural Language endpoint:

curl -X POST "https://api.matchgraph.io/v1/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Show me all goals and assists by player 9 in the last 5 matches",
    "format": "json"
  }'

Step 4: GraphQL Query

For more complex queries, use our GraphQL API:

query PlayerPerformance {
  playerStats(playerId: "9", matchCount: 5) {
    matchesAnalyzed
    performanceMetrics {
      shooting {
        totalShots
        onTarget
        accuracy
        goals
        xG
      }
      passing {
        totalPasses
        completed
        completionRate
        throughBalls {
          attempted
          successful
          successRate
        }
      }
      physical {
        distanceCovered
        averageSpeed
        maxSpeed
        sprints
      }
    }
    teamComparison {
      shotAccuracy
      passCompletion
      distanceCovered
    }
  }
}

Send this to the GraphQL endpoint:

curl -X POST "https://api.matchgraph.io/v1/graphql" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query PlayerPerformance { playerStats(playerId: \"9\", matchCount: 5) { matchesAnalyzed performanceMetrics { shooting { totalShots accuracy goals xG } passing { completionRate throughBalls { successRate } } } } }"
  }'

Next Steps

Now that you've made your first API calls, explore these resources:

API Keys

MatchGraph uses API key authentication for all requests. You can generate API keys from your dashboard.

Using API Keys

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY_HERE

Example Request

curl -X GET "https://api.matchgraph.io/v1/players/9/stats" \
  -H "Authorization: Bearer mg_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Key Management

Manage your API keys from the MatchGraph dashboard:

Error Responses

Authentication errors will return specific HTTP status codes:

Overview

MatchGraph API implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits are applied per API key and vary based on your subscription plan.

Rate Limit Tiers

Different subscription plans have different rate limits:

Rate Limit Headers

Every API response includes headers that provide information about your current rate limit status:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 60

Rate Limit Errors

When you exceed your rate limit, the API returns a 429 Too Many Requests error:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retry_after": 45,
    "limit": 300,
    "remaining": 0,
    "reset": 1640995200
  }
}

Handling Rate Limits

Here are best practices for handling rate limits in your applications:

async function makeRequestWithBackoff(url, maxRetries = 3) {
    let delay = 1000; // Start with 1 second
    
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            const response = await fetch(url);
            
            if (response.status === 429) {
                const retryAfter = response.headers.get('Retry-After') || delay / 1000;
                console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
                await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
                delay *= 2; // Exponential backoff
                continue;
            }
            
            return response;
        } catch (error) {
            if (attempt === maxRetries - 1) throw error;
            await new Promise(resolve => setTimeout(resolve, delay));
            delay *= 2;
        }
    }
}

class RateLimitedQueue {
    constructor(requestsPerSecond = 5) {
        this.queue = [];
        this.processing = false;
        this.interval = 1000 / requestsPerSecond;
    }
    
    async add(requestFn) {
        return new Promise((resolve, reject) => {
            this.queue.push({ requestFn, resolve, reject });
            this.process();
        });
    }
    
    async process() {
        if (this.processing || this.queue.length === 0) return;
        
        this.processing = true;
        
        while (this.queue.length > 0) {
            const { requestFn, resolve, reject } = this.queue.shift();
            
            try {
                const result = await requestFn();
                resolve(result);
            } catch (error) {
                reject(error);
            }
            
            // Wait before processing next request
            await new Promise(resolve => setTimeout(resolve, this.interval));
        }
        
        this.processing = false;
    }
}

function checkRateLimit(response) {
    const limit = parseInt(response.headers.get('X-RateLimit-Limit'));
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const usagePercentage = ((limit - remaining) / limit) * 100;
    
    if (usagePercentage > 80) {
        console.warn(`High API usage: ${usagePercentage.toFixed(1)}%`);
        // Send alert to your monitoring system
    }
    
    return { limit, remaining, usagePercentage };
}

Best Practices

Rate Limit by Endpoint

Different endpoints may have different rate limits based on their resource intensity:

Upgrading Your Plan

If you're consistently hitting rate limits, consider upgrading your plan:

Overview

The Natural Language API allows you to query MatchGraph data using everyday language. Simply describe what you want to know, and our AI will translate your request into the appropriate API calls.

Basic Usage

Send your query to the Natural Language endpoint:

curl -X POST "https://api.matchgraph.io/v1/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Show me all goals by player 9 in the last 5 matches",
    "format": "json"
  }'

Query Examples

Here are some examples of what you can ask:

Query Parameters

You can customize your natural language queries with additional parameters:

Response Format

Natural Language API responses include the interpreted query and results:

{
  "query": {
    "original": "Show me all goals by player 9 in the last 5 matches",
    "interpreted": {
      "type": "player_events",
      "player_id": 9,
      "event_types": ["goal"],
      "match_count": 5,
      "time_range": "recent"
    },
    "confidence": 0.95
  },
  "results": {
    "events": [
      {
        "match_id": "m123",
        "timestamp": "2024-03-15T15:23:12",
        "type": "goal",
        "player_id": 9,
        "position": [32, 45],
        "details": {
          "assist_by": 11,
          "shot_type": "right_foot",
          "xG": 0.76
        }
      }
    ],
    "summary": {
      "total_events": 3,
      "matches_analyzed": 5,
      "time_period": "last_5_matches"
    }
  },
  "metadata": {
    "processing_time": 0.45,
    "api_calls_made": 2,
    "cache_hit": false
  }
}

Supported Query Types

The Natural Language API understands various types of football queries:

Advanced Features

{
  "query": "player 9 goals",
  "suggestions": [
    "Show me all goals by player 9 in the last 5 matches",
    "What is the goal scoring rate for player 9 this season?",
    "Compare goal scoring between player 9 and player 11"
  ]
}

{
  "query": "Muéstrame todos los goles del jugador 9 en los últimos 5 partidos",
  "language": "es"
}

{
  "query": "Generate a video clip of the penalty kick at 67:30 in match m127",
  "format": "json"
}

Best Practices

Error Handling

Common errors and how to handle them:

{
  "error": {
    "code": "LOW_CONFIDENCE",
    "message": "Query interpretation confidence is low (0.3). Please rephrase your query.",
    "suggestions": [
      "Show me all goals by player 9",
      "What are the statistics for player 9?",
      "Get player 9's performance data"
    ]
  }
}

{
  "error": {
    "code": "AMBIGUOUS_QUERY",
    "message": "Multiple interpretations possible. Please specify:",
    "clarifications": [
      "Which player do you mean? (player 9, player 19, etc.)",
      "Which match are you referring to?",
      "What time period do you want to analyze?"
    ]
  }
}

Rate Limits

Natural Language queries have different rate limits due to their computational complexity:

Next Steps

Ready to start using the Natural Language API?

Overview

MatchGraph's GraphQL API provides a flexible, strongly-typed interface for querying football data. With GraphQL, you can request exactly the data you need, nothing more and nothing less.

Basic Usage

Send GraphQL queries to the GraphQL endpoint:

curl -X POST "https://api.matchgraph.io/v1/graphql" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query PlayerStats { playerStats(playerId: \"9\") { matchesAnalyzed performanceMetrics { shooting { goals accuracy } } } }"
  }'

Schema Overview

The GraphQL schema is organized around these main types:

Query Examples

Here are practical examples of common GraphQL queries:

query PlayerPerformance($playerId: ID!, $matchCount: Int) {
  playerStats(playerId: $playerId, matchCount: $matchCount) {
    matchesAnalyzed
    performanceMetrics {
      shooting {
        totalShots
        onTarget
        accuracy
        goals
        xG
      }
      passing {
        totalPasses
        completed
        completionRate
        throughBalls {
          attempted
          successful
          successRate
        }
      }
      physical {
        distanceCovered
        averageSpeed
        maxSpeed
        sprints
      }
    }
    teamComparison {
      shotAccuracy
      passCompletion
      distanceCovered
    }
  }
}

query TeamAnalysis($teamId: ID!, $matchCount: Int) {
  teamStats(teamId: $teamId, matchCount: $matchCount) {
    matchesAnalyzed
    overallMetrics {
      distanceRun {
        total
        averagePerMatch
        trend
      }
      intensity {
        acceleration {
          highIntensityCount
          averagePerMatch
        }
        deceleration {
          highIntensityCount
          averagePerMatch
        }
      }
      possession {
        averagePercentage
        ownHalf
        oppositionHalf
      }
    }
    matchBreakdown {
      matchId
      date
      metrics {
        distanceRun
        possessionPercentage
        highIntensityActions {
          total
          acceleration
          deceleration
        }
      }
    }
  }
}

query MatchEvents(
  $playerId: ID, 
  $matchIds: [ID!], 
  $eventType: [EventType!],
  $limit: Int
) {
  events(
    playerId: $playerId
    matchIds: $matchIds
    eventType: $eventType
    limit: $limit
  ) {
    matchId
    timestamp
    type
    playerId
    position
    details {
      assistBy
      shotType
      xG
      passType
      xA
    }
  }
}

query FrameAnalysis(
  $matchId: ID!, 
  $eventId: ID, 
  $timestamp: String, 
  $duration: Float
) {
  frameData(
    matchId: $matchId
    eventId: $eventId
    timestamp: $timestamp
    duration: $duration
  ) {
    eventDetails {
      eventType
      scorer
      assistBy
      period
    }
    frames {
      frameId
      timestamp
      ball {
        x
        y
        z
        velocity
      }
      players {
        teamA {
          playerId
          x
          y
          z
          orientation
          velocity
          acceleration
        }
        teamB {
          playerId
          x
          y
          z
          orientation
          velocity
          acceleration
        }
      }
      officials {
        role
        x
        y
        z
        orientation
      }
    }
    metadata {
      totalFrames
      frameRate
      durationSeconds
      calibrationConfidence
      trackingConfidence {
        players
        ball
        officials
      }
    }
  }
}

Mutations

GraphQL mutations allow you to modify data or trigger actions:

mutation ExportVideo($input: VideoExportInput!) {
  exportVideo(input: $input) {
    exportId
    status
    progress
    estimatedCompletion
    downloadUrl
    metadata {
      duration
      resolution
      format
      size
    }
  }
}

{
  "input": {
    "matchId": "m127",
    "eventId": "e456",
    "duration": 10.0,
    "format": "mp4",
    "resolution": "1080p",
    "annotations": {
      "showPlayerNames": true,
      "showTrajectories": true,
      "highlightEvent": true
    }
  }
}

mutation CreateWebhook($input: WebhookInput!) {
  createWebhook(input: $input) {
    webhookId
    url
    events
    status
    createdAt
    lastTriggered
  }
}

Subscriptions

Real-time data streaming with GraphQL subscriptions:

subscription LiveMatch($matchId: ID!) {
  liveMatch(matchId: $matchId) {
    matchId
    timestamp
    period
    score {
      home
      away
    }
    events {
      type
      playerId
      timestamp
      position
    }
    metrics {
      possession {
        home
        away
      }
      shots {
        home
        away
      }
      distance {
        home
        away
      }
    }
  }
}

subscription PlayerEvents($playerId: ID!, $eventTypes: [EventType!]) {
  playerEvents(playerId: $playerId, eventTypes: $eventTypes) {
    eventId
    matchId
    timestamp
    type
    position
    details {
      assistBy
      shotType
      xG
      passType
      xA
    }
    context {
      matchTime
      period
      score
    }
  }
}

Schema Types

Key GraphQL types and their fields:

type PlayerStats {
  playerId: ID!
  matchesAnalyzed: Int!
  performanceMetrics: PerformanceMetrics!
  teamComparison: TeamComparison!
  trends: TrendAnalysis!
}

type PerformanceMetrics {
  shooting: ShootingMetrics!
  passing: PassingMetrics!
  physical: PhysicalMetrics!
  defensive: DefensiveMetrics!
}

type ShootingMetrics {
  totalShots: Int!
  onTarget: Int!
  accuracy: Float!
  goals: Int!
  xG: Float!
  shotTypes: [ShotType!]!
}

type PassingMetrics {
  totalPasses: Int!
  completed: Int!
  completionRate: Float!
  throughBalls: ThroughBallMetrics!
  keyPasses: Int!
  assists: Int!
  xA: Float!
}

type Event {
  eventId: ID!
  matchId: ID!
  timestamp: String!
  type: EventType!
  playerId: ID
  position: Position!
  details: EventDetails!
  context: EventContext!
}

type Position {
  x: Float!
  y: Float!
  z: Float
}

type EventDetails {
  assistBy: ID
  shotType: ShotType
  xG: Float
  passType: PassType
  xA: Float
  tackleType: TackleType
  foulType: FoulType
}

enum EventType {
  GOAL
  ASSIST
  SHOT
  PASS
  TACKLE
  INTERCEPTION
  FOUL
  SPRINT
  SUBSTITUTION
}

Best Practices

Error Handling

GraphQL provides structured error handling:

{
  "data": {
    "playerStats": null
  },
  "errors": [
    {
      "message": "Player not found",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["playerStats"],
      "extensions": {
        "code": "PLAYER_NOT_FOUND",
        "playerId": "999"
      }
    }
  ]
}

Rate Limits

GraphQL queries have the same rate limits as other API endpoints, but with additional complexity limits:

Next Steps

Ready to explore the GraphQL API?

Overview

The MatchGraph REST API provides a familiar HTTP-based interface for accessing football data. All endpoints return JSON responses and follow RESTful conventions.

Authentication

All REST API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Endpoints Overview

The REST API is organized into the following resource categories:

Player Endpoints

Access player statistics, profiles, and performance data:

curl -X GET "https://api.matchgraph.io/v1/players/9/stats?matchCount=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "player_id": "9",
  "matches_analyzed": 10,
  "performance_metrics": {
    "shooting": {
      "total_shots": 25,
      "on_target": 15,
      "accuracy": 60.0,
      "goals": 8,
      "xG": 6.2
    },
    "passing": {
      "total_passes": 450,
      "completed": 380,
      "completion_rate": 84.4,
      "through_balls": {
        "attempted": 18,
        "successful": 12,
        "success_rate": 66.7
      }
    },
    "physical": {
      "distance_covered": 95.2,
      "average_speed": 7.8,
      "max_speed": 32.5,
      "sprints": 45
    }
  },
  "team_comparison": {
    "shot_accuracy": "+12.5%",
    "pass_completion": "+5.3%",
    "distance_covered": "+8.2%"
  }
}

curl -X GET "https://api.matchgraph.io/v1/players/9/profile" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "player_id": "9",
  "name": "Player 9",
  "position": "Forward",
  "key_attributes": {
    "speed": {
      "rating": 85,
      "trend": "+3",
      "details": {
        "sprint_speed": 32.5,
        "acceleration": 88
      }
    },
    "technical": {
      "rating": 79,
      "trend": "+2",
      "details": {
        "ball_control": 76,
        "passing": 81
      }
    }
  },
  "scout_notes": {
    "strengths": ["Explosive acceleration", "Excellent finishing", "Good vision"],
    "areas_for_improvement": ["Defensive positioning", "Aerial duels"]
  }
}

Team Endpoints

Access team statistics and performance data:

curl -X GET "https://api.matchgraph.io/v1/teams/team_a/stats?matchCount=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "team_id": "team_a",
  "matches_analyzed": 10,
  "overall_metrics": {
    "distance_run": {
      "total": 1052.3,
      "average_per_match": 105.23,
      "trend": "+3.2%"
    },
    "intensity": {
      "acceleration": {
        "high_intensity_count": 490,
        "average_per_match": 49
      },
      "deceleration": {
        "high_intensity_count": 396,
        "average_per_match": 39.6
      }
    },
    "possession": {
      "average_percentage": 58.4,
      "own_half": 35.2,
      "opposition_half": 64.8
    }
  },
  "match_breakdown": [
    {
      "match_id": "m127",
      "date": "2024-03-20",
      "metrics": {
        "distance_run": 107.2,
        "possession_percentage": 62.5,
        "high_intensity_actions": {
          "total": 52,
          "acceleration": 31,
          "deceleration": 21
        }
      }
    }
  ]
}

Match Endpoints

Access match data, events, and real-time position information:

curl -X GET "https://api.matchgraph.io/v1/matches/m127/events?eventType=GOAL&playerId=9" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "match_id": "m127",
  "events": [
    {
      "event_id": "e456",
      "timestamp": "2024-03-20T15:23:12",
      "type": "GOAL",
      "player_id": "9",
      "position": {
        "x": 32.5,
        "y": 45.2
      },
      "details": {
        "assist_by": "11",
        "shot_type": "right_foot",
        "xG": 0.76
      },
      "context": {
        "match_time": "23:15",
        "period": 1,
        "score": {
          "home": 1,
          "away": 0
        }
      }
    }
  ],
  "total_events": 1,
  "filters_applied": {
    "eventType": "GOAL",
    "playerId": "9"
  }
}

curl -X GET "https://api.matchgraph.io/v1/matches/m127/frames?eventId=e456&duration=15.0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Event Endpoints

Query and filter events across multiple matches:

curl -X GET "https://api.matchgraph.io/v1/events?playerId=9&eventType=GOAL,ASSIST&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "events": [
    {
      "event_id": "e456",
      "match_id": "m127",
      "timestamp": "2024-03-20T15:23:12",
      "type": "GOAL",
      "player_id": "9",
      "position": {
        "x": 32.5,
        "y": 45.2
      },
      "details": {
        "assist_by": "11",
        "shot_type": "right_foot",
        "xG": 0.76
      }
    },
    {
      "event_id": "e457",
      "match_id": "m125",
      "timestamp": "2024-03-18T14:15:30",
      "type": "ASSIST",
      "player_id": "9",
      "position": {
        "x": 28.1,
        "y": 40.3
      },
      "details": {
        "scored_by": "7",
        "pass_type": "through_ball",
        "xA": 0.45
      }
    }
  ],
  "total_events": 2,
  "filters_applied": {
    "playerId": "9",
    "eventType": "GOAL,ASSIST"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

Error Handling

REST API errors follow standard HTTP status codes and include detailed error information:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid matchCount parameter. Must be between 1 and 50.",
    "parameter": "matchCount",
    "value": "100"
  }
}

{
  "error": {
    "code": "PLAYER_NOT_FOUND",
    "message": "Player with ID '999' not found.",
    "player_id": "999"
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retry_after": 45,
    "limit": 300,
    "remaining": 0,
    "reset": 1640995200
  }
}

Rate Limits

REST API endpoints follow the same rate limiting as other API interfaces:

Best Practices

Next Steps

Ready to start using the REST API?

Event Types

Content coming soon...

Player Attributes

Content coming soon...

Team Statistics

Content coming soon...

Match Information

Content coming soon...

Frame Structure

Content coming soon...

Common Queries

Content coming soon...

Video Generation

Content coming soon...

Webhook Setup

Content coming soon...

Available SDKs

Content coming soon...

Error Codes

Content coming soon...

API Best Practices

Content coming soon...

Common Issues

Content coming soon...