Search API

The search module provides a unified interface to search VLR.gg for players, teams, events, and series.

Overview

The search module is the easiest way to find anything on VLR.gg. By default it searches across all entity types and enriches results with additional data like country information. Pass enrich=False to vlr.search.search if you want the fastest raw results with no additional network calls.

Search-related API endpoints and models.

class vlrdevapi.search.SearchPlayerResult(player_id: int, url: str, ign: str | None = None, real_name: str | None = None, country: str | None = None, image_url: str | None = None, result_type: Literal['player'] = 'player')[source]

Bases: object

Player search result.

player_id: int

url: str

ign: str | None = None

real_name: str | None = None

country: str | None = None

image_url: str | None = None

result_type: Literal['player'] = 'player'

__init__(player_id: int, url: str, ign: str | None = None, real_name: str | None = None, country: str | None = None, image_url: str | None = None, result_type: Literal['player'] = 'player') → None

class vlrdevapi.search.SearchTeamResult(team_id: int, url: str, name: str | None = None, country: str | None = None, logo_url: str | None = None, is_inactive: bool = False, result_type: Literal['team'] = 'team')[source]

Bases: object

Team search result.

team_id: int

url: str

name: str | None = None

country: str | None = None

logo_url: str | None = None

is_inactive: bool = False

result_type: Literal['team'] = 'team'

__init__(team_id: int, url: str, name: str | None = None, country: str | None = None, logo_url: str | None = None, is_inactive: bool = False, result_type: Literal['team'] = 'team') → None

class vlrdevapi.search.SearchEventResult(event_id: int, url: str, name: str | None = None, date_range: str | None = None, prize: str | None = None, image_url: str | None = None, result_type: Literal['event'] = 'event')[source]

Bases: object

Event search result.

event_id: int

url: str

name: str | None = None

date_range: str | None = None

prize: str | None = None

image_url: str | None = None

result_type: Literal['event'] = 'event'

__init__(event_id: int, url: str, name: str | None = None, date_range: str | None = None, prize: str | None = None, image_url: str | None = None, result_type: Literal['event'] = 'event') → None

class vlrdevapi.search.SearchSeriesResult(series_id: int, url: str, name: str | None = None, image_url: str | None = None, result_type: Literal['series'] = 'series')[source]

Bases: object

Series search result.

series_id: int

url: str

name: str | None = None

image_url: str | None = None

result_type: Literal['series'] = 'series'

__init__(series_id: int, url: str, name: str | None = None, image_url: str | None = None, result_type: Literal['series'] = 'series') → None

class vlrdevapi.search.SearchResults(query: str, total_results: int, players: list[SearchPlayerResult] = <factory>, teams: list[SearchTeamResult] = <factory>, events: list[SearchEventResult] = <factory>, series: list[SearchSeriesResult] = <factory>)[source]

Bases: object

Combined search results.

query: str

total_results: int

players: list[SearchPlayerResult]

teams: list[SearchTeamResult]

events: list[SearchEventResult]

series: list[SearchSeriesResult]

__init__(query: str, total_results: int, players: list[SearchPlayerResult] = <factory>, teams: list[SearchTeamResult] = <factory>, events: list[SearchEventResult] = <factory>, series: list[SearchSeriesResult] = <factory>) → None

vlrdevapi.search.search(query: str, search_type: Literal['all', 'players', 'teams', 'events', 'series'] = 'all', timeout: float | None = None) → SearchResults[source]

Search VLR.gg for players, teams, events, and series.

Parameters:

query – Search query string
search_type – Type of search - “all”, “players”, “teams”, “events”, or “series”
timeout – Request timeout in seconds

Returns:

SearchResults object containing all matching results

Raises:

NetworkError – If the request fails

Example

>>> import vlrdevapi as vlr
>>> results = vlr.search.search("nrg")
>>> print(f"Found {results.total_results} results")
>>> for player in results.players:
...     print(f"Player: {player.ign}")
>>> for team in results.teams:
...     print(f"Team: {team.name}")

