> For the complete documentation index, see [llms.txt](https://zsuckylp.gitbook.io/workspace/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zsuckylp.gitbook.io/workspace/usage-of-the-api.md).
# Usage of the API
How to use it.
## Getting Started
To get started, create a new Maven project and add this repository:
```markup
FluentCoding-smmdb-api
https://packagecloud.io/FluentCoding/smmdb-api/maven2
```
... and the dependency:
```markup
io.fluentcoding
smmdb-api
LATEST
```
If you prefer using Gradle then add the dependency like this:
```groovy
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.
{% hint style="info" %}
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.
{% endhint %}
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:
{% code title="Example" %}
```java
CourseRequestParams params = CourseRequestParams.createCourseRequestParams();
```
{% endcode %}
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 ([⭐](https://emojiterra.com/de/gelber-stern/)) the respective levels. |
| `getCourses(CourseRequestParams, String)` | Gets the courses of the SMMDB-Server filtered with the attribute if the player has starred ([⭐](https://emojiterra.com/de/gelber-stern/)) 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](https://de.wikipedia.org/wiki/Plain_Old_Java_Object) (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.**:
{% tabs %}
{% tab title="6 Courses with Super Mario Bros 3. style" %}
```java
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();
}
}
```
{% endtab %}
{% tab title="Output" %}
```
[Course {
id = 5d7e76b31d890ae79e812905
owner = 5d6942585553e67e415ae4e8
title = ultra dificil
maker = slem
nintendoid =
videoid =
autoScroll = DISABLED
autoScrollSub = DISABLED
gameStyle = SMB3
courseTheme = GROUND
courseThemeSub = UNDERWATER
difficulty = NORMAL
lastModified = Sun Sep 15 19:38:33 CEST 2019
uploaded = Sun Sep 15 19:36:51 CEST 2019
stars = 2
time = 500
width = 3840
widthSub = 0
vPrev = null
vFull = null
starred = null
}, Course {
id = 5d7945db1d890a92d0812865
owner = 5d73bf936085e858a38e8805
title = Where is the POW
maker = TheMateoXD
nintendoid =
videoid =
autoScroll = DISABLED
autoScrollSub = DISABLED
gameStyle = SMB3
courseTheme = GROUND
courseThemeSub = UNDERGROUND
difficulty = NORMAL
lastModified = Wed Sep 11 21:07:55 CEST 2019
uploaded = Wed Sep 11 21:07:06 CEST 2019
stars = 1
time = 400
width = 1344
widthSub = 3264
vPrev = null
vFull = null
starred = null
}, Course {
id = 5d7674821d890a10c981281a
owner = 5d73cd6f6085e846e18e8806
title = batalha
maker = Luzak
nintendoid =
videoid =
autoScroll = DISABLED
autoScrollSub = DISABLED
gameStyle = SMB3
courseTheme = GHOUST_HOUSE
courseThemeSub = CASTLE
difficulty = EXPERT
lastModified = Mon Sep 09 18:02:19 CEST 2019
uploaded = Mon Sep 09 17:49:22 CEST 2019
stars = 2
time = 500
width = 3264
widthSub = 3264
vPrev = null
vFull = null
starred = null
}, Course {
id = 5d6d8da65553e65d4c5ae57a
owner = 5d4eed07b4162eeffb4029d1
title = super smash bros
maker = stal123mor
nintendoid =
videoid =
autoScroll = DISABLED
autoScrollSub = DISABLED
gameStyle = SMB3
courseTheme = GROUND
courseThemeSub = CASTLE
difficulty = NORMAL
lastModified = Mon Sep 02 23:46:52 CEST 2019
uploaded = Mon Sep 02 23:46:14 CEST 2019
stars = 2
time = 500
width = 3840
widthSub = 0
vPrev = null
vFull = null
starred = null
}, Course {
id = 5d6af7745553e6a8025ae52d
owner = 5d69f2c45553e626e65ae503
title = Bowser Hell
maker = raMio
nintendoid =
videoid =
autoScroll = DISABLED
autoScrollSub = DISABLED
gameStyle = SMB3
courseTheme = GROUND
courseThemeSub = UNDERGROUND
difficulty = NORMAL
lastModified = Sun Sep 01 00:41:22 CEST 2019
uploaded = Sun Sep 01 00:40:52 CEST 2019
stars = 1
time = 10
width = 384
widthSub = 0
vPrev = null
vFull = null
starred = null
}, Course {
id = 5d6304f15553e678dc5ae42d
owner = 5c06fcc719764a319891f4d2
title = mario 3 marble garden zone
maker = jony gamer
nintendoid =
videoid = UCnyzOrMwYnr
autoScroll = DISABLED
autoScrollSub = DISABLED
gameStyle = SMB3
courseTheme = GROUND
courseThemeSub = UNDERWATER
difficulty = NORMAL
lastModified = Mon Aug 26 00:02:59 CEST 2019
uploaded = Mon Aug 26 00:00:14 CEST 2019
stars = 1
time = 500
width = 3840
widthSub = 3840
vPrev = null
vFull = null
starred = null
}]
```
{% endtab %}
{% endtabs %}
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.
{% tabs %}
{% tab title="2 Courses with a time between 10 and 20 sec., fast autoscroll and in super-expert mode" %}
```java
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();
}
}
```
{% endtab %}
{% tab title="Output" %}
```
[Course {
id = 5d1e205ac653e383c14926c9
owner = 5d1e1cb1c653e3367c4926c6
title = IMPOSSIBLE - IMPOSSIVEL
maker = Peedruuh
nintendoid =
videoid =
autoScroll = FAST
autoScrollSub = DISABLED
gameStyle = SMW
courseTheme = CASTLE
courseThemeSub = UNDERGROUND
difficulty = SUPER_EXPERT
lastModified = Thu Jul 04 17:54:46 CEST 2019
uploaded = Thu Jul 04 17:50:50 CEST 2019
stars = 3
time = 20
width = 1920
widthSub = 0
vPrev = null
vFull = null
starred = null
}, Course {
id = 5cee8f2600dd3ddd3bfc85d7
owner = 5ce18ee70cb2ae09bd8a1df9
title = Deadly Run
maker = Benner
nintendoid =
videoid =
autoScroll = FAST
autoScrollSub = DISABLED
gameStyle = SMW
courseTheme = GROUND
courseThemeSub = GROUND
difficulty = SUPER_EXPERT
lastModified = Wed May 29 15:56:22 CEST 2019
uploaded = Wed May 29 15:54:46 CEST 2019
stars = 3
time = 20
width = 1200
widthSub = 1200
vPrev = null
vFull = null
starred = null
}]
```
{% endtab %}
{% endtabs %}
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:
```java
public static void main(String[] args) {
try {
List 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...