Hexide Osu! API documentation

In this page you will be able to get some details about API documentation and stuff.

If you have any requests or sugestions please email at miz@hexide.com, or leave them in this thread http://osu.ppy.sh/forum/t/137156

GET /

GET /doc

GET /stats

Pages dedicated for API documentations, not an actual API.

GET /beatmaps/

Returns list of beatmaps that are on the server

Output structure:
[
	{
		id:           Beatmap id in our database
		ranked_id:    Expected beatmap id in main osu system
		name:         Full beatmap name
		title:        Beatmap title
		type:         Beatmap type
		size:         Beatmap size in bytes
		date:          Date when last beatmap was updated
	},
	[...]
]
Example output:
https://osu.hexide.com/beatmaps

[
	{
		id: 1,
		ranked_id: 31066,
		name: "31066 DJ YOSHITAKA - SEED",
		title: "DJ YOSHITAKA - SEED",
		type: "osz",
		size: 2378910,
		date: "2013-04-18 18:59:13"
	},
	[...]
	{
		id: 7,
		ranked_id: 698,
		name: "698 RIZE - Lady Love",
		title: "RIZE - Lady Love",
		type: "osz",
		size: 8941073,
		date: "2013-04-18 18:56:05"
	}
]

GET /beatmaps/[0-9]+

Returns full data on a single beatmap id.

Request data:
[0-9]+ Can be any integer, ranked beatmap id
Output structure:
{
	id:           Beatmap id in our database
	ranked_id:    Expected beatmap id in main osu system
	name:         Beatmap file name
	title:        Beatmap title
	type:         Beatmap type
	size:         Beatmap size in bytes
	date:          Date when last beatmap was updated
	hash_md5:     Beatmap file md5 hash
	hash_sha1:    Beatmap file sha1 hash
	versions:
	[
		{
			id:               Difficulty record id in database
			map:              Parent beatmap id
			name:             Name of difficulty file
			size:             Difficulty file size
			hash_md5:         Difficulty file md5 hash
			hash_sha1:        Difficulty file sha1 hash
			m_title:          Song name
			m_artist:         Song artist
			m_creator:        Beatmap creator name
			m_version:        Difficulty name
			m_source:         Song source
			m_tags:           Additional tags
			m_beatmap:        Ranked difficulty id
			m_beatmapset:     Ranked beatmap id
			d_drain:          Drain rate
			d_size:           Note size
			d_diff:           Overal difficulty
			d_smult:          Slider score multiplier
			d_srate:          Slider tick rate
			version:          Beatmap difficulty file version
		},
		[...]
	]
}
Example output:
https://osu.hexide.com/beatmaps/846

{
	id: 266,
	ranked_id: 846,
	name: "846 TERRA - We Are",
	title: "TERRA - We Are",
	type: "osz",
	size: 5754508,
	date: "2013-04-18 18:59:03",
	hash_md5: "b589f6a288f5a3bafa031e2220f95f",
	hash_sha1: "e7355644ba85e1cb6cf597253eb71070b93515",
	"versions":
	[
		{
			id: 931,
			map: 266,
			name: "TERRA - We Are (James) [Normal]",
			size: 3664,
			hash_md5: "23dba9f7d217818ecbd50cc1586c90",
			hash_sha1: "6bc092a4aff8156fcc22794a986374e3ebc8e34",
			m_title: "We Are",
			m_artist: "TERRA",
			m_creator: "James",
			m_version: "Normal",
			m_source: null,
			m_tags: null,
			m_beatmap: 0,
			m_beatmapset: 0,
			d_drain: 3,
			d_size: 3,
			d_diff: 3,
			d_smult: 1,
			d_srate: 1,
			version: 4
		},
		[...]
	]
}

GET /beatmaps/[0-9]+/content/raw

Provides list of beatmap contents.

Request data:
[0-9]+ Can be any integer, beatmap id

GET /beatmaps/[0-9]+/content/raw/layout

Layout of beatmap files, includes subdirectories.

Request data:
[0-9]+ Can be any integer, beatmap id
Output structure:
{
	directories:
	{
		[key]:
		{
			directories: { [...] }
			files: [ [...] ]
		},
		[...]
	},
	files:
	[
		[value],   File name
		[...]
	]
}
Example output:
https://osu.hexide.com/beatmaps/12191/content/raw/layout