vlrdevapi.search.search_players(query: str, timeout: float | None = None) → list[SearchPlayerResult][source]

Search for players only.

Parameters:

query – Search query string
timeout – Request timeout in seconds

Returns:

List of player search results

Example

>>> import vlrdevapi as vlr
>>> players = vlr.search.search_players("tenz")
>>> for player in players:
...     print(f"{player.ign} - {player.real_name}")

vlrdevapi.search.search_teams(query: str, timeout: float | None = None) → list[SearchTeamResult][source]

Search for teams only.

Parameters:

query – Search query string
timeout – Request timeout in seconds

Returns:

List of team search results

Example

>>> import vlrdevapi as vlr
>>> teams = vlr.search.search_teams("sentinels")
>>> for team in teams:
...     print(f"{team.name} - Active: {not team.is_inactive}")

vlrdevapi.search.search_events(query: str, timeout: float | None = None) → list[SearchEventResult][source]

Search for events only.

Parameters:

query – Search query string
timeout – Request timeout in seconds

Returns:

List of event search results

Example

>>> import vlrdevapi as vlr
>>> events = vlr.search.search_events("champions")
>>> for event in events:
...     print(f"{event.name} - {event.date_range}")

vlrdevapi.search.search_series(query: str, timeout: float | None = None) → list[SearchSeriesResult][source]

Search for series only.

Parameters:

query – Search query string
timeout – Request timeout in seconds

Returns:

List of series search results

Example

>>> import vlrdevapi as vlr
>>> series = vlr.search.search_series("vct")
>>> for s in series:
...     print(f"{s.name}")

Functions

search

Search across all types (players, teams, events, series).

vlrdevapi.search.search(query: str, search_type: Literal['all', 'players', 'teams', 'events', 'series'] = 'all', timeout: float | None = None) → SearchResults[source]

Search VLR.gg for players, teams, events, and series.

Parameters:

query – Search query string
search_type – Type of search - “all”, “players”, “teams”, “events”, or “series”
timeout – Request timeout in seconds

Returns:

SearchResults object containing all matching results

Raises:

NetworkError – If the request fails

Example

>>> import vlrdevapi as vlr
>>> results = vlr.search.search("nrg")
>>> print(f"Found {results.total_results} results")
>>> for player in results.players:
...     print(f"Player: {player.ign}")
>>> for team in results.teams:
...     print(f"Team: {team.name}")

Keyword Arguments:

enrich – defaults to True. When False the function returns raw search cards without additional requests to team/player detail pages.

Caching:

Results are cached in process via vlr.fetcher. Clear the cache with vlr.fetcher.clear_cache() before re-running the same query if you need fresh data.

search_players

Search for players only.

vlrdevapi.search.search_players(query: str, timeout: float | None = None) → list[SearchPlayerResult][source]

Search for players only.

Parameters:

query – Search query string
timeout – Request timeout in seconds

Returns:

List of player search results

Example

>>> import vlrdevapi as vlr
>>> players = vlr.search.search_players("tenz")
>>> for player in players:
...     print(f"{player.ign} - {player.real_name}")

search_teams

Search for teams only.

vlrdevapi.search.search_teams(query: str, timeout: float | None = None) → list[SearchTeamResult][source]

Search for teams only.

Parameters:

query – Search query string
timeout – Request timeout in seconds

Returns:

List of team search results

Example

>>> import vlrdevapi as vlr
>>> teams = vlr.search.search_teams("sentinels")
>>> for team in teams:
...     print(f"{team.name} - Active: {not team.is_inactive}")

search_events

Search for events only.

vlrdevapi.search.search_events(query: str, timeout: float | None = None) → list[SearchEventResult][source]

Search for events only.

Parameters:

query – Search query string
timeout – Request timeout in seconds

Returns:

List of event search results

Example

>>> import vlrdevapi as vlr
>>> events = vlr.search.search_events("champions")
>>> for event in events:
...     print(f"{event.name} - {event.date_range}")

search_series

Search for series only.

vlrdevapi.search.search_series(query: str, timeout: float | None = None) → list[SearchSeriesResult][source]

Search for series only.

