diff --git a/README.md b/README.md index daf088a..f0c8cb4 100644 --- a/README.md +++ b/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 auth = new HashMap<>(); +auth.put("api_key", "your_api_key"); +auth.put("engine", "google"); +SerpApi serpapi = new SerpApi(auth); + +Map 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 diff --git a/README.md.erb b/README.md.erb index 85e9d8f..e2d3d98 100644 --- a/README.md.erb +++ b/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 auth = new HashMap<>(); +auth.put("api_key", "your_api_key"); +auth.put("engine", "google"); +SerpApi serpapi = new SerpApi(auth); + +Map 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 diff --git a/build.gradle b/build.gradle index b491cdc..4f996dd 100644 --- a/build.gradle +++ b/build.gradle @@ -20,7 +20,7 @@ jacocoTestReport { base { archivesName = 'serpapi' } -version = '1.1.0' +version = '1.2.0' group = 'com.github.serpapi' java { diff --git a/src/main/java/serpapi/SerpApi.java b/src/main/java/serpapi/SerpApi.java index 9c24872..230e378 100644 --- a/src/main/java/serpapi/SerpApi.java +++ b/src/main/java/serpapi/SerpApi.java @@ -62,6 +62,20 @@ public String html(Map 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 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 diff --git a/src/main/java/serpapi/SerpApiHttp.java b/src/main/java/serpapi/SerpApiHttp.java index 33129e9..23cc8f4 100644 --- a/src/main/java/serpapi/SerpApiHttp.java +++ b/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 diff --git a/src/test/java/serpapi/MarkdownApiTest.java b/src/test/java/serpapi/MarkdownApiTest.java new file mode 100644 index 0000000..7dd7721 --- /dev/null +++ b/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 recorded; + + RecordingHttp() { + super("/search"); + } + + @Override + public String get(Map 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 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 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")); + } +}