API Documentation

Welcome to the osu-profile-stats API documentation. Our API allows you to generate customizable cards and retrieve osu! player data in multiple formats including SVG, PNG, and JPG. All endpoints are accessible via simple GET requests.

Base URL: All endpoints are relative to https://osu-profile-stats.vercel.app

Profile Stats Card

Generates a customizable SVG card displaying a user's profile statistics.

GET /api/profile-stats/:username

Parameters

Parameter Type Description Default
usernameRequired Path The osu! username of the player. -
playmode Query Game mode to display stats for.
Values: osu, mania, fruits, taiko. 		User's default
background Query The card background.
Values: bg1, bg2, bg3, bg4, bg5, color. 		User's cover
hex Query A 3 or 6-digit hex code (without #) if background=color. -
version Query Card version. Values: mini, full. mini
height Query Sets a custom height for the card in pixels. 120 (mini), 200 (full)
supporter Query Toggle supporter tag visibility. Values: true, false. true
team Query Toggle team flag visibility. Values: strue, false. true
imageType Query Output image format. Values: svg, png, jpg, jpeg. svg

Example Request

/api/profile-stats/tanese?playmode=mania&background=bg3&version=full&imageType=png

Additional Examples

SVG (default):

/api/profile-stats/tanese?playmode=mania

PNG output:

/api/profile-stats/tanese?playmode=mania&imageType=png

JPG output with custom height:

/api/profile-stats/tanese?playmode=mania&imageType=jpg&height=200

Example Success Response (200 OK)

An SVG image is returned.

Example full card

Example Error Response (404 Not Found)

An SVG error card is returned if the user is not found.

Example error card

User Data (JSON)

Retrieves raw user data and statistics as a JSON object.

GET /api/user-data/:username

Parameters

Parameter Type Description Default
usernameRequired Path The osu! username of the player. -
playmode Query Game mode to retrieve stats for.
Values: sosu, mania, fruits, taiko. 		User's default

Example Request

/api/user-data/tanese?playmode=osu

Example Success Response (200 OK)

{
    "avatar_url": "https://a.ppy.sh/...",
    "country_code": "BR",
    "id": 1234567,
    "is_active": true,
    "is_bot": false,
    "is_deleted": false,
    "is_online": true,
    "is_supporter": true,
    "username": "tanese",
    "statistics": {
        "global_rank": 76929,
        "pp": 5000.12,
        "ranked_score": 1234567890,
        ...
    },
    "playmode": "osu"
}

Example Error Response (404 Not Found)

{
    "error": "User \"thisuserdoesnotexist\" not found"
}

Rank History Graph

Generates an SVG graph of a user's rank history over the last 90 days.

GET /api/rank-graph/:username

Parameters

Parameter Type Description Default
usernameRequired Path The osu! username of the player. -
playmode Query Game mode to display rank history for.
Values: osu, mania, fruits, taiko. 		User's default
width Query Width of the graph in pixels. 800
height Query Height of the graph in pixels. 100
imageType Query Output image format. Values: svg, png, jpg, jpeg. svg

Example Request

/api/rank-graph/tanese?playmode=mania&height=120&imageType=png

Additional Examples

SVG (default):

/api/rank-graph/tanese?playmode=mania

PNG output:

/api/rank-graph/tanese?playmode=mania&imageType=png

JPG output with custom dimensions: 

/api/rank-graph/tanese?playmode=mania&imageType=jpg&width=1000&height=150

Example Success Response (200 OK)

An SVG image is returned.

Example rank graph

Example Error Response (404 Not Found)

A JSON error is returned.

{
    "error": "No rank history data available"
}

API Meta

Returns a JSON object containing information about all available API endpoints.

GET /api

Parameters

This endpoint does not accept any parameters.

Example Request

/api

Example Success Response (200 OK)

{
    "message": "Welcome to the silly api, here is some info:",
    "endpoints": {
        "profileStats": { ... },
        "userData": { ... },
        "rankGraph": { ... },
        "api": { ... }
    },
    "repository": "https://github.com/Luis-Tanese/osu-profile-stats"
}