{
    directories:
    {
        bg:
        {
            directories: {},
            files:
            [
                "spotlight2.png",
                "2.png",
                "frame.png",
                "k.png",
                [...]
            ]
        },
        text:
        {
            directories: {},
            files:
            [
                "9.png",
                "11.png",
                "1.png",
                [...]
            ]
        },
        scrltext:
        {
            directories: {},
            files:
            [
                "9.png",
                "1.png",
                "12.png",
                [...]
            ]
        },
        noise:
        {
            directories: {},
            files:
            [
                "1.png",
                "2.png"
            ]
        }
    },
    files:
    [
        "score-dot.png",
        "default-1.png",
        "score-5.png",
        "default-5.png",
        "hit50.png",
        [...]
    ]
}

GET /beatmaps/[0-9]+/content/hash/.*

Returns all supported hashes of specified file

Request data:
[0-9]+ Can be any integer, beatmap id
.* Any existing file name
Output structure:
{
	md2:            Hash value
	md4:            Hash value
	md5:            Hash value
	sha1:           Hash value
	sha224:         Hash value
	sha256:         Hash value
	sha384:         Hash value
	sha512:         Hash value
	ripemd128:      Hash value
	ripemd160:      Hash value
	ripemd256:      Hash value
	ripemd320:      Hash value
	whirlpool:      Hash value
	tiger128,3:     Hash value
	tiger160,3:     Hash value
	tiger192,3:     Hash value
	tiger128,4:     Hash value
	tiger160,4:     Hash value
	tiger192,4:     Hash value
	snefru:         Hash value
	snefru256:      Hash value
	gost:           Hash value
	adler32:        Hash value
	crc32:          Hash value
	crc32b:         Hash value
	fnv132:         Hash value
	fnv164:         Hash value
	joaat:          Hash value
	haval128,3:     Hash value
	haval160,3:     Hash value
	haval192,3:     Hash value
	haval224,3:     Hash value
	haval256,3:     Hash value
	haval128,4:     Hash value
	haval160,4:     Hash value
	haval192,4:     Hash value
	haval224,4:     Hash value
	haval256,4:     Hash value
	haval128,5:     Hash value
	haval160,5:     Hash value
	haval192,5:     Hash value
	haval224,5:     Hash value
	haval256,5:     Hash value
}
Example output:
https://osu.hexide.com/beatmaps/103094/content/raw/hash/soft-hitclap2.wav

{
    md2: "379dda3e7d70f29385d2c28144ff8f9b",
    md4: "5274eed5262f9f0294a3aaead0413d1f",
    md5: "ffa7f21f24839573a77a3857168f9e92",
    sha1: "729338d638ab3084d3b465462de69cdc2872cc35",
    sha224: "fccf7e404b8bc1fe8b0951dd7569f13e751ca36c2f13012c13ab7b3a",
    sha256: "cb2d40c9487c3cc606f4c481b802b1eb0cc726af8e4616206b57336f3cb04f1e",
    sha384: "e08fa997ac64354339e5431d5e73b8a27285d98b93e83e2adc6d97bd8800dd1a5fe736b6e9c4ea59e73783791b837f06",
    sha512: "cbe938940c0a5a63ceeb9b159d8df0bf56c1651f4572afdde5af10d3a245c49b6851aad02ed664b7d0a6b8ccdaed2e41bac777e065a3bddbafff6e0e42662eab",
    ripemd128: "b364c3f2ee1cd36d8285185e53f8bca0",
    ripemd160: "b19b67c299269b4f63e358be3b0f2a39b117b15e",
    ripemd256: "1171ef3385db9d6ff5d59e6fe3f8de94b1647f1aa1c79f4313fcfbb7114c02f4",
    ripemd320: "f1339517e967ec8ad124a796f616aa732888f69aec6767ce36436b0858ce0181aba500da6daa07e2",
    whirlpool: "5ca205542ab39ab234b6c32ead285673743148b461622a42add95f4214e2dc859911aa682dce0f196b9f262bcc996c17da390cec81430ddd4aff6530ebac6729",
    tiger128,3: "53439d54006243581d3c8f82daadcbf6",
    tiger160,3: "53439d54006243581d3c8f82daadcbf6d1393634",
    tiger192,3: "53439d54006243581d3c8f82daadcbf6d1393634e562f934",
    tiger128,4: "f5b2d1613b86e110aee06c85d00c2960",
    tiger160,4: "f5b2d1613b86e110aee06c85d00c2960ee7fff02",
    tiger192,4: "f5b2d1613b86e110aee06c85d00c2960ee7fff020e2bd354",
    snefru: "1b146103e865acb2f6ffea57c320169ccd369131892d5c516258a2498ac40f5c",
    snefru256: "1b146103e865acb2f6ffea57c320169ccd369131892d5c516258a2498ac40f5c",
    gost: "4581b39524e126bc939dd63952b67fee9959aff1754cbfdc51194496d3272bca",
    adler32: "a1926e1a",
    crc32: "228c9a97",
    crc32b: "f3e5ae7b",
    fnv132: "afc5f3da",
    fnv164: "7bdddd79aabe3a7a",
    joaat: "32860661",
    haval128,3: "021d0e05c8a478d391a9c13455d86841",
    haval160,3: "5cf930ccb22d83050b9cb33b6fce25467cf32f63",
    haval192,3: "ede229cce4907c05add2b13babec1d46d75220639ff94015",
    haval224,3: "d3dc29ccb78f7c053cccb13b76e61d46f34e2063f0f1401504104ae4",
    haval256,3: "b4dc29cca88f7c052eccb13b68e61d46ed4e2063ddf14015fc0f4ae438cdf9fb",
    haval128,4: "233d094c4e71988c3425aa50cbbdd036",
    haval160,4: "ea4e610c6818d2c8dabfd18002a79ff13469d840",
    haval192,4: "f960590ca197d0c8fa04ca80528798f14917d4405f3ce4dc",
    haval224,4: "1659590c9194d0c8f7fec980788398f17215d440393ae4dcd6e038af",
    haval256,4: "0e59590c7a94d0c8f4fec9805a8398f17115d440263ae4dcc7e038af3fc3cf45",
    haval128,5: "b8499d1ad8bb2602791d84c3ba3ce1c1",
    haval160,5: "2cb757c9d4e0f52969a8b7adfc946d155a5a9917",
    haval192,5: "869255c99fa6f12933ddb1ad134b6d152e838e17c2fcbb15",
    haval224,5: "4a8e55c95aa6f12967d6b1adad456d1527838e174cf7bb1536d27347",
    haval256,5: "358e55c94aa6f12962d6b1ad9f456d151b838e1747f7bb1535d2734751d815ac"
}

