Hi there!

This is the documentation for the Geometry Dash Level Browser API!

The API (application programming interface) is how the website is able to get all the neat stuff from the Geometry Dash servers. In the off chance that you actually know what any of this means, this page contains everything you need to know about grabbing information on GD levels/accounts/etc without going through the trouble of using the actual GD API on boomlings.com

Geometry Dash's API isn't meant to be publicly used, and is a total nightmare to fetch stuff from. That's why I made this API to send you whatever you need in a nice, clean JSON. You're welcome.

Everything on the API can be accessed without any authorization, and with little to no required parameters.

Here are the different things you can use the API for. Click one to skip to it's documentation.

Levels /api/level/levelID

Profiles /api/profile/username-or-id

Searching /api/search/search-query

Leaderboards /api/leaderboard

Level Leaderboards /api/leaderboardLevel/levelID

Comments & Posts /api/comments/level-or-user-ID

Level Analysis /api/analyze/levelID

Commenting /api/postComment (POST)

Profile Posting /api/postProfileComment (POST)

Messages /messages (4 different POSTs)

Liking /api/like (POST)

Icons /icon/username


In the event that something goes horribly wrong and the server doesn't like your request (or you tried to search for a level/profile/etc that doesn't exist), the API will return "-1". It doesn't actually mean anything, I was just referencing the Geometry Dash servers. But yeah, if it responds that just double check the documentation or make sure what you're looking for actually exists.

If by any chance you use this API for other projects, credit is greatly appreciated!

Levels

/api/level/levelID


LevelID should be the ID of a level (whoa)

Using "daily" or "weekly" as the level ID will return the current daily/weekly level (always downloaded)


Parameters (1)

download: Whether or not to actually download the level (much slower)

*By default it performs a search for the level ID and returns as much information as possible without downloading


Response (36)

*Values that require a download are in red

name: The name of the level

id: The ID of the level

description: The description

author: The name of the level's author (appears lower down in response)

authorID: The ID of the level's author

accountID: The account ID of the level's author. An ID of 0 indicates a green (unregistered) user

difficulty: The difficulty of the level (as a string). Includes demon rating

downloads: Number of downloads

likes: Number of likes

disliked: If the level has a negative number of likes (true/false)

length: The length of the level (Tiny/Short/Medium/Long/XL)

stars: Amount of stars received for beating the level

orbs: Amount of mana orbs received for beating the level

diamonds: Amount of diamonds received for beating the level (stars + 2)

featured: Whether the level is featured or not

epic: Whether the level has an "epic" rating or not

version: Number of times the level was updated

copiedID: The original level ID, if the level was copied. Otherwise returns 0

officialSong: The level number of the song, if no custom song is used. Otherwise returns 0

customSong: The ID of the song, if a custom song was used. Otherwise returns 0

coins: Number of user coins placed in the level

verifiedCoins: Whether these coins are verified or not

starsRequested: How many stars the author requested the level to be rated. 0 if no request was given

objects: The number of objects in the level. This was added in a recent version of GD, so older levels will simply return 0

large: Whether the level is considered "large" (more than 40k objects)

cp: How many creator points the level is worth (1 for star rating, 1 for feature, and 1 for epic rating)

difficultyFace: The URL of the difficulty face image for this level. Plug it into gdbrowser.com/difficulty/{difficultyFace}.png

songName: The name of the song used for the level

songAuthor: The name of the author of said song

songSize: The size of the song in megabytes, if a custom song was used

songID: The ID of the song (again). If a non-custom song was used, this will return a string with the level number of the song

demonList: The level's position on the Demon List (Pointercrate). Extreme demons only

