Fix nearby API documentation and coordinate validation

src/main/java/net/earthmc/emcapi/endpoint/LocationEndpoint.java

@@ -1,11 +1,9 @@
 package net.earthmc.emcapi.endpoint;
 
-import com.google.gson.JsonArray;
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import com.palmergames.bukkit.towny.TownyAPI;
 import com.palmergames.bukkit.towny.object.Town;
-import io.javalin.http.BadRequestResponse;
 import io.javalin.openapi.ContentType;
 import io.javalin.openapi.HttpMethod;
 import io.javalin.openapi.OpenApi;
@@ -79,26 +77,7 @@ public LocationEndpoint(final EMCAPI plugin) {
 
     @Override
     public Pair<Integer, Integer> getObjectOrNull(@NotNull JsonElement element, @Nullable String key) {
-        JsonArray jsonArray = JSONUtil.getJsonElementAsJsonArrayOrNull(element);
-        if (jsonArray == null) throw new BadRequestResponse("Your query contains a value that is not a JSON array");
-
-        int x;
-        int z;
-        try {
-            JsonElement xElement = jsonArray.get(0);
-            JsonElement zElement = jsonArray.get(1);
-
-            Integer xInner = JSONUtil.getJsonElementAsIntegerOrNull(xElement);
-            Integer zInner = JSONUtil.getJsonElementAsIntegerOrNull(zElement);
-            if (xInner == null || zInner == null) throw new BadRequestResponse("A JSON array in your query contained a value that was not an int");
-
-            x = xInner;
-            z = zInner;
-        } catch (IndexOutOfBoundsException oobe) {
-            throw new BadRequestResponse("A JSON array in your query did not contain two values");
-        }
-
-        return new Pair<>(x, z);
+        return JSONUtil.parseCoordinates(element);
     }
 
     @Override

src/main/java/net/earthmc/emcapi/endpoint/NearbyEndpoint.java

@@ -15,6 +15,7 @@
 import io.javalin.openapi.HttpMethod;
 import io.javalin.openapi.OpenApi;
 import io.javalin.openapi.OpenApiContent;
+import io.javalin.openapi.OpenApiContentProperty;
 import io.javalin.openapi.OpenApiRequestBody;
 import io.javalin.openapi.OpenApiResponse;
 import kotlin.Pair;
@@ -35,23 +36,27 @@
 import java.util.Objects;
 
 @OpenApi(
-    path = "/v4/location",
+    path = "/v4/nearby",
     methods = HttpMethod.POST,
-    summary = "Query location data",
+    summary = "Find nearby towns or nations",
     requestBody = @OpenApiRequestBody(
         required = true,
         description = "Target and type, search type, radius",
         content = {
             @OpenApiContent(
-                from = ContentTypes.NearbyQuery.class,
+                properties = @OpenApiContentProperty(name = "query", from = ContentTypes.NearbyQuery.class, isArray = true),
                 mimeType = ContentType.JSON,
                 example = """
                     {
+                      "query": [
+                        {
                           "target_type": "TOWN",
                           "target": "Melbourne",
                           "search_type": "TOWN",
                           "radius": 100,
                           "strict": true
+                        }
+                      ]
                     }
                     """
             )
@@ -60,6 +65,7 @@
     responses = {
         @OpenApiResponse(
             status = "200",
+            description = "An array containing one array of matching name/UUID objects per query",
             content = {
                 @OpenApiContent(
                     from = ContentTypes.NameUUID[].class,
@@ -125,10 +131,7 @@ public NearbyContext getObjectOrNull(@NotNull JsonElement element, @Nullable Str
         JsonElement targetElement = jsonObject.get("target");
         return switch (targetType) {
             case COORDINATE -> {
-                JsonArray jsonArray = JSONUtil.getJsonElementAsJsonArrayOrNull(targetElement);
-                if (jsonArray == null) throw new BadRequestResponse("Your target is not a valid JSON array");
-
-                Pair<Integer, Integer> pair = new Pair<>(jsonArray.get(0).getAsInt(), jsonArray.get(1).getAsInt());
+                Pair<Integer, Integer> pair = JSONUtil.parseCoordinates(targetElement);
 
                 yield new NearbyContext(targetType, pair, searchType, radius, strict);
             }

src/main/java/net/earthmc/emcapi/util/JSONUtil.java

@@ -7,6 +7,7 @@
 import com.google.gson.JsonParser;
 import com.google.gson.JsonPrimitive;
 import io.javalin.http.BadRequestResponse;
+import kotlin.Pair;
 
 public class JSONUtil {
 
@@ -40,6 +41,25 @@ public static Integer getJsonElementAsIntegerOrNull(JsonElement element) {
         return primitive.getAsInt();
     }
 
+    public static Pair<Integer, Integer> parseCoordinates(JsonElement element) {
+        JsonArray array = getJsonElementAsJsonArrayOrNull(element);
+        if (array == null || array.size() != 2) {
+            throw new BadRequestResponse("Coordinates must be an array of two integers: [x, z]");
+        }
+
+        for (JsonElement coordinate : array) {
+            if (!coordinate.isJsonPrimitive() || !coordinate.getAsJsonPrimitive().isNumber()) {
+                throw new BadRequestResponse("Coordinates must contain only integers");
+            }
+        }
+
+        try {
+            return new Pair<>(array.get(0).getAsBigDecimal().intValueExact(), array.get(1).getAsBigDecimal().intValueExact());
+        } catch (ArithmeticException | NumberFormatException e) {
+            throw new BadRequestResponse("Coordinates must be whole numbers within the 32-bit integer range");
+        }
+    }
+
     public static Boolean getJsonElementAsBooleanOrNull(JsonElement element) {
         if (element == null) return null;