GET /beatmaps/[0-9]+/content/mp3/short

GET /beatmaps/[0-9]+/content/mp3/full

Returns beatmap audio preview.

Request data:
[0-9]+ Can be any integer, beatmap id

GET /beatmaps/[0-9]+/content/image/full

Returns primary beatmap background file.

Request data:
[0-9]+ Can be any integer, beatmap id

GET /beatmaps/[0-9]+/content/image/custom/[0-9]+x[0-9]+

GET /beatmaps/[0-9]+/content/image/custom/[0-9]+x[0-9]+/crop

Returns custom sized background image.
Crop option fills background into specified image size, unlike default - maintain aspect ratio.

Request data:
[0-9]+ Can be any integer, beatmap id

[0-9]+ Image width
[0-9]+ Image height
Image limitations:
Maximum image size: , minimum 

GET /beatmaps/[0-9]+/download(/.*)?

Beatmap download action

Request data:
[0-9]+ Can be any integer, beatmap id
Example output:
https://osu.hexide.com/beatmaps/846/download/with-video.osz

*binary data* :v

GET /beatmaps/[0-9]+/download/novid(/.*)?

Beatmap download action

Request data:
[0-9]+ Can be any integer, beatmap id
Example output:
https://osu.hexide.com/beatmaps/846/download/novid/no-video.osz

*binary data* :v

GET /metadata/[0-9]+

GET /metadata/[0-9A-Fa-f]{32}

GET /metadata/[0-9A-Fa-f]{40}

Return single difficulty data.
Supports selection by id, md5 hash and sha1 hash.

Request data:
[0-9]+ Can be any integer
Output structure:
{
	id:               Difficulty record id in database
	map:              Parent beatmap id
	name:             Name of difficulty file
	size:             Difficulty file size
	hash_md5:         Difficulty file md5 hash
	hash_sha1:        Difficulty file sha1 hash
	m_title:          Song name
	m_artist:         Song artist
	m_creator:        Beatmap creator name
	m_version:        Difficulty name
	m_source:         Song source
	m_tags:           Additional tags
	m_beatmap:        Ranked difficulty id
	m_beatmapset:     Ranked beatmap id
	d_drain:          Drain rate
	d_size:           Note size
	d_diff:           Overal difficulty
	d_smult:          Slider score multiplier
	d_srate:          Slider tick rate
	version:          Beatmap difficulty file version
}
Example output:
https://osu.hexide.com/metadata/931

