API Documentation

Access DotaData programmatically with our REST API

Overview

Base URL

https://dotadata.org/api

Response Format

JSON

GET

/leagues/{leagueId}

Get league information and statistics

Parameters

leagueId - League ID (integer)

Example Request

GET https://dotadata.org/api/leagues/12345

Example Response

{
  "success": true,
  "data": {
    "league_id": 12345,
    "name": "The International 2024",
    "slug": "ti2024",
    "start_date": "2024-10-01",
    "end_date": "2024-10-15",
    "statistics": {
      "total_matches": 150,
      "first_match": "2024-10-01 10:00:00",
      "last_match": "2024-10-15 22:30:00",
      "avg_duration_minutes": 42.5
    }
  }
}

GET

/leagues/{leagueId}/matches

Get matches for a league with full match data

Parameters

leagueId - League ID (integer)
limit - Number of matches (1-1000, default: 100)
offset - Skip matches (default: 0)
order_by - Sort field: match_id, start_time, duration
order_direction - Sort direction: asc, desc

Example Request

GET https://dotadata.org/api/leagues/12345/matches?limit=50&order_by=start_time

Example Response

{
  "success": true,
  "data": {
    "league_id": 12345,
    "league_name": "The International 2024",
    "matches": [
      {
        "match_id": 7234567890,
        "start_time": "2024-10-01 10:00:00",
        "duration": 2520,
        "radiant_win": true,
        "radiant_score": 25,
        "dire_score": 18,
        "radiant_team_id": 1001,
        "dire_team_id": 1002
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 50,
      "offset": 0,
      "has_more": true,
      "next_offset": 50
    }
  }
}

GET

/leagues/{leagueId}/match-ids

Get match IDs only for a league (lightweight endpoint)

Parameters

leagueId - League ID (integer)
all - Get ALL match IDs (true/false, default: false)
limit - Number of IDs (1-5000, default: 1000) - ignored if all=true
offset - Skip IDs (default: 0) - ignored if all=true

Example Requests

Get ALL match IDs:

GET https://dotadata.org/api/leagues/12345/match-ids?all=true

Get paginated match IDs:

GET https://dotadata.org/api/leagues/12345/match-ids?limit=1000&offset=0

Example Responses

Response with all=true (ALL match IDs):

{
  "success": true,
  "data": {
    "league_id": 12345,
    "league_name": "The International 2024",
    "match_ids": [
      7234567890,
      7234567889,
      7234567888,
      // ... all match IDs
    ],
    "total_returned": 150,
    "all_matches": true
  }
}

Response with pagination:

{
  "success": true,
  "data": {
    "league_id": 12345,
    "league_name": "The International 2024",
    "match_ids": [
      7234567890,
      7234567889,
      7234567888
    ],
    "pagination": {
      "total": 150,
      "limit": 1000,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    }
  }
}

POST

/matches/by-ids

Get match data by specific match IDs (up to 100 IDs per request)

Request Body

match_ids - Array of match IDs (1-100 integers)

Example Request

POST https://dotadata.org/api/matches/by-ids

Content-Type: application/json

{
  "match_ids": [
    7234567890,
    7234567889,
    7234567888
  ]
}

Example Response

{
  "success": true,
  "data": {
    "requested_ids": [7234567890, 7234567889, 7234567888],
    "found_matches": 2,
    "missing_ids": [7234567888],
    "matches": [
      {
        "match_id": 7234567890,
        "start_time": "2024-10-01 10:00:00",
        "duration": 2520,
        "radiant_win": true,
        "radiant_score": 25,
        "dire_score": 18,
        "radiant_team_id": 1001,
        "dire_team_id": 1002,
        "league_id": 12345,
        "league_name": "The International 2024",
        "patch_id": 150
      }
    ]
  }
}

Error Responses

404 - League Not Found

{
  "success": false,
  "message": "League not found",
  "error_code": "LEAGUE_NOT_FOUND"
}

422 - Validation Error

{
  "success": false,
  "message": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "errors": {
    "match_ids": ["The match ids field is required."]
  }
}

500 - Internal Server Error

{
  "success": false,
  "message": "Internal server error",
  "error_code": "INTERNAL_ERROR"
}

Rate Limiting

API requests are currently unlimited, but we recommend implementing reasonable request intervals to ensure optimal performance. Future versions may include rate limiting.