This article has links to websites or programs outside of Scratch and Wikipedia. Remember to stay safe while using the internet, as we cannot guarantee the safety of other websites. |
This article or section documents something not included in the current version of Scratch (3.0). It is only useful from a historical perspective. |
- This article or section documents an outdated version of Scratch (version 1.4). For this article in the current version (version 3.0), see Scratch API (3.0).
The Scratch API is a relatively simple way for sites not using the Scratch Website to access information about the website. There is no official documentation, but the source contains comments, explaining the way to use them.
There are 28 APIs. They access data about projects, users, galleries, and statistics.
Use
The API is used by downloading the content of the page. This can be done in any programming language that can read the source of web pages, such as Panther.
The page to be accessed is https://scratch.mit.edu/api/[apiname]/[parameters]. [apiname] is the name of the API. [parameters] are variables that can be passed to the API, such as with getproject
, the project ID parameter is available. If multiple parameters are accepted, such as with getprojectinfobyID
, they are usually separated by slashes. An exception is authenticateuser
, where parameters are passed using URL variables (https://scratch.mit.edu/api/authenticateuser?username=demo&password=demo123).
Output
Different APIs have different types of output.
- Redirect
- Some APIs, such as
getuser
, redirect to a page on the website. - Plain text output
- Some APIs print a plain value.
getregisteredusers
, and other statistics APIs, are examples. - CSVs
- CSV normally stands for "comma-separated values", but the Scratch API uses colon-separated values. An example is
getprojectinfobyID
. - JSON
- JSON stands for JavaScript Object Notation. The basic syntax is
{abc: "def", array: ["xyz",{key: "value", number: 4}]}
. An example isgetprojectblocks
.
Each of these must be parsed in their own manner.
Example Uses
Some actual example uses of these APIs are presented below:
- The Scratch Forums — in automatically upgrading New Scratchers
- The Scratch Wiki and Scratch Resources — to authenticate logins
- Sparks's Scratch API, which is a user-friendly implementation of some of the official APIs
API
This is a full list of all the current Scratch APIs.
getproject
This function takes project ID as input and redirects to project page based on a project ID.
Parameters:
- project ID
For example, https://scratch.mit.edu/api/getproject/2489922 will redirect to https://scratch.mit.edu/projects/Scratch-Dach-Wiki/2489922
getprojectpath
This function takes project ID as input and print the .sb file path of a project.
Parameters:
- project ID
For example, https://scratch.mit.edu/api/getprojectpath/2489922 prints:
/projects/Scratch-Dach-Wiki/2489922.sb
getuser
This function takes user ID as input and redirects to user's my stuff page based on a user ID.
Parameters:
- user ID
For example, https://scratch.mit.edu/api/getuser/139 will redirect to https://scratch.mit.edu/users/andresmh/
getusernamebyID
This function takes user ID as input and print username.
Parameters:
- user ID
For example, https://scratch.mit.edu/api/getusernamebyID/139 prints:
andresmh
getregisteredusers
This function returns total number of registered users.
For example, https://scratch.mit.edu/api/getregisteredusers prints:
682,139
getcreators
This function returns the number of people who have created a project.
For example, https://scratch.mit.edu/api/getcreators prints:
194,830
gettotalprojects
This function returns the total number of projects uploaded by users.
For example, https://scratch.mit.edu/api/gettotalprojects prints:
1,484,878
gettotalscripts
This function returns sum of total scripts.
For example, https://scratch.mit.edu/api/gettotalscripts prints:
25,806,007
gettotalsprites
This function returns sum of number of sprites.
For example, https://scratch.mit.edu/api/gettotalsprites prints:
8,746,913
getprojectsbyusername
This function returns all ID of visible project separated with colon (:) created by a user.
Parameters:
- username
For example, https://scratch.mit.edu/api/getprojectsbyusername/ashok prints:
20805:920784:920767:920759:785614:715431:609769:608275:490870:490868:397124:371906
getfriendsbyusername
This function returns all friend ID of a user separated with colon (:).
Parameters:
- username
For example, https://scratch.mit.edu/api/getfriendsbyusername/ashok prints:
273837:261892:140467:9811:183315:82753:184712:185632:183245:184333
getgalleriesbyusername
This function returns all gallery ID created by a user separated with colon (:).
Parameters:
- username
For example, https://scratch.mit.edu/api/getgalleriesbyusername/ashok prints:
27321:24994
getinfobyusername
This function returns profile information of a user.
Parameters:
- username
It outputs in the format of:
username: ID: country
For example, https://scratch.mit.edu/api/getinfobyusername/ashok prints:
ashok:139123:India
getprojectsbygallery
This function returns all projects (creator and project ID) of a gallery. Result contains one project details per line.
Parameters:
- gallery ID
It outputs in the format of:
project creator:project ID
For example, https://scratch.mit.edu/api/getprojectsbygallery/27321 prints:
UnitedChuckVIDs:255443
getprojectinfobyID
This function returns project information. Result contains one project details per line.
Parameters:
- project ID (one or more project IDs)
It outputs in the format of:
author_ID:name:description:created:tags:country:loveit:num_favoriters:remixer:remixes:numberOfSprites:totalScripts:numberofcomments:numberofdownloads
For example, https://scratch.mit.edu/api/getprojectinfobyID/1210197 prints:
261892:Snake:Eat%20the%20fruits%2C%20and%20don%27t%20touch%20the%20walls%20or%20your%20own%20tail.%20%20Use%20the%20arrow%20keys%20to%20navigate.Get%20the%20Extra%20points%20as%20soon%20as%20u%20can.:2010-07-24%2007%3A32%3A08:game%2Cfruit%2Csnake:BD:7:3:14:15:4:9:31:24
https://scratch.mit.edu/api/getprojectinfobyID/785614/490868 prints:
139123:3%20FishChomp%20remix:Try%20to%20make%20the%20big%20fish%20eat%20the%20smaller%20fish.%0D%0DINSTRUCTIONS%0DClick%20the%20Green%20Flag%20to%20start.%20Move%20the%20mouse%20to%20control%20the%20big%20fish.%0D%0DHOW%20I%20MADE%20THIS%0D%2A%20To%20see%20whether%20the%20big%20fish%20is%20close%20enough%20to%20eat%20the%20little%20fish%2C%20I%20used%20the%20%22color%20_%20is%20over%20_%3F%22%20block%0D%2A%20The%20little%20fish%20broadcasts%20%22got%20me%22%20when%20the%20big%20fish%20gets%20close%20to%20it%2C%20which%20triggers%20the%20big%20fish%20to%20animate%20its%20mouth%20in%20an%20eating%20motion.%0D%0DMORE%20IDEAS%0D%2A%20Keep%20score%20of%20how%20many%20fish%20are%20eaten%0D%2A%20Make%20different%20kinds%20of%20fish%20%28%22good%20fish%22%20and%20%22bad%20fish%22%29:2009-04-16%2002%3A31%3A45:::::1:1:5:5:2:0 139123:FISHVILLE:this%20is%20just%20a%20prctice%20project:2009-12-02%2000%3A27%3A17:::::0:0:4::0:0
authenticateuser
This function returns user information if success and 'false'. if authentication fails.
Parameters:
- username, password
Note: | password should be encoded using rawurlencode() method. So if your password is "demo#123" you need to use password as https://scratch.mit.edu/api/authenticateuser?username=demo&password=demo%23123 where "demo%23123" is rawurlencode format of "demo#123"; %23 is equivalent to #. |
It outputs in the format of:
user_ID:username:status
For example, https://scratch.mit.edu/api/authenticateuser?username=demo&password=demo123 could print:
12345:demo: normal
getgalleryinfobyID
This function returns gallery information. Result contains one gallery details per line.
Parameters:
- gallery ID (one or more gallery IDs)
It outputs in the format of:
author_ID:name:description:totalproject:usgae:staus,visibility:created
For example, https://scratch.mit.edu/api/getgalleryinfobyID/24994 prints:
139123:scratchr:http%3A%2F%2Fscratch.mit.edu%2Fgalleries%2Fview%2F24994:0:friends:notreviewed:visible:2008-07-25%2005%3A48%3A20
https://scratch.mit.edu/api/getgalleryinfobyID/24994 prints:
139123:scratchr:http%3A%2F%2Fscratch.mit.edu%2Fgalleries%2Fview%2F24994:0:friends:notreviewed:visible:2008-07-25%2005%3A48%3A20139123:ashoks%20gallery:this%20is%20my%20gallery:1:private:notreviewed:visible:2008-08-25%2017%3A54%3A08
getnumprojectsbyuser
This function returns number of project visible/all depends on parameter onlyvisible(yes/no) created by user. By default result contains only visible projects.
Parameters:
- username
For example, https://scratch.mit.edu/api/getnumprojectsbyuser/ashok prints:
12
https://scratch.mit.edu/api/getnumprojectsbyuser/ashok?onlyvisible='no' prints:
12
getnumcommentsbyuser
This function returns number of visible comments created by user (on projects and galleries
Parameters:
- username
For example, https://scratch.mit.edu/api/getnumcommentsbyuser/ashok prints:
53620
getpcommentsbyID
This function returns all visible comments of a project. Result contains one comment details per line.
Parameters:
- project ID
It outputs in the format of:
author_ID:comment_ID:reply_to_comment_ID,createddate:comment
For example, https://scratch.mit.edu/api/getpcommentsbyID/255443 prints:
144037:897255::2008-09-02%2012%3A26%3A46:cool%20n%20gr8%2C%20only%20i%20dont%20get%20the%20end155300:898467::2008-09-02%2019%3A02%3A48:he%20get%27s%20hurt%20then%20he%20blasts%20%27em%0D%0Aoh%20and%20sorry%20it%20was%2019%20not%2018%0D%0A%28school%20just%20started%20I%27m%20losing%20my%20mind%29
getusersfavoriteprojectsbyuID
This function returns all favorite project ID of user separated with colon(:)
Parameters:
- user ID
It outputs in the format of:
project_ID:project_ID
For example, https://scratch.mit.edu/api/getusersfavoriteprojectsbyuID/261892 prints:
766560:703044
getprojectsblockscount
This function returns block count code of latest version of the project (in JSON format)
Parameters:
- project ID
For example, https://scratch.mit.edu/api/getprojectblockscount/4447 prints:
{"project_ID":"4447","project_version":"2","scratchComment":"0","KeyEventHatMorph":"0","EventHatMorph_StartClicked":"3","EventHatMorph":"2","MouseClickEventHatMorph":"1","WhenHatBlockMorph":"0","and_operator":"0","multiply_operator":"0","add_operator":"0","subtract_operator":"0","divIDe_operator":"0","isLessThan":"0","isEqualTo":"0","isGreaterThan":"0","mod_operator":"0","or_operator":"0","abs":"0","allMotorsOff":"0","allMotorsOn":"0","answer":"0","append_toList_":"0","backgroundIndex":"0","bounceOffEdge":"0","broadcast_":"1","changeBackgroundIndexBy_":"0","changeBlurBy_":"0","changeBrightnessShiftBy_":"0","changeCostumeIndexBy_":"0","changeFisheyeBy_":"0","changeGraphicEffect_by_":"2","changeHueShiftBy_":"0","changeMosaicCountBy_":"0","changePenHueBy_":"0","changePenShadeBy_":"0","changePenSizeBy_":"0","changePixelateCountBy_":"0","changePointillizeSizeBy_":"0","changeSaturationShiftBy_":"0","changeSizeBy_":"0","changeStretchBy_":"0","changeTempoBy_":"0","changeVar_by_":"0","changeVisibilityBy_":"0","changeVolumeBy_":"0","changeWaterRippleBy_":"0","changeWhirlBy_":"0","changeXposBy_":"0","changeYposBy_":"2","clearPenTrails":"0","color_sees_":"0","comeToFront":"0","comment_":"0","computeFunction_of_":"0","concatenate_with_":"0","contentsOfList_":"0","costumeIndex":"0","deleteLine_ofList_":"0","distanceTo_":"0","doAsk":"0","doBroadcastAndWait":"0","doForever":"3","doForeverIf":"0","doIf":"0","doIfElse":"0","doPlaySoundAndWait":"0","doRepeat":"0","doReturn":"0","doUntil":"0","doWaitUntil":"0","drum_duration_elapsed_from_":"0","filterReset":"0","forward_":"0","getAttribute_of_":"0","getLine_ofList_":"0","glIDeSecs_toX_y_elapsed_from_":"0","goBackByLayers_":"0","gotoSpriteOrMouse_":"0","gotoX_y_":"1","gotoX_y_duration_elapsed_from_":"0","heading":"0","heading_":"1","hIDe":"2","hIDeVariable_":"0","insert_at_ofList_":"0","isLoud":"0","keyPressed_":"0","letter_of_":"0","lineCountOfList_":"0","list_contains_":"0","lookLike_":"0","mIDiInstrument_":"0","motorOnFor_elapsed_from_":"0","mousePressed":"0","mouseX":"0","mouseY":"0","nextBackground":"0","nextCostume":"0","not":"0","noteOn_duration_elapsed_from_":"0","penColor_":"0","penSize_":"0","playSound_":"1","pointTowards_":"0","putPenDown":"0","putPenUp":"0","randomFrom_to_":"0","rest_elapsed_from_":"0","rewindSound_":"0","readVariable":"0","rounded":"0","say_":"3","say_duration_elapsed_from_":"0","sayNothing":"0","scale":"0","sensor_":"0","sensorPressed_":"0","setBlurTo_":"0","setBrightnessShiftTo_":"0","setFisheyeTo_":"0","setGraphicEffect_to_":"0","setHueShiftTo_":"0","setLine_ofList_to_":"0","setMosaicCountTo_":"0","setMotorDirection_":"0","setPenHueTo_":"0","setPenShadeTo_":"0","setPixelateCountTo_":"0","setPointillizeSizeTo_":"0","setSaturationShiftTo_":"0","setSizeTo_":"0","setStretchTo_":"0","setTempoTo_":"0","setVar_to_":"0","setVisibilityTo_":"0","setVolumeTo_":"0","setWaterRippleTo_":"0","setWhirlTo_":"0","show":"2","showBackground_":"0","showVariable_":"0","soundLevel":"0","sqrt":"0","stampCostume":"0","startMotorPower_":"0","stopAll":"0","stopAllSounds":"0","stringLength_":"0","tempo":"0","think_":"0","think_duration_elapsed_from_":"0","timer":"0","timerReset":"0","touching_":"0","touchingColor_":"0","turnAwayFromEdge":"0","turnLeft_":"0","turnRight_":"3","volume":"0","wait_elapsed_from_":"4","xpos":"0","xpos_":"0","yourself":"0","ypos":"0","ypos_":"0","askYahoo":"0","wordOfTheDay_":"0","jokeOfTheDay_":"0","synonym_":"0","info_fromZip_":"0","scratchrInfo_forUser_":"0","other":""}
getprojectsblocks
This function returns human-readable code of the latest version of the project (in JSON format)
Parameters:
- project ID
For example, https://scratch.mit.edu/api/getprojectblocks/1308192 prints:
{"project_ID":"1308192","sprites":["","when I am clicked\n set \"arms\" to (pick random 4 to 20)\n set \"mini arm angle\" to (pick random 5 to 90)\n set \"mini arm length\" to (pick random 1 to 20)\n set \"mini arms\" to (pick random 1 to 4)\n set \"size\" to (pick random 10 to 150)\n set \"mainframe pen size\" to (pick random 1 to 5)\n set \"M.A. pen size\" to (pick random 1 to 5)\n\nwhen green flag clicked\n forever\n go to x: 0 y: -20\n if \n switch to costume \"costume2\"\n else\n switch to costume \"costume1\"\n\n","","when green flag clicked\n forever\n wait until \n wait until >\n go to x: 0 y: -20\n pen down\n clear\n point in direction 180\n set pen color to c[ebf7ff]\n repeat \"arms\"\n set pen size to \"mainframe pen size\"\n move (\"size\" \/ ((\"mini arms\" * 2) + 0.1)) steps\n repeat \"mini arms\"\n turn \"mini arm angle\" degrees\n set pen size to \"M.A. pen size\"\n move \"mini arm length\" steps\n move (0 - \"mini arm length\") steps\n turn (\"mini arm angle\" * 2) degrees\n move \"mini arm length\" steps\n move (0 - \"mini arm length\") steps\n turn \"mini arm angle\" degrees\n set pen size to \"mainframe pen size\"\n move (\"size\" \/ ((\"mini arms\" * 2) + 0.1)) steps\n go to x: 0 y: -20\n turn (360 \/ \"arms\") degrees\n\n","when green flag clicked\n go to x: 0 y: 0\n forever\n change y by -2\n wait 0 secs\n set x to 0\n if <(y position) < \"-318\">\n set y to 360\n\n","when green flag clicked\n go to x: 0 y: 360\n forever\n change y by -2\n wait 0 secs\n set x to 0\n if <(y position) < \"-318\">\n set y to 360\n\n"]}
get_latest_project
This function returns latest project uploaded by scratch user (in JSON format)
Parameters:
- authentication_key, number of project required (default 1).
For example, https://scratch.mit.edu/api/get_latest_project/XXXXXXXXXXXXX prints:
[{"project":{"ID":"13","projectName":"bus","thumbnailUrl":"http:\/\/scratch.mit.edu\/static\/projects\/demo\/13_sm.png","uplodedIpAddress":"8.8.8.8","shortCountryName":"CN","longCountryName":"China","url":"http:\/\/scratch.mit.edu\/projects\/demo\/13","created":"2 days, 1 hour"}}]
getblockcountpercategorybyuserID
This function returns category wise no.of blocks used by a user (in JSON format)
Parameters:
- user_ID
For example, https://scratch.mit.edu/api/getblockcountpercategorybyuserID/139 prints:
{"Control":{"total":17,"used":15},"Operators":{"total":19,"used":8},"Sensing":{"total":17,"used":4},"Variables":{"total":13,"used":3},"Looks":{"total":47,"used":15},"Motion":{"total":18,"used":11},"Sounds":{"total":14,"used":6}}
getblockcategorycountbypID
This function returns category wise no.of blocks used in a project (in JSON format)
Parameters:
- pID
For example, https://scratch.mit.edu/api/getblockcategorycountbypID/12339 prints:
{"Control":{"total":17,"used":3},"Operators":{"total":19,"used":2},"Sensing":{"total":17,"used":1},"Looks":{"total":47,"used":1}}
get_remixed_project
This function returns latest remixes (in JSON format)
Parameters:
- number of project required (default 1).
For example, https://scratch.mit.edu/api/get_remixed_project prints:
[{"project":{"ID":"13","projectName":"bus","thumbnailUrl":"http:\/\/scratch.mit.edu\/static\/projects\/demo\/13_sm.png","shortCountryName":"CN","longCountryName":"China","region":"Jiangsu","city":"Nanjing","url":"http:\/\/scratch.mit.edu\/projects\/demo\/13","created":"1 week"},"basedOn":{"ID":"12","projectName":"bus","thumbnailUrl":"http:\/\/scratch.mit.edu\/static\/projects\/ashok\/12_sm.png","shortCountryName":"BR","longCountryName":"Brazil","region":"Minas Gerais","city":"Belo Horizonte","url":"http:\/\/scratch.mit.edu\/projects\/ashok\/12","created":"1 month, 1 week"}}]
getuserspcommentsbyuID
This function returns all pcomments that A has posted on B in JSON format
Parameters:
- user ID1, user_ID2
It outputs in the format of:
pcomment ID,user_ID,content,created date
For example, https://scratch.mit.edu/api/getuserspcommentsbyuID/2/3 prints:
[{"Pcomment":{"ID":"101","user_ID":"2","content":"just for test now","created":"2011-02-02 15:38:19"}},{"Pcomment":{"ID":"58","user_ID":"2","content":"yes big bus","created":"2010-04-29 05:32:04"}},{"Pcomment":{"ID":"57","user_ID":"2","content":"big bus","created":"2010-04-29 05:31:30"}},{"Pcomment":{"ID":"56","user_ID":"2","content":"first comment","created":"2010-04-29 05:31:16"}},{"Pcomment":{"ID":"47","user_ID":"2","content":"hey this one another comment!!!!!!!!!!","created":"2009-11-30 10:56:24"}},{"Pcomment":{"ID":"46","user_ID":"2","content":"comment on demo's project","created":"2009-11-30 10:54:46"}},{"Pcomment":{"ID":"45","user_ID":"2","content":"http:\/\/scratch.mit.edu\/forums\/viewtopic.php?pID=231636#p231636","created":"2009-09-29 06:24:24"}},{"Pcomment":{"ID":"44","user_ID":"2","content":"http:\/\/scratch.mit.edu\/projects\/-db-\/666150","created":"2009-09-29 06:06:43"}}]