feat: add markdown() for the md output format, bump to 1.2.0

README.md

@@ -21,7 +21,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.github.serpapi:serpapi-java:1.1.0'
+    implementation 'com.github.serpapi:serpapi-java:1.2.0'
 }
 ```
 
@@ -159,6 +159,22 @@ it prints your account information.
 
 [AccountApiTest.java](https://github.com/serpapi/serpapi-java/blob/master/src/test/java/serpapi/AccountApiTest.java)
 
+### Markdown output
+
+```java
+Map<String, String> auth = new HashMap<>();
+auth.put("api_key", "your_api_key");
+auth.put("engine", "google");
+SerpApi serpapi = new SerpApi(auth);
+
+Map<String, String> parameter = new HashMap<>();
+parameter.put("q", "coffee");
+System.out.println(serpapi.markdown(parameter));
+```
+it prints the results as raw markdown, intended for LLM and agent consumption.
+
+[MarkdownApiTest.java](https://github.com/serpapi/serpapi-java/blob/master/src/test/java/serpapi/MarkdownApiTest.java)
+
 ## Examples in Java
 
 ### Search bing
@@ -550,7 +566,7 @@ If you are upgrading from the legacy [`google-search-results-java`](https://gith
 implementation 'com.github.serpapi:google-search-results-java:2.0.0'
 
 // after
-implementation 'com.github.serpapi:serpapi-java:1.1.0'
+implementation 'com.github.serpapi:serpapi-java:1.2.0'
 ```
 
 ### Class and method renames
@@ -648,6 +664,7 @@ On Windows, install a current JDK from your vendor and point `JAVA_HOME` at it.
 MIT license
 
 ## Changelog
+- 1.2.0 — Add markdown support, improve error handling if corrupt data received
 - 1.1.0 — Java 21, Gradle 8.x; ongoing API and example updates
 - 1.0.0 — Revisit API naming and align the client with serpapi.com
 

README.md.erb

@@ -39,7 +39,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.github.serpapi:serpapi-java:1.1.0'
+    implementation 'com.github.serpapi:serpapi-java:1.2.0'
 }
 ```
 
@@ -177,6 +177,22 @@ it prints your account information.
 
 [AccountApiTest.java](https://github.com/serpapi/serpapi-java/blob/master/src/test/java/serpapi/AccountApiTest.java)
 
+### Markdown output
+
+```java
+Map<String, String> auth = new HashMap<>();
+auth.put("api_key", "your_api_key");
+auth.put("engine", "google");
+SerpApi serpapi = new SerpApi(auth);
+
+Map<String, String> parameter = new HashMap<>();
+parameter.put("q", "coffee");
+System.out.println(serpapi.markdown(parameter));
+```
+it prints the results as raw markdown, intended for LLM and agent consumption.
+
+[MarkdownApiTest.java](https://github.com/serpapi/serpapi-java/blob/master/src/test/java/serpapi/MarkdownApiTest.java)
+
 ## Examples in Java
 
 ### Search bing
@@ -287,7 +303,7 @@ If you are upgrading from the legacy [`google-search-results-java`](https://gith
 implementation 'com.github.serpapi:google-search-results-java:2.0.0'
 
 // after
-implementation 'com.github.serpapi:serpapi-java:1.1.0'
+implementation 'com.github.serpapi:serpapi-java:1.2.0'
 ```
 
 ### Class and method renames
@@ -385,6 +401,7 @@ On Windows, install a current JDK from your vendor and point `JAVA_HOME` at it.
 MIT license
 
 ## Changelog
+- 1.2.0 — Add markdown support, improve error handling if corrupt data received
 - 1.1.0 — Java 21, Gradle 8.x; ongoing API and example updates
 - 1.0.0 — Revisit API naming and align the client with serpapi.com
 

build.gradle

@@ -20,7 +20,7 @@ jacocoTestReport {
 base {
     archivesName = 'serpapi'
 }
-version = '1.1.0'
+version = '1.2.0'
 group = 'com.github.serpapi'
 
 java {

src/main/java/serpapi/SerpApi.java

@@ -62,6 +62,20 @@ public String html(Map<String, String> parameter) throws SerpApiException {
     return get("/client", "html", parameter);
   }
 
+  /***
+   * Returns search results as a raw markdown String
+   *
+   * The markdown format is produced by the backend and intended for LLM and
+   * agent consumption. It is returned unparsed, like html().
+   *
+   * @param parameter markdown search parameter
+   * @return raw markdown response from the client engine
+   * @throws SerpApiException wraps backend error message
+   */
+  public String markdown(Map<String, String> parameter) throws SerpApiException {
+    return get("/search", "md", parameter);
+  }
+
   /***
    * Returns search results as JSON object
    * 
@@ -143,7 +157,7 @@ public SerpApiHttp getClient() {
    * Build a serp API query by expanding existing parameters
    *
    * @param path backend HTTP path
-   * @param output type of output format (json, html, json_with_images)
+   * @param output type of output format (json, html, md)
    * @param parameter custom search parameter which override the default parameter provided in the constructor
    * @return format parameter hash map
    * @throws SerpApiException wraps backend error message

src/main/java/serpapi/SerpApiHttp.java

@@ -22,7 +22,7 @@ public class SerpApiHttp {
   /**
    * current API version
    */
-  public static String VERSION = "1.0.0";
+  public static String VERSION = "1.2.0";
 
   /**
    * backend service

src/test/java/serpapi/MarkdownApiTest.java

@@ -0,0 +1,67 @@
+package serpapi;
+
+import org.junit.Test;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.Assert.*;
+
+/**
+ * Test SerpApi.markdown() method.
+ *
+ * Offline: the HTTP client is stubbed, so no network call and no SERPAPI_KEY
+ * are needed. What matters here is the request this client builds, which can
+ * be asserted without a live backend.
+ */
+public class MarkdownApiTest {
+
+  /**
+   * Stubbed HTTP client that records the query it was asked to send.
+   */
+  private static class RecordingHttp extends SerpApiHttp {
+    Map<String, String> recorded;
+
+    RecordingHttp() {
+      super("/search");
+    }
+
+    @Override
+    public String get(Map<String, String> parameter) {
+      this.recorded = parameter;
+      return "## Search results\n\n1. [Coffee](https://example.com)\n";
+    }
+  }
+
+  @Test
+  public void markdownRequestsMdOutput() throws SerpApiException {
+    SerpApi serpapi = new SerpApi(new HashMap<>());
+    RecordingHttp http = new RecordingHttp();
+    serpapi.client = http;
+
+    Map<String, String> parameter = new HashMap<>();
+    parameter.put("q", "coffee");
+    String content = serpapi.markdown(parameter);
+
+    assertEquals("md", http.recorded.get("output"));
+    assertEquals("coffee", http.recorded.get("q"));
+    assertEquals("/search", http.path);
+    assertTrue(content.startsWith("## Search results"));
+  }
+
+  @Test
+  public void markdownMergesDefaultParameter() throws SerpApiException {
+    Map<String, String> auth = new HashMap<>();
+    auth.put("api_key", "secret");
+    auth.put("engine", "google");
+    SerpApi serpapi = new SerpApi(auth);
+    RecordingHttp http = new RecordingHttp();
+    serpapi.client = http;
+
+    serpapi.markdown(new HashMap<>());
+
+    assertEquals("secret", http.recorded.get("api_key"));
+    assertEquals("google", http.recorded.get("engine"));
+    assertEquals("md", http.recorded.get("output"));
+  }
+}