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 is nil, 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

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

Link to this section Types

Link to this section Functions

Link to this function

get_beatmap(id_or_md5, opts \\ []) View Source
get_beatmap(beatmap_id(), keyword()) ::
  {:ok, map() | nil} | OsuEx.API.Error.t()

Gets a beatmap by ID (beatmap ID, not beatmapset ID) or MD5.

Link to this function

get_beatmap!(id_or_md5, opts \\ []) View Source
get_beatmap!(beatmap_id(), keyword()) :: map() | nil

Same as get_beatmap/2 but raises exceptions.

Link to this function

get_beatmaps(opts \\ []) View Source
get_beatmaps(keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()

Gets beatmaps.

Link to this function

get_beatmaps!(opts \\ []) View Source
get_beatmaps!(keyword()) :: [map()]

Same as get_beatmaps/2 but raises exceptions.

Link to this function

get_beatmapset(id, opts \\ []) View Source
get_beatmapset(pos_integer(), keyword()) ::
  {:ok, [map()]} | OsuEx.API.Error.t()

Gets a beatmapset by ID (beatmapset ID, not beatmap ID).

Link to this function

get_beatmapset!(id, opts \\ []) View Source
get_beatmapset!(pos_integer(), keyword()) :: [map()]

Same as get_beatmapset/2 but raises exceptions.

Link to this function

get_match(id, opts \\ []) View Source
get_match(pos_integer(), keyword()) :: {:ok, map() | nil} | OsuEx.API.Error.t()

Gets a multiplayer match by ID.

Link to this function

get_match!(id, opts \\ []) View Source
get_match!(pos_integer(), keyword()) :: map() | nil

Same as get_match/2 but raises exceptions.

Link to this function

get_replay(map_id, user, mode, opts \\ []) View Source
get_replay(pos_integer(), user_id(), mode(), keyword()) ::
  {:ok, map() | nil} | OsuEx.API.Error.t()

Gets replay data for a score.

Link to this function

get_replay!(map_id, user, mode, opts \\ []) View Source
get_replay!(pos_integer(), user_id(), mode(), keyword()) :: map() | nil

Same as get_replay/4 but raises exceptions.

Link to this function

get_scores(map_id, opts \\ []) View Source
get_scores(pos_integer(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()

Gets a beatmap's top scores.

Link to this function

get_scores!(map_id, opts \\ []) View Source
get_scores!(pos_integer(), keyword()) :: [map()]

Same as get_scores/2 but raises exceptions.

Link to this function

get_user(user, opts \\ []) View Source
get_user(user_id(), keyword()) :: {:ok, map() | nil} | OsuEx.API.Error.t()

Gets a user by username or user ID.

Link to this function

get_user!(user, opts \\ []) View Source
get_user!(user_id(), keyword()) :: map() | nil

Same as get_user/2 but raises exceptions.

Link to this function

get_user_best(user, opts \\ []) View Source
get_user_best(user_id(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()

Gets a user's top scores.

Link to this function

get_user_best!(user, opts \\ []) View Source
get_user_best!(user_id(), keyword()) :: [map()]

Same as get_user_best/2 but raises exceptions.

Link to this function

get_user_recent(user, opts \\ []) View Source
get_user_recent(user_id(), keyword()) :: {:ok, [map()]} | OsuEx.API.Error.t()

Gets a user's recent scores.

Link to this function

get_user_recent!(user, opts \\ []) View Source
get_user_recent!(user_id(), keyword()) :: [map()]

Same as get_user_recent/2 but raises exceptions.