osu!ex v0.2.0 OsuEx.API View Source
A wrapper around the osu! API.
Usage
iex> {:ok, u} = OsuEx.API.get_user("cookiezi"); u
%{
accuracy: 98.85315704345703,
count100: 368145,
count300: 9087788,
count50: 32334,
count_rank_a: 505,
count_rank_s: 99,
count_rank_sh: 568,
count_rank_ss: 22,
count_rank_ssh: 70,
country: "KR",
events: [],
level: 101.69,
playcount: 22667,
pp_country_rank: 2,
pp_rank: 3,
pp_raw: 13849.5,
ranked_score: 34166564378,
total_score: 195920565377,
total_seconds_played: 1832614,
user_id: 124493,
username: "Cookiezi"
}
The get_*
function names mirror the API itself as do the parameter names,
which can be passed as a trailing keyword list.
The returned data is mostly identical to the osu! API documentation, except for the following:
- The return value of functions which return at most one result
(
get_user/2
for example) is a map instead of a list containing one map. If no result is found, then the value isnil
, instead of an empty list. - Numbers, booleans, dates, and lists are parsed to their native types.
To parse enum values like approved: 3
into more human-readable atoms,
or encode/decode mods, see the OsuEx.API.Utils
module.
Configuration
To access the osu! API, you need to provide an API key.
You can pass the k
parameter around if you want,
but otherwise you can configure its value in config.exs
:
config :osu_api, api_key: "<your key here>"
You can also set the OSU_API_KEY
environment variable.
Link to this section Summary
Functions
Gets a beatmap by ID (beatmap ID, not beatmapset ID) or MD5
Same as get_beatmap/2
but raises exceptions
Gets beatmaps
Same as get_beatmaps/2
but raises exceptions
Gets a beatmapset by ID (beatmapset ID, not beatmap ID)
Same as get_beatmapset/2
but raises exceptions
Gets a multiplayer match by ID
Same as get_match/2
but raises exceptions
Gets replay data for a score
Same as get_replay/4
but raises exceptions
Gets a beatmap's top scores
Same as get_scores/2
but raises exceptions
Gets a user by username or user ID
Same as get_user/2
but raises exceptions
Gets a user's top scores
Same as get_user_best/2
but raises exceptions
Gets a user's recent scores
Same as get_user_recent/2
but raises exceptions
Link to this section Types
beatmap_id()
View Source
beatmap_id() :: pos_integer() | binary()
beatmap_id() :: pos_integer() | binary()
mode()
View Source
mode() :: 0..3
mode() :: 0..3
user_id()
View Source
user_id() :: pos_integer() | String.t()
user_id() :: pos_integer() | String.t()
Link to this section Functions
get_beatmap(id_or_md5, opts \\ [])
View Source
get_beatmap(beatmap_id(), keyword()) ::
{:ok, map() | nil} | OsuEx.API.Error.t()
get_beatmap(beatmap_id(), keyword()) :: {:ok, map() | nil} | OsuEx.API.Error.t()
Gets a beatmap by ID (beatmap ID, not beatmapset ID) or MD5.
get_beatmap!(id_or_md5, opts \\ [])
View Source
get_beatmap!(beatmap_id(), keyword()) :: map() | nil
get_beatmap!(beatmap_id(), keyword()) :: map() | nil
Same as get_beatmap/2
but raises exceptions.
get_beatmaps(opts \\ [])
View Source
get_beatmaps(keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
get_beatmaps(keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
Gets beatmaps.
get_beatmaps!(opts \\ []) View Source
Same as get_beatmaps/2
but raises exceptions.
get_beatmapset(id, opts \\ [])
View Source
get_beatmapset(pos_integer(), keyword()) ::
{:ok, [map()]} | OsuEx.API.Error.t()
get_beatmapset(pos_integer(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
Gets a beatmapset by ID (beatmapset ID, not beatmap ID).
get_beatmapset!(id, opts \\ [])
View Source
get_beatmapset!(pos_integer(), keyword()) :: [map()]
get_beatmapset!(pos_integer(), keyword()) :: [map()]
Same as get_beatmapset/2
but raises exceptions.
get_match(id, opts \\ [])
View Source
get_match(pos_integer(), keyword()) :: {:ok, map() | nil} | OsuEx.API.Error.t()
get_match(pos_integer(), keyword()) :: {:ok, map() | nil} | OsuEx.API.Error.t()
Gets a multiplayer match by ID.
get_match!(id, opts \\ [])
View Source
get_match!(pos_integer(), keyword()) :: map() | nil
get_match!(pos_integer(), keyword()) :: map() | nil
Same as get_match/2
but raises exceptions.
get_replay(map_id, user, mode, opts \\ [])
View Source
get_replay(pos_integer(), user_id(), mode(), keyword()) ::
{:ok, map() | nil} | OsuEx.API.Error.t()
get_replay(pos_integer(), user_id(), mode(), keyword()) :: {:ok, map() | nil} | OsuEx.API.Error.t()
Gets replay data for a score.
get_replay!(map_id, user, mode, opts \\ [])
View Source
get_replay!(pos_integer(), user_id(), mode(), keyword()) :: map() | nil
get_replay!(pos_integer(), user_id(), mode(), keyword()) :: map() | nil
Same as get_replay/4
but raises exceptions.
get_scores(map_id, opts \\ [])
View Source
get_scores(pos_integer(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
get_scores(pos_integer(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
Gets a beatmap's top scores.
get_scores!(map_id, opts \\ [])
View Source
get_scores!(pos_integer(), keyword()) :: [map()]
get_scores!(pos_integer(), keyword()) :: [map()]
Same as get_scores/2
but raises exceptions.
get_user(user, opts \\ [])
View Source
get_user(user_id(), keyword()) :: {:ok, map() | nil} | OsuEx.API.Error.t()
get_user(user_id(), keyword()) :: {:ok, map() | nil} | OsuEx.API.Error.t()
Gets a user by username or user ID.
get_user!(user, opts \\ []) View Source
Same as get_user/2
but raises exceptions.
get_user_best(user, opts \\ [])
View Source
get_user_best(user_id(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
get_user_best(user_id(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
Gets a user's top scores.
get_user_best!(user, opts \\ []) View Source
Same as get_user_best/2
but raises exceptions.
get_user_recent(user, opts \\ [])
View Source
get_user_recent(user_id(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
get_user_recent(user_id(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()
Gets a user's recent scores.
get_user_recent!(user, opts \\ []) View Source
Same as get_user_recent/2
but raises exceptions.