{
	id: 931,
	map: 266,
	name: "TERRA - We Are (James) [Normal]",
	size: 3664,
	hash_md5: "23dba9f7d217818ecbd50cc1586c90",
	hash_sha1: "6bc092a4aff8156fcc22794a986374e3ebc8e34",
	m_title: "We Are",
	m_artist: "TERRA",
	m_creator: "James",
	m_version: "Normal",
	m_source: null,
	m_tags: null,
	m_beatmap: 0,
	m_beatmapset: 0,
	d_drain: 3,
	d_size: 3,
	d_diff: 3,
	d_smult: 1,
	d_srate: 1,
	version: 4
}

GET /metadata/[0-9]+/raw

Returns raw data of selected difficulty

Request data:
[0-9]+ Can be any integer
Output example:
https://osu.hexide.com/metadata/931/raw

osu file format v9

[General]
AudioFilename: Renard - TU4AR.mp3
AudioLeadIn: 0
PreviewTime: 39307
Countdown: 0
SampleSet: Normal
StackLeniency: 0.7
Mode: 1
LetterboxInBreaks: 0

[Editor]
Bookmarks: 65488,74215,82942,91669,109124,148397,165851
DistanceSpacing: 1
BeatDivisor: 4
GridSize: 32

[Metadata]
Title:TU4AR
Artist:Renard
Creator:Mercurius
Version:Ono's Taiko Oni
Source:
Tags:Hakeru Prismriver Blue Dragon LAPFOX TRAUMA OnosakiHito

[Difficulty]
HPDrainRate:6
CircleSize:5
OverallDifficulty:6
ApproachRate:5
SliderMultiplier:1.4
SliderTickRate:1

[Events]
//Background and Video events
0,0,"Taiko_BG.jpg"
//Break Periods
//Storyboard Layer 0 (Background)
//Storyboard Layer 1 (Fail)
//Storyboard Layer 2 (Pass)
//Storyboard Layer 3 (Foreground)
//Storyboard Sound Samples
//Background Colour Transformations
3,100,163,162,255

[TimingPoints]
33,272.727272727273,4,1,0,40,1,0
4669,-133.333333333333,4,1,0,60,0,0
17078,-100,4,1,0,60,0,0
39306,-100,4,1,0,60,0,1
56760,-100,4,1,0,60,0,0
109124,-133.333333333333,4,1,0,60,0,0
112260,-100,4,1,0,60,0,0
130942,-100,4,1,0,60,0,1
146215,-100,4,1,0,60,0,0
165851,-100,4,1,0,60,0,1
183306,-100,4,1,0,60,0,0

[Colours]
Combo1 : 64,0,0
Combo2 : 196,0,0
Combo3 : 255,128,128

[HitObjects]
256,192,4942,5,8
256,192,6032,5,8
256,192,6305,5,0
256,192,6442,1,0
...

GET /search

Provides map and metadata search functionality.

Search request structure and logic ( none of it found ):

Search parameters are date out of 4 components: 'table name', 'table column', 'operand', 'value', for example:

  • metadata.name.like.fade
  • maps.title.like.dance
  • maps.size.gt.100000000
TODO

Operands and their actions:
           equal
           less than
        less than or equal
           greater than
        greater than or equal
         like
API limitations:
 fields can only use:  and 
     fields can only use: , , , , 
  fields can only use: , , , , 
    fields can only use: 
All possible search fields:

Please reffer to database structure of maps and metadata tables.

Example queries:
https://osu.hexide.com/search/maps.title.like.dance
	Finds all rows in `maps` table containing `dance` in `title` column.

https://osu.hexide.com/search/maps.size.gt.100000000
	Finds all beatmaps that are larger than 95mb.

https://osu.hexide.com/search/metadata.name.like.fade/metadata.m_creator.like.la cataline
	Find beatmaps containing 'fade' in any of their difficulties and having difficulty creator as 'la cataline'
