SandCastleIcon.png 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.
Archive.png 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 is getprojectblocks.

Each of these must be parsed in their own manner.

Example Uses

Some actual example uses of these APIs are presented below:

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

See Also

External Links

Cookies help us deliver our services. By using our services, you agree to our use of cookies.