Introduction

ScratchAPI is a simple Java interface to the Scratch 2.0 website. It is not nearly done yet, and will later include several features, but it takes time. :P

If you want to see a list of features to be added, click here > #1 Also, if you're wondering why everything is indented with 8-width tabs, it's because GitHub is being irritating. They are supposed to be 4 spaces.

Documentation

Jump to Section

• Session Management
• Users
• Projects
• Cloud Data Management
• Statistics
• Miscellaneous
• Exceptions

---

Session Management

Create a user session and log in:

ScratchSession session = Scratch.createSession("username", "password");

Register a new user (might now work, but it might! Try it out!):

ScratchSession session = Scratch.register("username", "password", "gender", birthMonth, "birthYear", "location", "the@email.here"); // All fields case sensitive-- to be documented better later...

Get information about the session:

String username = session.getUsername();
String csrftoken = session.getCSRFToken();
String expiration = session.getExpiration();
String sessionid = session.getSessionID();
ScratchCloudSession cloudSession = session.getCloudSession(projectid); // Cloud sessions are documented a while down
ScratchUser user = session.you();

Log session out:

session.logout();

---

Users

Create a user instance:

ScratchUser user = new ScratchUser("username");

Get information about user:

user.update(); // Run this first! It updates the info about the user.
String username = user.getUsername();
String status = user.getStatus();
String bio = user.getBio();
String country = user.getCountry();
Date joinDate = user.getJoinDate();
int messageCount = user.getMessageCount();
List<ScratchProject> favoriteProjects = user.getFavoriteProjects(limit, offset); // limit max 20

Follow and unfollow the user:

user.setFollowing(session, true); // Follow user
user.setFollowing(session, false); // Unfollow user

Comment on user profile:

user.comment(session, "Example comment"); // You can't comment too fast, remember the delay

---

Projects

Create a project instance:

ScratchProject project = new ScratchProject(projectid); // 'projectid' is an int

Get information about project:

project.update(); // Run this before everything else
String title = project.getTitle();
String description = project.getDescription();
ScratchUser creator = project.getCreator();
int viewCount = project.getViewCount();
int loveCount = project.getLoveCount();
int favoriteCount = project.getFavoriteCount();
int projectid = project.getProjectID();
ScratchProjectManager manager = project.getProjectManager(); // Useless as of now
String resourceurl = project.getResourceURL();
String shareDate = project.getShareDate();
String thumbnailurl = project.getThumbnailURL();

Love and unlove the project:

project.setLoved(session, true); // Love project
project.setLoved(session, false); // Unlove project

Favorite and unfavorite the project:

project.setFavorited(session, true); // Favorite project
project.setFavorited(session, false); // Unfavorite project

Comment on project:

project.comment(session, "Example comment"); // You also can't comment too fast, remember the delay

---

Cloud Data Management

Create a cloud session:

ScratchCloudSession cloudSession = session.getCloudSession(projectid);

Add and remove a cloud event listener:

ScratchCloudListener listener = new ScratchCloudListener() {
    public void onSet(int projectID, String name, String value) {
        // insert code here...	
    }
    
    // Later TODO add onEnd
}

cloudSession.addCloudListener(listener); // add
cloudSession.removeCloudListener(listener); // remove

Get the cloud symbol (☁):

char cloudSymbol = Scratch.CLOUD;

Get information about cloud session:

int projectid = cloudSession.getProjectID();
ScratchSession session = cloudSession.getScratchSession();
String cloudToken = cloudSession.getCloudToken();

Get a list of cloud variables:

List<String> variables = cloudSession.getVariables();

Get a cloud variable's contents:

String contents = cloudSession.get(Scratch.CLOUD + " variable"); // The space is needed!

Set a cloud variable's contents:

cloudSession.set(Scratch.CLOUD + " variable", "new value"); // Strings should work...

Rename a cloud variable (untested):

cloudSession.rename(Scratch.CLOUD + " variable", Scratch.CLOUD + " new name");

Create a cloud variable (untested):

cloudSession.create(Scratch.CLOUD + " newVariable", "value");

Delete a cloud variable (untested):

cloudSession.delete(Scratch.CLOUD + " variable");

Close the cloud session:

cloudSession.close();

---

Statistics

Get total project count:

 // Updates every 24hrs (thanks @thisandagain)
 
int totalProjectCount = ScratchStatistics.getProjectCount();
int totalStudioCount = ScratchStatistics.getStudioCount();
int totalUserCount = ScratchStatistics.getUserCount();
int totalCommentCount = ScratchStatistics.getCommentCount();
Date timestamp = ScratchStatistics.getTimestamp(); 

---

Miscellaneous

Set the default User-Agent:

Scratch.setUserAgent("insert User-Agent here");

Get a list of Scratch users:

List<ScratchUser> users = Scratch.getUsers(limit, offset); // Max limit is 20

---

Exceptions

List of exceptions:

edu.mit.scratch.exceptions.ScratchException
edu.mit.scratch.exceptions.ScratchLoginException
edu.mit.scratch.exceptions.ScratchUserException
edu.mit.scratch.exceptions.ScratchProjectException
edu.mit.scratch.exceptions.ScratchStatisticalException

Examples

Follow yourself and kaj

new ScratchUser(session.getUsername()).setFollowing(session, true); // Yourself
new ScratchUser("kaj").setFollowing(session, true); // Kaj

---

Open alert dialog when you get a message

final String user = "griffpatch"; // Change this to your username!
		
Timer timer = new Timer();
timer.schedule(new TimerTask() {
	public ScratchUser target = new ScratchUser(user);
	public int previous = -1;
	
	@Override
	public void run() {
		try {
			int count = target.getMessageCount();
			if(previous == -1) {
				previous = count; // This means the program just started.
			} else 
				if(count > previous) {
					previous = count;
					javax.swing.JOptionPane.showMessageDialog(null, "The account " + user + " on Scratch now has " + count + " messages.");
				}
		} catch (Exception e) {
			e.printStackTrace();
		}
	}
}, 0, 5 * 1000); // Updates every 5 seconds

Warning: if you are famous, the number of dialogs from your messages will seriously get annoying.