Output structure:
[
	{
		id:           Beatmap id in our database
		ranked_id:    Expected beatmap id in main osu system
		name:         Beatmap file name
		title:        Beatmap title
		type:         Beatmap type
		size:         Beatmap size in bytes
		date:          Date when last beatmap was updated
		hash_md5:     Beatmap file md5 hash
		hash_sha1:    Beatmap file sha1 hash
		versions:
		[
			{
				id:               Difficulty record id in database
				map:              Parent beatmap id
				name:             Name of difficulty file
				size:             Difficulty file size
				hash_md5:         Difficulty file md5 hash
				hash_sha1:        Difficulty file sha1 hash
				m_title:          Song name
				m_artist:         Song artist
				m_creator:        Beatmap creator name
				m_version:        Difficulty name
				m_source:         Song source
				m_tags:           Additional tags
				m_beatmap:        Ranked difficulty id
				m_beatmapset:     Ranked beatmap id
				d_drain:          Drain rate
				d_size:           Note size
				d_diff:           Overal difficulty
				d_smult:          Slider score multiplier
				d_srate:          Slider tick rate
				version:          Beatmap difficulty file version
			},
			[...]
		]
	},
	[...]
]


Selective output structure

This is ment to reduce API returged output side by eliminating all unused data by end user. This parameter must always go after "/search/" and before all filters.

Example request structure:
/search//maps.title.like.night          This would return only ranked map is with map title per beatmap.
/search//maps.title.like.night    Will return ranked beatmap id with creator name
/search//maps.title.like.nigh                              This will show all data chat comes from maps table.
/search//maps.title.like.nigh                          This will show all data chat comes from metadata table.

Result ordering

Used to order results, please look at maps table structure for reference which columns can be used. Note, that this option have to go before limit parameter.

Parameter structure:
/order..
Example request structure:
/search/maps.title.like.night/     Will return all beatmaps from highest ranked id to lovest
/search/maps.title.like.night/      Oposite of above query

Result limiting

Another way of limiting size of outputed data, this time by actualy limiting how many results should be returned for that request. This is last parameter for request, it goes after all search filters.

Parameter structure:
/limit..
Example request structure:
/search/maps.title.like.night/       This will return first 5 results for that search query.
/search/maps.title.like.night/       Returns all results from 5th to 10th.

/search/maps.title.like.night/      Returns first 50 results.
/search/maps.title.like.night/     Returns next 50 results.

AND, OR logic

Allows you to specify filter logic for selected fields.
However grouping is not yet supported.
Note: OR logic will always return more results than AND logic. You can also mix OR AND logic, but it might return unpredictable results due to lack of support for grouping.

Parameter structure:
/a.... - Filter with AND logic
/o.... - Filter with OR logic
Example request structure:
/search/.metadata.m_title.like.dance/.metadata.m_artist.like.itou 			WHERE `m_title` LIKE `dance`  `m_artist` LIKE `itou`
/search/.metadata.m_title.like.dance/.metadata.m_artist.like.itou 			WHERE `m_title` LIKE `dance`  `m_artist` LIKE `itou`

TABLE maps

Stores main data about beatmap files

Table columns:
Column Data type Length Unsigned Allow NULL Default Used in search Used in ordering Comment
id int 10 AUTO_INCREMENT
ranked_id int 10 NULL
name varchar 1024
title varchar 1024
type enum 'rar','zip','osz','osz2'
size int 10
date datetime
hash_md5 binary 16 Binary data converted to string in API
hash_sha1 binary 20 Binary data converted to string in API

TABLE metadata

This table contains rest data about beatmaps, mainly difficulties and most of the data about them.

Table columns:
Column Data type Length Unsigned Allow NULL Default Used in search Comment
id int 10 AUTO_INCREMENT
map int 10
name varchar 1024
size int 10
hash_md5 binary 16 Binary data converted to string in API
hash_sha1 binary 20 Binary data converted to string in API
m_title varchar 1024 NULL
m_artist varchar 1024 NULL
m_creator varchar 1024 NULL
m_version varchar 1024 NULL
m_source varchar 1024 NULL
m_tags varchar 1024 NULL
m_beatmap int 10 NULL
m_beatmapset int 10 NULL
d_drain double
d_size double
d_diff double
d_smult double
d_srate double
version tinyint 4 NULL

TABLE raw

This table contains rest data about beatmaps, mainly difficulties and most of the data about them.

Table columns:
Column Data type Length Unsigned Allow NULL Default Used in search Comment
id int 10 AUTO_INCREMENT
raw longtext Raw beatmap data.

osu.grr.io

Subdomain provided by nanashiRei.

Usage:

For simple beatmap downloads: Example: http://osu.grr.io/1
For no-video downloads: ( note added 'n' before beatmap id ) Example: http://osu.grr.io/n1

waa.ai

Subdomain provided by bedabeda.

Usage:

For simple beatmap downloads: Example: http://waa.ai/!1
For no-video downloads: ( note added 'n' before beatmap id ) Example: http://waa.ai/!n1