Eng:Scratch API (1.4)

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. The Scratch Modification Panther works for this.

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, the project ID parameter is available. If multiple parameters are accepted, such as with, they are usually separated by slashes. An exception is, 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, redirect to a page on the website.


 * Plain text output
 * Some APIs print a plain value., 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.


 * JSON
 * JSON stands for JavaScript Object Notation. The basic syntax is . An example is.

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: It outputs in the format of: project creator:project ID
 * gallery 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: It outputs in the format of: author_ID:name:description:created:tags:country:loveit:num_favoriters:remixer:remixes:numberOfSprites:totalScripts:numberofcomments:numberofdownloads
 * project ID (one or more project IDs)

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

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: It outputs in the format of: author_ID:name:description:totalproject:usgae:staus,visibility:created
 * gallery ID (one or more gallery IDs)

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: It outputs in the format of: author_ID:comment_ID:reply_to_comment_ID,createddate:comment
 * project ID

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: It outputs in the format of: project_ID:project_ID
 * user 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: It outputs in the format of: pcomment ID,user_ID,content,created date
 * user ID1, user_ID2

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"}}]