uploaded: Time since the level was uploaded (sent as "x days/weeks/months" ago, since it's all the API sends)

updated: Time since the level was last updated

password: The password to copy the level. 0 means the level isn't copyable and 1 means it's free to copy

ldm: If the level contains a checkbox for Low Detail Mode

data: The actual data of the level. Don't ask how to use it, because I have no idea


Example

Example Request

/api/level/4284013

(the ID for Nine Circles by Zobros)


Example Response

...


Profiles

/api/profile/username-or-id


Unlike the Geometry Dash API, both username and ID can be used to fetch a user profile.


Parameters (0)

No parameters for this one!


Response (28)

username: The name of the player

playerID: The unique ID for all accounts

accountID: An additional ID for registered accounts

rank: The global rank of the player. Returns 0 if banned or star count is too low

stars: Number of stars the player has

diamonds: Number of diamonds

coins: Number of secret coins

userCoins: Number of user coins

demons: Number of completed demons

cp: Number of creator points

friendRequests: If the player has friend requests enabled

messages: If the player has messages enabled. Returns "all", "friends", or "off"

commentHistory: If the player has a visible comment history. Returns "all", "friends", or "off"

moderator: If the player is a moderator. Returns 0 (none), 1 (mod) or 2 (elder)

youtube: The URL of the player's YouTube channel, if linked. Plug it into https://youtube.com/channel/{youtube}

twitter: The URL of the player's Twitter account, if linked. Plug it into https://twitter.com/{twitter}

twitch: The URL of the player's Twitch account, if linked. Plug it into https://twitch.tv/{twitch}

glow: If the player's icon has a glow or not

icon, ship, ball, ufo, wave, robot, spider, col1, col2, deathEffect: The number of the icon/color used for each form. The actual icon needs to be manually constructed. My Online Icon Kit could be of assistance.


Example

Example Request

/api/profile/robtop

(fetches the user named RobTop)


Example Response

...


Searching

/api/search/search-query


Use an asterisk (*) as your search query if you do not wish to search by level name (if you intend on using filters)


Parameters (17)


Response*


Examples

Leaderboards

/api/leaderboard

Simply returns the top player leaderboard


Parameters (3)

count: The amount of players to list (default is 100, max is 5000, does not work with accurate leaderboard)

creator: Fetches the creator leaderboard

accurate: Fetches the accurate leaderboard


Response (9)

The API will return an array of each player with the following information:

rank: Position on the leaderboard

username: The player's username

playerID: The player's ID

stars: Number of stars the player has

demons: Number of completed demons

cp: Number of creator points

coins: Number of secret coins

usercoins: Number of user coins

diamonds: Number of diamonds


Examples

Example Requests

/api/leaderboard?count=10 (Fetches the top 10 players)

/api/leaderboard (Fetches the top 100 players)

/api/leaderboard?creator&count=250 (Fetches the top 250 creators)


Example Response

(first example used)

...


Level Leaderboards

/api/leaderboardLevel/levelID

Returns the leaderboard for a level


Parameters (2)

count: The amount of players to list (default is 100, max is 200)

week: Whether or not to fetch the weekly leaderboard instead of the regular one


Response (6)

The API will return an array of each player with the following information:

rank: Position on the leaderboard

username: The player's username

playerID: The player's ID

accountID: The player's account ID

percent: Percent on the level

coins: Number of coins obtained (0-3)

date: Time since score was submitted (sent as "x days/weeks/months" ago, since it's all the API sends)


Example

Example Request

/api/leaderboardLevel/1063115 (Fetches the leaderboard for Dynamic on Track)


Example Response

...


Comments and Profile Posts

/api/comments/level-or-user-ID

Returns up to 10 comments or profile posts


Parameters (3)

top: Whether or not to sort by most liked (comments only)

page: The page of the search

type: The type of comments to fetch. Instead of a level ID, they require a player and account ID, respectively.

• commentHistory - All the comments from a player, if public on their profile

• profile - A player's profile posts


Response (10)

The API will return an array of each comment with the following information.
Values that don't work for profile posts are in red

content: The comment text

ID: The ID of the comment (used for liking and deleting)

likes: The number of likes the comment has

date: Time since the comment was posted (sent as "x days/weeks/months" ago, since it's all the API sends)

levelID: The ID of the level

browserColor: If the comment was posted through GDBrowser

username: The commenter's username

playerID: The commenter's ID

accountID: The commenter's account ID

form: The form of the commenter's icon

percent: The commenter's percent on the level, if provided

modColor: If the commenter is an elder mod and gets fancy green text


Examples

Example Requests

/api/comments/26681070?top (Fetches Sonic Wave's most liked comments)

/api/comments/16?type=commentHistory (Fetches RobTop's comment history)

/api/comments/4170784?type=profile (Fetches Serponge's profile posts)


Example Response

(first example used)

...

Level Analysis

/api/analyze/levelID

Analyzes a level's data

Level analysis is updated a lot so there may be changes in the future


Parameters (0)

No parameters for this one!


Response (12)

Response is subject to change in the future

The API will return an array of each player with the following information:

level: Basic level info (name, ID, author, etc)

settings: The level's settings (song offset, starting form/speed, two player mode, font, etc)

portals: A string listing the order of all the portals in the level + their percent. Does not include starting form/speed

orbs: How many of each jump ring is in the level

triggers: How many of each trigger is in the level

blocks: How many of each block type is in the level

triggerGroups: How many of each group ID is in the level

misc: Amount of objects that aren't categorized above (glow, arrows, clouds, pickups, etc)

colors: The level's initial color channels. Contains channel, R, G, B, opacity, player color, blending, and copied channel

text: An array of all the text objects in a level. ([text, percent])

dataLength: How long the level data is (spoilers - very)

data: The decrypted data of the level. And it's freakin' huge


Commenting

POST: /api/postComment

Leaves a comment on a level. This one is a POST request!

*Commenting has a rate limit of 10 seconds


Parameters (6)

comment: The content of the comment

username: Your username

accountID: Your account ID

password: Your password (as plain text)

levelID: The ID of the level to comment on

percent: The percent shown on the comment (optional)

color: If the comment should have a special pink color on GDBrowser (optional)


Example

Example Request

POST /api/postComment
?comment=This is a nifty comment!
&username=colon
&accountID=106255
&password=KitsuneColon333
&levelID=21448270
&percent=69

If a status of 200 is returned, then the comment was successfully posted. Otherwise, a 400 will return with an error message.

Profile Posting

POST: /api/postProfileComment

Leaves a profile post. This one is a POST request!


Parameters (5)

comment: The content of the profile post

username: Your username

accountID: Your account ID

password: Your password (as plain text)

color: If the comment should have a special pink color on GDBrowser (optional)


Example

Example Requests

POST /api/postProfileComment
?comment=Update 2.0 is revolution!
&username=viprin
&accountID=2795
&password=CopyAndPasteTurnsMeOn

If a status of 200 is returned, then the profile post was successfully posted. Otherwise, a 400 will return with an error message.

Liking

POST: /api/like

Likes/dislikes level, comment, or post. This one is a POST request!


Parameters (6)

ID: The ID of the item to like. This should be a level ID, comment ID, or profile post ID

like: Whether to like or dislike the level. 1=like, 0=dislike

type: The type of item you're liking. 1=level, 2=comment, 3=profile post

extraID: An extra ID. This should be the level ID for comments, the account ID for profile posts, or "0" for levels

accountID: Your account ID

password: Your password (as plain text)


Example

Example Request

Drop a like on RobTop's popular "can you handle the kappa" comment:

POST /api/like
?id=42602304 (ID of the comment)
&like=1 (thumbs up)
&type=2 (liking a comment)
&extraID=7485599 (ID of Kappaclysm)
&accountID=106255
&password=KitsuneColon333

A status of 200 will return if everything goes well, otherwise a 400 will return with an error message.
Liking a comment multiple times on the same account will return a 200, but not actually increase the in-game like counter.

Messages

POST:
/messages (fetches messages, includes subject but not actual content. blame robtop)
/messages/messageID (reads a message)
/deleteMessage (deletes a message)
/sendMessage (sends a message)

I decided to put all 4 of these requests in one section because they're fairly similar ¯\_(ツ)_/¯


Parameters

All:

accountID: Your account ID

password: Your password (as plain text)


/messages:

page: The page of the search

sent: Set to 1 or true to fetch your sent messages

count: Set to 1 or true to fetch your number of unread messages


/deleteMessage:

id: The ID of the message to delete, or an array of multiple IDs


/sendMessage:

targetID: The account ID of the message recipient

subject: The subject of the message, max 50 characters

message: The content of the message, max 300 characters

color: If the message should have a special pink color on GDBrowser (optional)


Example

Example Request

Fetch your messages:

POST /messages
?page=0
&accountID=106255
&password=KitsuneColon333

Read message with ID of 177013:

POST /messages/177013
?accountID=106255
&password=KitsuneColon333

Delete message with ID of 177013:

POST /deleteMessage
?accountID=106255
&id=177013
&password=KitsuneColon333

Send "Hello!" to Tubular9:

POST /deleteMessage
?accountID=106255
&password=KitsuneColon333
&subject=Message for you
&message=Hello!
&targetID=10760804 (Account ID of Tubular9)

A status of 200 will return if everything goes well, otherwise a 400 will return with an error message.
Deleting a message ID that doesn't exist will still return a 200 but won't do anything.

Icons

/icon/username

Gets a player's GD icon, or builds a custom one (Sent as a PNG)

This one isn't really part of the API, but dammit, my website my rules


Parameters (6)

Parameters can be used to modify parts of a fetched user's icon

IDs generally correspond to their order of appearance in GD

form: The form of the icon (cube/ship/ball/ufo/wave/robot/spider/cursed)

icon: The ID of the icon to use

col1: The ID of the primary color to use

col2: The ID of the secondary color to use

glow: If the icon should have a glow/outline (0 = off, anything else = on)

noUser: Disables fetching the icon from the GD servers. Slightly faster, but comes at the cost of having to build icons from the ground up using the parameters listed above. It completely ignores the entered username and always returns the default icon


Response (1)

A lovely PNG of the icon you fetched!


Examples

Sample Icons

/icon/colon (Colon's beautiful icon)

/icon/colon?form=ship (Colon's beautiful ship)

/icon/colon?col1=5&col2=3 (Colon's beautiful icon, but it's blue)

/icon/colon?icon=98&col1=40&col2=12&glow=0 (Colon's beautiful icon, but edited to a familiar face)

^since practically all the values are being changed for that last one, it's a good idea to use the noUser parameter