-
Notifications
You must be signed in to change notification settings - Fork 49
API
Ninjabrain Bot exposes an API on the port 52533, if enabled in the settings. This allows other applications access data from Ninjabrain Bot.
Currently only GET requests are provided, there is no way to input data to the application through the API.
If you have any questions about the API, or any feature requests, do not hesitate to message me on discord (username: ninjabrain). You can also contact me if you have an application that integrates with Ninjabrain Bot and want me to add a link to it on the front page (README).
The API supports querying data from the application, which will be returned in json format (with the exception of the ping endpoint). See Endpoints for details on specific queries.
Most queries provided by the API can be subscribed to, which means updates to the information will be automatically propagated to the subscriber. This gives the client a faster and more efficient method of receiving updates than to constantly poll the API. Appending /events to an endpoint will yield the corresponding events endpoint, if the endpoint supports it.
Events are sent according to the SSE protocol. The data sent in each event is equivalent to the json body returned by the underlying query, and an event is sent to the client every time the information is updated. Data is also sent once when the subscription is set up, to initialize the client with the current data.
To implement an SSE client you can just create your own parser (the data format is pretty simple, see example below), or use e.g. Spring if using Java.
Example output from the endpoint /api/v1/stronghold/events, including three events. The first event was sent when the subscription was started, in this case the calculator was empty when the subscription was started. The second event was sent after the user inputted one eye throw. The third event was sent after the user adjusted the measurement with +0.01 degree.
data: {"eyeThrows":[],"resultType":"NONE","playerPosition":{},"predictions":[]}
data: {"eyeThrows":[{"xInOverworld":1199.63,"angleWithoutCorrection":-161.14926034190884,"zInOverworld":-139.09,"angle":-161.14926034190884,"correction":0,"error":-0.00506611661506895,"type":"NORMAL"}],"resultType":"TRIANGULATION","playerPosition":{"xInOverworld":1199.63,"isInOverworld":true,"isInNether":false,"horizontalAngle":-161.15,"zInOverworld":-139.09},"predictions":[{"overworldDistance":1216.5659558774444,"certainty":0.460625484216222,"chunkX":99,"chunkZ":-81},{"overworldDistance":523.3899550048701,"certainty":0.21791728798094168,"chunkX":85,"chunkZ":-40},{"overworldDistance":1909.7519223710706,"certainty":0.2001332338282566,"chunkX":113,"chunkZ":-122},{"overworldDistance":1960.3478275551001,"certainty":0.0705705609262995,"chunkX":114,"chunkZ":-125},{"overworldDistance":1267.1621541854856,"certainty":0.04724231910903797,"chunkX":100,"chunkZ":-84}]}
data: {"eyeThrows":[{"xInOverworld":1199.63,"angleWithoutCorrection":-161.14926034190884,"zInOverworld":-139.09,"angle":-161.13926034190885,"correction":0.01,"error":0.0014111816929869292,"type":"NORMAL"}],"resultType":"TRIANGULATION","playerPosition":{"xInOverworld":1199.63,"isInOverworld":true,"isInNether":false,"horizontalAngle":-161.15,"zInOverworld":-139.09},"predictions":[{"overworldDistance":523.3899550048701,"certainty":0.5147413124532876,"chunkX":85,"chunkZ":-40},{"overworldDistance":1216.5659558774444,"certainty":0.2674146623130985,"chunkX":99,"chunkZ":-81},{"overworldDistance":1859.1560464361241,"certainty":0.1252834863035146,"chunkX":112,"chunkZ":-119},{"overworldDistance":1909.7519223710706,"certainty":0.07908349382318092,"chunkX":113,"chunkZ":-122},{"overworldDistance":1165.9697787678717,"certainty":0.012493314849953712,"chunkX":98,"chunkZ":-78}]}Gets information relating to stronghold finding, such as current stronghold predictions and eye measurements.
URL : /api/v1/stronghold
Method : GET
Supports subscriptions : Yes (/api/v1/stronghold/events)
Details
Root
| Name | Data type | Description |
|---|---|---|
| eyeThrows | List[EyeThrowDto] | List of all eye throw measurements made by the player. |
| resultType | string | The result type currently being shown in the calculator. |
| playerPosition | PlayerPositionDto | The last known position of the player since the calculator was reset, or {} if no position has been recorded yet. |
| predictions | List[PredictionDto] | List of up to 5 stronghold predictions. |
EyeThrowDto
| Name | Data type | Description |
|---|---|---|
| xInOverworld | double | The player's x-coordinate at the time of the eye throw. |
| zInOverworld | double | The player's z-coordinate at the time of the eye throw. |
| angle | double | The player's angle at the time of the eye throw, including manual corrections made by the user. Represented in degrees. |
| angleWithoutCorrection | double | The player's angle at the time of the eye throw, excluding manual corrections made by the user. Represented in degrees. |
| correction | double | The manual angle corrections made by the user. Represented in degrees. |
| error | double | The angle error, assuming the top stronghold prediction is correct. Will be 0 if there is no top prediction. Represented in degrees. |
| type | string | The type of throw (used to determine standard deviation). Can be NORMAL, NORMAL_WITH_ALT_STD, MANUAL, or BOAT. |
PlayerPositionDto
| Name | Data type | Description |
|---|---|---|
| xInOverworld | double | The player's x-coordinate in the overworld. If the player is in the nether this will be 8x the recorded position. |
| zInOverworld | double | The player's z-coordinate in the overworld. If the player is in the nether this will be 8x the recorded position. |
| horizontalAngle | double | The player's horizontal angle. Represented in degrees. |
| isInOverworld | boolean |
true if the player is in the overworld, false otherwise. |
| isInNether | boolean |
true if the player is in the nether, false otherwise. |
PredictionDto
| Name | Data type | Description |
|---|---|---|
| chunkX | int | The x-coordinate of the stronghold prediction, in chunk coordinates. |
| chunkZ | int | The z-coordinate of the stronghold prediction, in chunk coordinates. |
| certainty | double | The certainty of the prediction, in the interval [0, 1]. |
| overworldDistance | double | The distance measured in the overworld, from the last known player position. |
The result type field can have the following values:
-
NONE, if nothing is shown in the calculator, e.g. after it is reset. -
TRIANGULATION, if stronghold predictions are shown. -
FAILED, if the calculator failed to determine the stronghold position. -
BLIND, if a blind travel calculation is shown, e.g. after doing F3+C in the nether. -
DIVINE, if divine coordinates are shown. -
ALL_ADVANCEMENTS, if all advancements mode is enabled.
Request
localhost:52533/api/v1/stronghold
Response
{
"eyeThrows": [
{
"xInOverworld": 1213.26,
"angleWithoutCorrection": -45.529992377906794,
"zInOverworld": -318.63,
"angle": -45.529992377906794,
"correction": 0,
"error": -0.01593748756458524,
"type": "NORMAL"
},
{
"xInOverworld": 1212.65,
"angleWithoutCorrection": -45.529992377906794,
"zInOverworld": -318.01,
"angle": -45.529992377906794,
"correction": 0,
"error": 0.015504548661041895,
"type": "NORMAL"
}
],
"resultType": "TRIANGULATION",
"playerPosition": {
"xInOverworld": 1212.65,
"isInOverworld": true,
"isInNether": false,
"horizontalAngle": -45.53,
"zInOverworld": -318.01
},
"predictions": [
{
"overworldDistance": 1579.2960908582024,
"certainty": 0.828727319460384,
"chunkX": 146,
"chunkZ": 49
},
{
"overworldDistance": 1601.9224895730754,
"certainty": 0.10307666011845126,
"chunkX": 147,
"chunkZ": 50
},
{
"overworldDistance": 1556.669721745753,
"certainty": 0.06796777690586643,
"chunkX": 145,
"chunkZ": 48
},
{
"overworldDistance": 1624.5489166534815,
"certainty": 1.9048820177993296E-4,
"chunkX": 148,
"chunkZ": 51
},
{
"overworldDistance": 1534.0433835455892,
"certainty": 3.7747839045262355E-5,
"chunkX": 144,
"chunkZ": 47
}
]
}Gets information relating to all advancements mode.
URL : /api/v1/all-advancements
Method : GET
Supports subscriptions : Yes (/api/v1/all-advancements/events)
Details
Root
| Name | Data type | Description |
|---|---|---|
| isAllAdvancementsModeEnabled | boolean |
true if the application is currently showing the all advancements UI, false otherwise. |
| spawn | PositionDto | The inputted spawn (shulker) position, or {} if no position has been recorded yet. |
| monument | PositionDto | The inputted monument position, or {} if no position has been recorded yet. |
| stronghold | PositionDto | The stronghold position, or {} if no position was recorded before entering all advancements mode. |
| outpost | PositionDto | The inputted pillager outpost position, or {} if no position has been recorded yet. |
| deepDark | PositionDto | The inputted deep dark position (1.20+), or {} if no position has been recorded yet. |
| cityQuery | PositionDto | The inputted city query position (1.20+), or {} if no position has been recorded yet. |
| shulkerTransport | PositionDto | The inputted shulker transport position (1.20+), or {} if no position has been recorded yet. |
| generalLocation | PositionDto | The inputted general location (1.20+), or {} if no position has been recorded yet. |
PositionDto
| Name | Data type | Description |
|---|---|---|
| xInOverworld | int | The x-coordinate in the overworld. |
| zInOverworld | int | The z-coordinate in the overworld. |
| travelAngle | double | The angle which the player needs to travel along to move towards the position. Represented in degrees. |
| overworldDistance | int | The player's distance in the overworld to the position. |
Request
localhost:52533/api/v1/all-advancements
Response
{
"generalLocation":{
},
"spawn":{
"overworldDistance":5007,
"xInOverworld":-215,
"zInOverworld":185,
"travelAngle":134.48365647425098
},
"cityQuery":{
},
"monument":{
"overworldDistance":1,
"xInOverworld":3357,
"zInOverworld":3693,
"travelAngle":141.5819446551723
},
"shulkerTransport":{
},
"stronghold":{
"overworldDistance":4247,
"xInOverworld":2212,
"zInOverworld":-396,
"travelAngle":164.35091545590393
},
"deepDark":{
},
"isAllAdvancementsModeEnabled":true,
"outpost":{
}
}Gets blind travel information.
URL : /api/v1/blind
Method : GET
Supports subscriptions : Yes (/api/v1/blind/events)
Details
Root
| Name | Data type | Description |
|---|---|---|
| isBlindModeEnabled | boolean |
true if the application is currently showing the blind travel UI, false otherwise. |
| hasDivine | boolean |
true if there is any divine information available (currently only fossil in 0,0 chunk) to be used in the blind travel calculation. |
| blindResult | BlindResultDto | The result of the blind travel calculation, or {} if the user has not requested a blind travel calculation (done F3+C in the nether). |
BlindResultDto
| Name | Data type | Description |
|---|---|---|
| evaluation | string | The evaluation of the blind coords that are shown in the UI. Can be EXCELLENT, HIGHROLL_GOOD, HIGHROLL_OKAY, BAD_BUT_IN_RING, BAD, or NOT_IN_RING. |
| xInNether | double | The player's x-coordinate in the nether. |
| zInNether | double | The player's z-coordinate in the nether. |
| highrollThreshold | double | The threshold of what is considered a good blind distance, currently this will always be 400. In the UI it corresponds to the 400 in the text: "10.1% chance of <400 block blind". |
| highrollProbability | double | The probability of being within highrollThreshold blocks to the stronghold if blinding at the current coordinates. |
| improveDirection | string | The direction the user should travel to improve their blind coordinates. NOTE: Represented in radians. |
| improveDistance | string | The distance the user should travel in the nether to improve their blind coordinates. |
| averageDistance | string | The calculated average distance to the stronghold from the given position. This value is not displayed in the UI and just used internally, no guarantees are made about the accuracy of this value. |
Request
localhost:52533/api/v1/blind
Response
{
"isBlindModeEnabled": true,
"hasDivine": false,
"blindResult": {
"evaluation": "HIGHROLL_GOOD",
"xInNether": -217.82,
"improveDistance": 8.071372233935255,
"zInNether": 6.88,
"averageDistance": 1086.9952915836398,
"improveDirection": 1.5392211114431098,
"highrollProbability": 0.10072320582001268,
"highrollThreshold": 400
}
}Gets divine travel information.
URL : /api/v1/divine
Method : GET
Supports subscriptions : Yes (/api/v1/divine/events)
Details
Root
| Name | Data type | Description |
|---|---|---|
| isDivineModeEnabled | boolean |
true if the application is currently showing the divine travel UI, false otherwise. |
| divineResult | DivineResultDto | The result of the divine travel calculation, or {} if the user has not inputted a fossil. |
DivineResultDto
| Name | Data type | Description |
|---|---|---|
| fossilXCoordinate | int | The x-coordinate of the inputted fossil. |
| formattedSafeCoords | string | The three safe divine coordinates, formatted into a string like it is shown in the UI. |
| formattedHighrollCoords | string | The three highroll divine coordinates, formatted into a string like it is shown in the UI. |
Request
localhost:52533/api/v1/divine
Response
{
"isDivineModeEnabled": true,
"divineResult": {
"formattedSafeCoords": "(-142, 213), (-113, -230), (255, 17)",
"formattedHighrollCoords": "(-106, 158), (-84, -170), (190, 12)",
"fossilXCoordinate": 5
}
}Gets boat information.
URL : /api/v1/boat
Method : GET
Supports subscriptions : Yes (/api/v1/boat/events)
Details
Root
| Name | Data type | Description |
|---|---|---|
| boatAngle | double | The recorded boat angle. This property will not be present in the JSON body if no boat angle is recorded. Represented in degrees. |
| boatState | string | The current boat state (equivalent to the boat icon shown at the top of the application). Can be one of NONE (grey boat), ERROR (red boat), MEASURING (blue boat), or VALID (green boat). |
Request
localhost:52533/api/v1/boat
Response
{
"boatAngle": -77.34375,
"boatState": "VALID"
}Gets the version of Ninjabrain Bot.
URL : /api/v1/version
Method : GET
Supports subscriptions : No
Details
Root
| Name | Data type | Description |
|---|---|---|
| version | string | The version of Ninjabrain Bot |
Request
localhost:52533/api/v1/version
Response
{
"version": "1.5.0"
}Pings Ninjabrain Bot, and will always return the same response regardless of version.
URL : /api/v1/ping
Method : GET
Supports subscriptions : No