Add markdown support, improve error handling if corrupt data received.

dependencies {
    implementation 'com.github.serpapi:serpapi-java:1.2.0'
}

Markdown output

markdown() returns search results in the md output format, intended for LLM and agent consumption. Previously this required dropping to the low-level get("/search", "md", parameter) and knowing the endpoint path.

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));

The raw markdown String is returned unparsed, like html().

Errors reported inside a successful response

This is a breaking behavior change.

SerpApi reports some failures in the body of an HTTP 200 response:

{
  "search_metadata": { "status": "Success" },
  "search_information": { "events_results_state": "Fully empty" },
  "error": "Google hasn't returned any results for this query."
}

The client previously decided success from the status code alone, so search() returned an object that was semantically an error. Callers then reached for the key they expected and got a NullPointerException in their own code, while the explanation sat unread in the error field.

search(), account(), searchArchive() and location() now raise SerpApiException carrying that message, whatever the status code.

If you currently inspect the returned object for an error field yourself, that branch is now unreachable — catch SerpApiException instead. html() and markdown() are unaffected, since both return raw Strings.

Request timeout

SerpApi.timeout was applied only to the connection timeout, leaving the read timeout at its 60s default. That is backwards: connecting takes milliseconds, while 60s to read is tight for engines that scrape. Searches against slow engines — home_depot especially — intermittently failed with:

SerpApiException: java.net.http.HttpTimeoutException: request timed out

The timeout now applies to both connecting and reading, and the default is 120s. To restore the previous bound, set timeout before issuing a search.

Also in this release

• Migration guide from google-search-results-java, and corrected SerpApi links in the README.
• The README example generator sliced test files at a hardcoded line offset, which corrupted examples whenever a test file shifted. It now anchors on a marker comment.
• Test failures print full exception detail in CI, so assertion messages are no longer discarded.

Known issues

• GoogleEventsTest is quarantined. The google_events engine returns events_results_state: "Fully empty" for every query tried, across several days. This is upstream, not the client; the test is marked @Ignore until events are returned again.
• markdown() has not been exercised against the live API. Its tests assert the request the client builds — that output=md goes to /search — not the backend response. Note html() posts to /client rather than /search; if that is the intended route for non-JSON output, markdown() should follow it.

Full changelog: 1.1.0...1.2.0

• Java 21 + Gradle modernization
• JaCoCo + Makefile coverage workflow updates
• HTTP/build reliability improvements
• test/build fixes
• README/demo/version documentation updates

What's Changed

• Remove num param by @shubhamjain in #4
• Clarify usage instructions in readme by @schaferyan in #2

New Contributors

• @shubhamjain made their first contribution in #4
• @schaferyan made their first contribution in #2

Full Changelog: 1.0.0...1.1.0

• Modern fluent API
• Support all SerpApi end points
• Fully documented