Usage of the API

How to use it.

Getting Started

To get started, create a new Maven project and add this repository:

<repository>
      <id>FluentCoding-smmdb-api</id>
      <url>https://packagecloud.io/FluentCoding/smmdb-api/maven2</url>
</repository>

... and the dependency:

<dependency>
      <groupId>io.fluentcoding</groupId>
      <artifactId>smmdb-api</artifactId>
      <version>LATEST</version>
</dependency>

If you prefer using Gradle then add the dependency like this:

repositories {
      // ...
      maven {
        url "https://packagecloud.io/FluentCoding/smmdb-api/maven2"
      }
}
// ...
compile 'io.fluentcoding:smmdbapi:LATEST'

If you don't prefer using a software project management tool then you can also just add the jar as an dependency.

Notice that adding the JAR manually doesn't guarantee full compatibility with the api as the api needs to be updated when the main api is also changed.

After adding the dependency you should be ready to get started with using the API!

Usage of the API

Filter and get courses

To filter the courses you want to get, instantiate an object of the class CourseRequestParams by executing the factory method:

Example

CourseRequestParams params = CourseRequestParams.createCourseRequestParams();

After the instantation of this object you can access the methods of this object which help you filtering the courses. These are listed here:

Method

Description

setOrder(Order)

Sets the priority on an attribute.

setDirection(Direction)

Defines the direction for an alphabetical order.

setLimit(Byte)

Limits the maximum amount of sent courses. (max: 120)

setStart(Integer)

Start index for pagination.

setTimeFrom(Integer)

Course completion time lower limit in seconds.

setTimeTo(Integer)

Course completion time upper limit in seconds.

setWidthFrom(Integer)

Course width lower limit in block.

setWidthTo(Integer)

Course width upper limit in block.

setWidthSubFrom(Integer)

Subcourse width lower limit in block.

setWidthSubTo(Integer)

Subcourse width upper limit in block.

setRandom(Boolean)

Receive random courses wrt filters.

setIds(String[])

Return only courses with specific id.

setLastModifiedFrom(Date)

Unix timestamp lower limit for lastmodified value.

setLastModifiedTo(Date)

Unix timestamp upper limit for lastmodified value.

setUploadedFrom(Date)

Unix timestamp lower limit for uploaded value.

setUploadedTo(Date)

Unix timestamp upper limit for uploaded value.

setDifficultyFrom(Difficulty)

Difficulty setting lower limit.

setDifficultyTo(Difficulty)

Difficulty setting upper limit.

setTitle(String)

Title's substring, case-insensitive.

setMaker(String)

Maker's exact name, case-insensitive.

setUploader(String)

Uploader's exact name, case-insensitive.

setGameStyle(GameStyle)

Game style of course.

setCourseTheme(CourseTheme)

Course theme.

setCourseThemeSub(CourseTheme)

Subcourse theme.

setAutoScroll(AutoScroll)

Auto scroll speed.

setAutoScrollSub(AutoScroll)

Auto scroll speed of sub course

For getting the courses you first need to access the singleton object SMMDBApi.INSTANCE and then you are able to choose one of these methods you want to call:

Method

Description

getCourses(CourseRequestParams)

Gets the courses of the SMMDB-Server filtered

getCourses(String)

Gets the courses of the SMMDB-Server with the attribute if the player has starred (⭐) the respective levels.

getCourses(CourseRequestParams, String)

Gets the courses of the SMMDB-Server filtered with the attribute if the player has starred (⭐) the respective levels.

Analogous to that you can also add the suffix "64" for accessing courses which are playable in Super Mario Maker 64. Calling the above methods returns a list of course-pojos (objects) which allow you to get detailed information about the course like the id, the maker, the upload date and so on. Here is one example: I'm getting here a list of 6 courses with the game style of Super Mario Bros 3.:

public static void main(String[] args) {
    try {
        CourseRequestParams params = CourseRequestParams.createCourseRequestParams();
        params.setLimit(6);
        params.setGameStyle(GameStyle.SMB3);
        System.out.println(SMMDBApi.INSTANCE.getCourses(params));
    } catch (RequestException e) {
        e.printStackTrace();
    }
}

Just for you to see how complicated things become easy with this api, here is another example: I'm getting two courses with a time range between 10 and 20 seconds, with fast autoscroll and in super expert mode. This is a good example for speedrunners who want to find hard levels quickly.


public static void main(String[] args) {
    try {
        CourseRequestParams params = CourseRequestParams.createCourseRequestParams();
        params.setLimit(2);
        params.setTimeRange(10, 20);
        params.setAutoScroll(AutoScroll.FAST);
        params.setDifficultyFrom(Difficulty.SUPER_EXPERT);
        System.out.println(SMMDBApi.INSTANCE.getCourses(params));
    } catch (RequestException e) {
        e.printStackTrace();
    }
}

As you can see it is pretty easy to use. And that's the goal of this api. Just try it out for yourself 😉.

Downloading courses

If you want to download a course, you just need to make sure you have the id of the course you want to download. Here is a quick example:

public static void main(String[] args) {
    try {
        List<Course> courses = SMMDBApi.INSTANCE.getCourses(); // Get a random course
        Course courseToDownload = courses.get(0);

        SMMDBApi.INSTANCE.downloadCourse(courseToDownload.getId(), CourseFileType.ZIP, "test.zip");
    } catch (RequestException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

In the 3rd parameter of the method downloadCourse you can write where you want to download it. Writing an invalid filepath causes a FileNotFoundException.

Uploading courses

In the ToDo...

PreviousIntroduction

Last updated

Was this helpful?