Valorant API Wrapper Client Tutorial¶

This notebook walks through the main ways to use ValorantAPI, from basic setup to common lookup and convenience patterns.

1. Install and import¶

If you are working from this repository, install it in editable mode first:

pip install -e .
In [2]:
from pathlib import Path
from tempfile import gettempdir

from valorant_assets_api import Language, ValorantAPI

2. Construct a client¶

By default, the client uses a local SQLite cache under your system temp directory, caches responses for 24 hours, and sends a standard user-agent.

In [3]:
api = ValorantAPI()
api
Out[3]:
<valorant_assets_api.client.ValorantAPI at 0x220a8688050>

You can also customize the cache location, expiry time, request logging, or timeout.

In [4]:
api = ValorantAPI(
    cache_path="cache/valorant-demo.db",
    default_expiry=60 * 60,
    request_log_path="valorant-api.log",
    timeout=10,
    download_directory="assets"
)

api
Out[4]:
<valorant_assets_api.client.ValorantAPI at 0x220a8685950>

3. List resources¶

Most endpoints follow a list_* and get_* pattern. Start with a collection call when you want to inspect what is available.

In [5]:
agents = api.list_agents(playable_only=True)
len(agents), agents[0].display_name
Out[5]:
(29, 'Gekko')
In [6]:
agents = api.list_agents(playable_only=True)
for each in agents:
    each.display_icon.cache_to_disk()
    
maps = api.list_maps()
for each in maps:
    if each.display_icon is not None:
        each.display_icon.cache_to_disk()

weapons = api.list_weapons()
for each in weapons:
    each.display_icon.cache_to_disk()
In [7]:
for agent in agents[:5]:
    role_name = agent.role.display_name if agent.role else "No role"
    print(f"{agent.display_name:10} | role={role_name}")

Gekko      | role=Initiator
Fade       | role=Initiator
Breach     | role=Initiator
Deadlock   | role=Sentinel
Tejo       | role=Initiator

4. Fetch a specific resource by UUID¶

Collection results expose UUIDs, which can be passed back into get_* methods.

In [8]:
jett_summary = api.find_agent("Jett", playable_only=True)
jett = api.get_agent(jett_summary.uuid)

print(jett.display_name)
print(jett.description)
print([ability.display_name for ability in jett.abilities])

Jett
Representing her home country of South Korea, Jett's agile and evasive fighting style lets her take risks no one else can. She runs circles around every skirmish, cutting enemies up before they even know what hit them.
['Updraft', 'Tailwind', 'Cloudburst', 'Blade Storm', 'Drift']

5. Use the built-in name helpers¶

For a few common resources, the wrapper includes find_* helpers that first try an exact case-insensitive match and then fall back to a partial match.

In [9]:
map_info = api.find_map("abyss")
weapon = api.find_weapon("bandit")

print(map_info. display_name, map_info.coordinates)
print(weapon.display_name, weapon.category)

Abyss 70° 50' AJ" N, 9° 00' VX" W
Bandit EEquippableCategory::Sidearm

6. Request localized data¶

Endpoints that support localization accept either a Language enum value or a raw language string.

In [10]:
agents_es = api.list_agents(language=Language.ES_ES, playable_only=True)
agents_fr = api.list_agents(language="fr-FR", playable_only=True)

print(agents_es[0].display_name)
print(agents_fr[0].display_name)

Gekko
Gekko

7. Use the convenience helpers¶

The client includes a few methods that compose lower-level endpoints into common tasks.

In [11]:
current_season = api.get_current_season()
version = api.get_version()
active_events = api.get_active_events()

print("Current season:", current_season.display_name if current_season else "None")
print("Game version:", version.version)
print("Active events:", [event.display_name for event in active_events])

Current season: ACT II
Game version: 12.06.00.4440219
Active events: []

Another convenience method flattens nested contract chapter rewards into a single list.

In [12]:
contracts = api.list_contracts()
sample_contract = contracts[0]
rewards = api.list_contract_rewards(sample_contract.uuid)

print(sample_contract.display_name)
print("Reward count:", len(rewards))
print("First reward:", rewards[0].reward if rewards and rewards[0].reward else None)

Gekko Gear
Reward count: 10
First reward: Reward(type='Spray', uuid='cd56a893-44f1-2b56-a477-08a9652c66f8', amount=1, is_highlighted=False)

8. Work with typed models¶

Returned objects are typed models, so nested attributes are already parsed into Python values such as enums and datetimes.

In [13]:
phantom = api.find_weapon("Phantom")

print(type(phantom).__name__)
print(phantom.category)
print(phantom.weapon_stats.fire_rate if phantom.weapon_stats else None)
print(phantom.weapon_stats.wall_penetration if phantom.weapon_stats else None)

Weapon
EEquippableCategory::Rifle
11.0
EWallPenetrationDisplayType::Medium

9. Explore the rest of the API surface¶

The same pattern is available for the other resources exposed by the wrapper:

  • list_buddies() / get_buddy()
  • list_bundles() / get_bundle()
  • list_maps() / get_map() / find_map()
  • list_player_cards() / get_player_card()
  • list_seasons() / get_season() / get_current_season()
  • list_weapons() / get_weapon() / find_weapon()
  • and the rest of the methods in valorant_assets_api.client.ValorantAPI

A good workflow is:

  1. Start with a list_* method.
  2. Pick a UUID from a returned model.
  3. Call the matching get_* method for full details.
  4. Use helper methods when you want name lookups, active windows, or flattened rewards.