add random search

src/main/java/llmjava/wikipedia/Wikipedia.java

@@ -58,6 +58,7 @@ public List<Document> geosearch(Double latitude, Double longitude) {
    * @param title - The title of an article to search for
    * @param results - the maximum number of results returned
    * @param radius - Search radius in meters. The value must be between 10 and 10000
+   * @return a list of documents near the center point
    */
   public List<Document> geosearch(Double latitude, Double longitude, String title, int results, int radius) {
     Request request = new Request();
@@ -83,7 +84,7 @@ public List<Document> geosearch(Double latitude, Double longitude, String title,
   /**
    * Get a Wikipedia search suggestion for `query`.
    * @param query search query
-   * @return a string or null if no suggestion was found.
+   * @return a list of documents or nothing if no suggestion was found.
    */
   public List<Document> suggest(String query) {
     Request request = new Request(language, userAgent);
@@ -96,6 +97,22 @@ public List<Document> suggest(String query) {
     return response.getDocs(this.language);
   }
 
+  /**
+   * Get a list of random Wikipedia article titles.
+   * @see <a href="http://en.wikipedia.org/w/api.php?action=query&list=random&rnlimit=5000&format=jsonfm">example url</a>
+   * note:: Random only gets articles from namespace 0, meaning no Category, User talk, or other meta-Wikipedia pages.
+   * @param pages the number of random pages returned (max of 10)
+   * @return a list of randomly selected documents
+   */
+  public List<Document> random(int pages) {
+    Request request = new Request(language, userAgent);
+    request.addParam("list", "random");
+    request.addParam("rnnamespace", String.valueOf(0));
+    request.addParam("rnlimit", String.valueOf(pages));
+
+    RandomResponse response = this.api.execute(request, new RandomResponse.Parser());
+    return response.getDocs(this.language);
+  }
 
   public List<Document> search(String term) throws Exception {
     Request request = new Request(language, userAgent);

src/main/java/llmjava/wikipedia/response/RandomResponse.java

@@ -0,0 +1,57 @@
+package llmjava.wikipedia.response;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import com.google.gson.Gson;
+import com.google.gson.annotations.SerializedName;
+
+import llmjava.wikipedia.Document;
+
+public class RandomResponse {
+    String batchcomplete;
+
+    @SerializedName("continue") Continue continueObj;
+    Query query;
+
+    public static class Query {
+        List<Page> random;
+
+        @Override public String toString() {
+            return "Query[random: "+random+"]";
+        }
+    }
+
+    public static class Continue {
+        String rncontinue;
+        @SerializedName("continue") String continueField;
+    }
+
+    public static class SearchInfo {
+        String suggestion;
+        String suggestionsnippet;
+    }
+
+    public List<Page> getResults() {
+        return query.random;
+    }
+
+    public List<Document> getDocs(String language) {
+        List<Document> docs = new ArrayList<>(getResults().size());
+        for(Page page: getResults()) {
+            docs.add(new Document(language, page.pageid, page.title));
+        }
+        return docs;
+    }
+
+    public static class Parser implements ResponseParser<RandomResponse> {
+        @Override public RandomResponse parse(String jsonString) {
+            RandomResponse response = new Gson().fromJson(jsonString, RandomResponse.class);
+            return response;
+        }
+    }
+
+    @Override public String toString() {
+        return "Response [batchcomplete: "+batchcomplete+", query: "+query+"]";
+    }
+}

src/test/java/llmjava/wikipedia/WikipediaTest.java

@@ -21,6 +21,10 @@ public static void main(String[] args) throws Exception {
     System.out.println("============ Query ============");
     List<Document>  results3 = wiki.suggest("apple");
     System.out.println(results3);
+
+    System.out.println("============ Query ============");
+    List<Document>  results4 = wiki.random(5);
+    System.out.println(results4);
   }
 
   @Test