Java server status

GET

/java

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://api.mcquery.net/java?target=mc.hypixel.net&port=25565"

  req, _ := http.NewRequest("GET", url, nil)

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mcquery.net/java?target=mc.hypixel.net&port=25565"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.mcquery.net/java?target=mc.hypixel.net&port=25565")
  .get()
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.mcquery.net/java',
  params: {target: 'mc.hypixel.net', port: '25565'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://api.mcquery.net/java?target=mc.hypixel.net&port=25565';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.mcquery.net/java";

    let querystring = [
        ("target", "mc.hypixel.net"),
        ("port", "25565"),
    ];

    let client = reqwest::Client::new();
    let response = client.get(url)
        .query(&querystring)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

Resolves the server (SRV supported too) and pings it. The resolved address must be public. Returns connection details and the server’s reported status fields.

Parameters

Query Parameters

target

required

string

Minecraft server hostname or IP.

Example

mc.hypixel.net

port

required

integer

>= 1 <= 65535

TCP port (1-65535).

Example

Responses

200

Server status

application/json

The server’s status fields (merged from the ping and a best-effort GS4 query) are spread into the top level alongside the connection metadata.

object

required

boolean

query

required

string

cached

required

Whether this result was served from cache

boolean

eula

required

The server’s Mojang blocklist verdict.

object

banned

required

Whether the server is on Mojang’s blocklist.

boolean

hash

required

The matching SHA1 hash from the blocklist when banned, otherwise null.

string | null

connection

required

How the server was reached. Empty object when the ping failed.

object

host

string

port

integer

srv

Whether an SRV record was used

boolean

dns

required

The server’s DNS resolution chain (SRV, CNAMEs, A/AAAA), in order. Empty for IP targets.

Array<object>

Server’s DNS resolution chain

object

hostname

required

string

type

required

Record type (SRV, CNAME, A, AAAA).

string

data

required

string

version

object

name

string

nullable

protocol

integer

nullable

players

object

online

integer

max

integer

sample

The ping’s UUID-bearing sample merged with the query’s full online roster, deduped by name.

Array<object>

One online player. id is the UUID when the ping sample reported it, or null for names that came only from the query roster. Only entries with a plausible username are included as players.

object

name

required

string

required

string

nullable

description

The server MOTD: a string or a chat component object (text/extra), as reported by the server. May contain Minecraft § color codes.

information

Lines that the server packs into its player data in place of real players. Every non-player line is kept verbatim and in order. Empty for servers that don’t do this.

Array<string>

favicon

The server icon as a data:image/png;base64 URI, or null.

string

nullable

software

The server software string from the query, or null when not queried.

string

nullable

plugins

The installed plugins from the query. null when not queried, [] when queried but none reported.

Array<string>

nullable

mods

Installed Forge mods read from the query, or null for vanilla/unmodded servers.

Array<object>

nullable

One installed Forge mod, as reported by the ping.

object

required

string

version

required

string

nullable

map

The world/map name from the query, or null.

string

nullable

gametype

The gametype from the query, or null.

string

nullable

Example

{
  "ok": true,
  "query": "mc.hypixel.net",
  "eula": {
    "hash": null
  },
  "connection": {
    "host": "mc.hypixel.net",
    "port": 25565
  },
  "dns": [
    {
      "hostname": "mc.hypixel.net",
      "type": "A",
      "data": "172.65.197.160"
    }
  ],
  "version": {
    "name": "Requires MC 1.8 / 1.21",
    "protocol": 769
  },
  "players": {
    "online": 27624,
    "max": 200000,
    "sample": [
      {
        "name": "Notch",
        "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
      }
    ]
  },
  "description": "Hypixel Network [1.8/26.2] ...",
  "information": [
    "§f✦ §9§lDISCORD: §fdiscord.gg/pp",
    "§f✦ §d§lWEBSITE: §fpurpleprison.co"
  ],
  "favicon": "data:image/png;base64,iVBORw0KGgoAAA...",
  "software": "CraftBukkit on Bukkit 1.20.1",
  "plugins": [
    "WorldEdit 7.2",
    "EssentialsX 2.20"
  ],
  "mods": [
    {
      "id": "create",
      "version": "0.5.1"
    }
  ],
  "map": "world",
  "gametype": "SMP"
}

Headers

RateLimit

string

IETF-draft combined rate-limit header for the current window: limit, remaining, and reset (seconds until the window resets). Sent on every response from a known endpoint.

Example

limit=120, remaining=119, reset=42

RateLimit-Limit

integer

Maximum requests allowed per client IP per window (120 requests per 60s).

Example

RateLimit-Remaining

integer

Requests remaining in the current window before the limit is hit.

Example

RateLimit-Reset

integer

Seconds until the current window resets.

Example

400

Missing or invalid parameter

application/json

Error response.

object

required

boolean

msg

required

string

Example

{
  "ok": false,
  "msg": "query param target is required"
}

Headers

RateLimit

string

IETF-draft combined rate-limit header for the current window: limit, remaining, and reset (seconds until the window resets). Sent on every response from a known endpoint.

Example

limit=120, remaining=119, reset=42

RateLimit-Limit

integer

Maximum requests allowed per client IP per window (120 requests per 60s).

Example

RateLimit-Remaining

integer

Requests remaining in the current window before the limit is hit.

Example

RateLimit-Reset

integer

Seconds until the current window resets.

Example

403

Target resolves to a private/reserved address

application/json

Error response.

object

required

boolean

msg

required

string

Example

{
  "ok": false,
  "msg": "target doesn't resolve to a public addr"
}

Headers

RateLimit

string

IETF-draft combined rate-limit header for the current window: limit, remaining, and reset (seconds until the window resets). Sent on every response from a known endpoint.

Example

limit=120, remaining=119, reset=42

RateLimit-Limit

integer

Maximum requests allowed per client IP per window (120 requests per 60s).

Example

RateLimit-Remaining

integer

Requests remaining in the current window before the limit is hit.

Example

RateLimit-Reset

integer

Seconds until the current window resets.

Example

429

Rate limit exceeded: more than 120 requests were made from one client IP within a 60-second window.

application/json

Error response.

object

required

boolean

msg

required

string

Example

{
  "ok": false,
  "msg": "you're being rate limited, try again later."
}

Headers

RateLimit

string

IETF-draft combined rate-limit header for the current window: limit, remaining, and reset (seconds until the window resets). Sent on every response from a known endpoint.

Example

limit=120, remaining=119, reset=42

RateLimit-Limit

integer

Maximum requests allowed per client IP per window (120 requests per 60s).

Example

RateLimit-Remaining

integer

Requests remaining in the current window before the limit is hit.

Example

RateLimit-Reset

integer

Seconds until the current window resets.

Example

Retry-After

integer

Seconds to wait before retrying. Sent only on a 429 response.

Example

500

Could not reach the server.

application/json

object

required

boolean

msg

required

string

cached

boolean

Example

{
  "ok": false,
  "cached": false,
  "msg": "couldn't resolve the server's hostname"
}