Parameters:

query – Search query string
timeout – Request timeout in seconds

Returns:

List of series search results

Example

>>> import vlrdevapi as vlr
>>> series = vlr.search.search_series("vct")
>>> for s in series:
...     print(f"{s.name}")

Data Models

SearchResults

Container for all search results.

class vlrdevapi.search.SearchResults(query: str, total_results: int, players: list[SearchPlayerResult] = <factory>, teams: list[SearchTeamResult] = <factory>, events: list[SearchEventResult] = <factory>, series: list[SearchSeriesResult] = <factory>)[source]

Combined search results.

query: str

total_results: int

players: list[SearchPlayerResult]

teams: list[SearchTeamResult]

events: list[SearchEventResult]

series: list[SearchSeriesResult]

__init__(query: str, total_results: int, players: list[SearchPlayerResult] = <factory>, teams: list[SearchTeamResult] = <factory>, events: list[SearchEventResult] = <factory>, series: list[SearchSeriesResult] = <factory>) → None

SearchPlayerResult

Player search result with enriched data.

class vlrdevapi.search.SearchPlayerResult(player_id: int, url: str, ign: str | None = None, real_name: str | None = None, country: str | None = None, image_url: str | None = None, result_type: Literal['player'] = 'player')[source]

Player search result.

player_id: int

url: str

ign: str | None = None

real_name: str | None = None

country: str | None = None

image_url: str | None = None

result_type: Literal['player'] = 'player'

__init__(player_id: int, url: str, ign: str | None = None, real_name: str | None = None, country: str | None = None, image_url: str | None = None, result_type: Literal['player'] = 'player') → None

SearchTeamResult

Team search result with enriched data.

class vlrdevapi.search.SearchTeamResult(team_id: int, url: str, name: str | None = None, country: str | None = None, logo_url: str | None = None, is_inactive: bool = False, result_type: Literal['team'] = 'team')[source]

Team search result.

team_id: int

url: str

name: str | None = None

country: str | None = None

logo_url: str | None = None

is_inactive: bool = False

result_type: Literal['team'] = 'team'

__init__(team_id: int, url: str, name: str | None = None, country: str | None = None, logo_url: str | None = None, is_inactive: bool = False, result_type: Literal['team'] = 'team') → None

SearchEventResult

Event search result.

class vlrdevapi.search.SearchEventResult(event_id: int, url: str, name: str | None = None, date_range: str | None = None, prize: str | None = None, image_url: str | None = None, result_type: Literal['event'] = 'event')[source]

Event search result.

event_id: int

url: str

name: str | None = None

date_range: str | None = None

prize: str | None = None

image_url: str | None = None

result_type: Literal['event'] = 'event'

__init__(event_id: int, url: str, name: str | None = None, date_range: str | None = None, prize: str | None = None, image_url: str | None = None, result_type: Literal['event'] = 'event') → None

SearchSeriesResult

Series search result.

class vlrdevapi.search.SearchSeriesResult(series_id: int, url: str, name: str | None = None, image_url: str | None = None, result_type: Literal['series'] = 'series')[source]

Series search result.

series_id: int

url: str

name: str | None = None

image_url: str | None = None

result_type: Literal['series'] = 'series'

__init__(series_id: int, url: str, name: str | None = None, image_url: str | None = None, result_type: Literal['series'] = 'series') → None

Examples

Basic Search

import vlrdevapi as vlr

# Search everything
results = vlr.search.search("nrg")
print(f"Found {results.total_results} results")

# Access results by type
for team in results.teams:
    status = "inactive" if team.is_inactive else "active"
    print(f"Team: {team.name} ({status}) - {team.country}")

for player in results.players:
    print(f"Player: {player.ign} - {player.country}")

Type-Specific Searches

import vlrdevapi as vlr
# Search only players
players = vlr.search.search_players("tenz")
for player in players:
    print(f"{player.ign} - {player.country}")

# Search only teams
teams = vlr.search.search_teams("sentinels")

# Search only events
events = vlr.search.search_events("champions")

See more examples: Usage Examples