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 (47)
*Values that require a download are in red and values that only work with daily/weekly levels are blue
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)
playerID: The unique player 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
twoPlayer: If the level has two player mode enabled
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/assets/difficulties/{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
songLink: The link to the raw MP3 of the song, if available
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
editorTime: The amount of seconds spent in the editor (currently only works when using GDBrowser locally)
totalEditorTime: The amount of seconds spent in the editor, including time from the level it was copied from
ldm: If the level contains a checkbox for Low Detail Mode
weekly: If the values below represent the weekly demon rather than the daily level
dailyNumber: Which daily/weekly the level is (e.g. 1000th daily level)
nextDaily: The amount of seconds until the daily/weekly level expires
nextDailyTimestamp: The Unix timestamp for when the daily/weekly level expires
extraString: An unknown data string
data: The actual data of the level, compressed with GZIP
Example
Example Request
/api/level/4284013
(the ID for Nine Circles by Zobros)
Example Response
Loading...
/api/profile/username-or-id
Unlike the Geometry Dash API, both username and ID can be used to fetch a user profile.
Parameters (1)
player: Forces the player ID to be used for fetching (normally Account ID is tried first)
Response (30)
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
col1RGB, col2RGB: The RGB color values for each player color
Example
Example Request
/api/profile/robtop
(fetches the user named RobTop)
Example Response
Loading...
/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 (19)
Buckle up... there's a lot
Params that require a number (e.g. ?page=1)
count: The amount of levels to list (default is 10, max is 500)
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. ?featured=yes or ?featured)
list: Reads and returns a custom list of levels (search query should be a comma seperated list of IDs)
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
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, gdworld
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/186646,13519,55520?list=1 (Searches for the levels in Demon Pack 3)
/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/*?gauntlet=3 (Fetches the Poison Gauntlet)
Example Response
(first example used)
Loading...
/api/leaderboard
Returns the top player, creator, and accurate leaderboards
Parameters (6)
*Values that only work with the accurate leaderboard are in red
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: The type of stat to sort by (stars, coins, diamonds, or demons)
mod: Restricts the leaderboard to GD mods only
gd: Formats the leaderboard using GD's number:value syntax (for use in GD)
Response (10)
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
icon: The icon preview showed next to the player's name
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)
Loading...
/api/mappacks or /api/gauntlets
Returns the list of map packs or gauntlets
I'm putting this in the same section because they're basically the same lol
Parameters (0)
No parameters for this one!
Response (8)
*Values in blue are used in gauntlets, everything else is exclusive to map packs
id: The ID of the map pack, or index/type of the gauntlet
name: The name of the pack. Note that Gauntlet names are hardcoded by GD and may be inaccurate for edited private servers
levels: An array of level IDs in the pack. Fetch with /search/ using the ?list parameter
stars: The amount of stars rewarded for completing the map pack
coins: Basically the only reason people play map packs LOL
difficulty: The (usually inaccurate) difficulty face of the map pack
barColor: The RGB color of the pack's progress bar
textColor: The RGB color of the pack's name
Example
Example Request
/api/mappacks
Example Response
Loading...
/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 (7)
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)
icon: The icon preview showed next to the player's name
Example
Example Request
/api/leaderboardLevel/1063115 (Fetches the leaderboard for Dynamic on Track)
Example Response
Loading...
/api/comments/level-or-user-ID
Returns up to 10 comments or profile posts
Parameters (4)
page: The page of the search
top: Whether or not to sort by most liked (comments only)
count: The number of comments/posts to list (default is 10, max is 1000)
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 (16)
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 player ID
accountID: The commenter's account ID
percent: The commenter's percent on the level, if provided
color: The RGB font color of the comment. Note that the yellow author text is not included
moderator: If type of moderator the commenter is. Returns 0 (none), 1 (mod) or 2 (elder, green text)
icon: The icon preview showed next to the commenter's name
results: The total number of comments (first comment only, doesn't work with comment history)
pages: The total number of pages, starting at 1
range: The index of comments that were fetched
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)
Loading...
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.
/api/song/songID
Checks if a song is allowed for use
For a song to be useable, the artist must be scouted on Newgrounds and the song must be enabled for external use.
If the song was published after March 2017, the artist must also be whitelisted by a GD moderator.
Parameters (0)
No parameters for this one!
Response (1)
literally just returns true or false (or -1 if there's an error)
there used to be more but rob disabled his song api sooo
/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 the following information about the level:
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
/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 (11)
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/swing/cursed)
icon: The ID of the icon to use
col1: The ID or hex code of the primary color to use
col2: The ID of hex code the secondary color to use
colG: Optional color ID or hex code to overwrite the glow for the icon
colW: Optional color ID or hex code to overwrite the 'white' layer used by some detailed icons
glow: If the icon should have a glow/outline (0 = off, anything else = on)
size: The size in pixels that the icon should be (always square), in case you don't want the default. "auto" also works.
topless: Removes the glass 'dome' from generated UFOs (legacy)
player: Forces the player ID to be used for fetching (normally Account ID is tried first)
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
psd: Saves the icon as a layered .psd file (spiders + robots not supported since they still use the old icon code)
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
