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
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 (35)
*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
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 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
...
/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)
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
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
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 (3)
count: The amount of players to list (default is 100, max is 2500, 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)
...
/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
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 [COMMENT HISTORY ONLY]
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)
...
/api/leaderboardLevel/levelID
Analyzes a level's data
Level analyzing is still a big WIP so there may be changes in the future
Parameters (0)
No parameters for this one!
Response (?)
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)
portals: A string listing the order of all the portals in the level. 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
misc: Amount of objects that aren't categorized above (glow, arrows, clouds, pickups, etc)
settings: The level's settings (song offset, starting form/speed, two player mode, font, etc)
colors: The level's initial color channels. Contains channel, R, G, B, opacity, player color, blending, and copied channel
dataLength: How long the level data is (spoilers - very)
data: The decrypted data of the level. And it's freakin' huge