This is the documentation for the
The
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
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 /postComment (POST)
Profile Posting /postProfileComment (POST)
Messages /messages (4 different POSTs)
Liking /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
If by any chance you use this API for other projects, credit is greatly appreciated!
/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
gameVersion: The version of GD the level was released on (1.9, 2.1, etc)
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
...
/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 can be generated through /icon
Example
Example Request
/api/profile/robtop
(fetches the user named RobTop)
Example Response
...
/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 (18)
Buckle up... there's a lot
Params that require a number (e.g. ?page=1)
count: The amount of levels to list (default and max is 10)
diff: The number of the difficulty to search for, see difficulty IDs below
demonFilter: If searching for demon levels, what difficulty to search for (1 is easy, 5 is extreme)
page: The page of the search
gauntlet: The number of the gauntlet to view (will return the 5 levels)
length: Only return levels with this length (0-4, 0 is tiny and 4 is XL)
songID: Only return levels that use this official song number (2-21, unless you want hacked levels with songs from meltdown/subzero/etc. Also, Stereo Madness and Back on Track don't seem to work). Add the 'customSong' parameter to read the number as a custom song ID.
Params that require a string (e.g. ?type=trending)
type: The type of search to perform, see search types below
creators: A comment seperated list of account IDs. Only levels by those players will be returned
Params that require anything (e.g. ?mappack=yes or ?mappack)
featured: Only return featured levels
original: Only return non-copied levels
twoPlayer: Only return two player mode levels
coins: Only return levels with verified coins
epic: Only return levels with an epic rating
starred: Only return levels with a star rating
noStar: Only return levels without a star rating
customSong: Reads the 'song' parameter as a custom song ID instead of an official one
mappack: Reads the search query as the name of a map pack and returns the 3 levels if pack exists
user: Reads the search query as a player's ID and returns their levels
Search Types
All types ignore your search query and will return levels with any name.
Filters allowed: mostdownloaded, mostliked, trending, recent, awarded
Filters ignored: featured, magic, halloffame
Difficulty IDs
1-5: Easy to insane, multiple can be selected (separate with commas)
-2: Demon (use demonFilter for a specific difficulty)
-3: Auto
-1: N/A
Response*
The response for searching is an array of up to 10 level objects
If the page is set to 0, the first level object will also display the number of pages and search results.
Since RobTop is a ploopy this only works on the first page, and may sometimes just display 9999 results.
Examples
Example Requests
/api/search/abc (Searches for a level named "abc")
/api/search/zodiac?diff=-2&demonFilter=5 (Searches for an extreme demon named "Zodiac"
/api/search/*?diff=-3 (Searches for any auto levels, regardless of name)
/api/search/*?type=trending&noStar (Searches for trending levels without a star rating)
/api/search/demon pack 1?mappack (Fetches Demon Pack 1)
/api/search/*?gauntlet=3 (Fetches the Poison Gauntlet)
Example Response
(first example used)
...
/api/leaderboard
Simply returns the top player leaderboard
Parameters (4)
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
type: Accurate leaderboard only - the type of stat to sort by (stars, coins, or demons)
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)
...
/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
...
/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
moderator: If type of moderator the commenter is. Returns 0 (none), 1 (mod) or 2 (elder, 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)
...
/api/analyze/levelID
Analyzes a level's data
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
POST: /postComment
Leaves a comment on a level. This one is a POST request!
*Commenting has a rate limit of 15 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 /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.
POST: /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 /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.
POST: /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 /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.
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 /sendMessage
?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.
/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 (7)
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)
size: The size (in pixels) the icon should be, in case you don't want the default. Will always be square
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