Integrate search data into your Java application. This library is the official wrapper for SerpApi (https://serpapi.com).
SerpApi supports Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and more.
The full documentation is available here.
Using Maven / Gradle.
Edit your build.gradle file:
repositories {
maven { url "https://jitpack.io" }
}
dependencies {
implementation 'com.github.serpapi:serpapi-java:1.1.0'
}To list all available versions: https://jitpack.io/api/builds/com.github.serpapi/serpapi-java
or you can download the jar file from https://github.com/serpapi/serpapi-java/releases
Note: JitPack builds Maven artifacts from GitHub releases and tags.
To try the library quickly, use the demo project:
git clone https://github.com/serpapi/serpapi-java.git
cd serpapi-java/demo
make all SERPAPI_KEY='<your private key>'Use quotes if your key contains shell-special characters. You need a SerpApi account to obtain a key: https://serpapi.com/dashboard
demo/src/main/java/demo/App.java:
class App {
public static void main(String[] args) {
String apiKey = System.getenv("SERPAPI_KEY");
// set search location
String location = "Austin,Texas";
String engine = "google";
System.out.println("find the first coffee shop in " + location + " using " + engine);
Map<String, String> auth = new HashMap<>();
auth.put("engine", engine);
auth.put("api_key", apiKey);
// create client
SerpApi serpapi= new SerpApi(auth);
// create search parameters
Map<String, String> parameter = new HashMap<>();
parameter.put("q", "Coffee");
parameter.put("location", location);
// perform search
try {
// get search results
JsonObject data = serpapi.search(parameter);
JsonArray organic = data.getAsJsonArray("organic_results");
JsonObject first = organic.get(0).getAsJsonObject();
System.out.println("First result: " + first.get("title").getAsString() + " (search near " + location + ")");
} catch (SerpApiException e) {
System.out.println("SerpApi request failed.");
e.printStackTrace();
System.exit(1);
}
}
}
The SerpApi.com API Documentation contains a list of all the possible parameters that can be passed to the API.
- SerpApi Search API — parameters, engines, and response formats
- After cloning, run
./gradlew javadocand openbuild/docs/javadoc/index.htmlfor this library’s Javadoc.
This library uses Gson for JSON and returns responses as Gson JsonObject / JsonArray.
This repository is built and tested with JDK 21 and the Gradle wrapper (./gradlew, currently Gradle 8.5). Use the wrapper so you do not need a separate Gradle install.
Consumers of the JitPack artifact should run a JVM whose version is at least the bytecode level of the release you depend on (releases from this branch target Java 21).
SerpApi serpapi = new SerpApi();
Map<String, String> parameter = new HashMap<String, String>();
parameter.put("q", "Austin");
parameter.put("limit", "3");
JsonArray location = serpapi.location(parameter);
System.out.println(location.get(0).getAsJsonObject().get("name").getAsString());
// Prints the first matching name among up to 3 results (see LocationApiTest for a JUnit example).Run a search to obtain a search_id.
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi serpapi = new SerpApi(auth);
Map<String, String> parameter = new HashMap<>();
parameter.put("q", "Coffee");
parameter.put("location", "Austin, Texas, United States");
parameter.put("hl", "en");
parameter.put("gl", "us");
parameter.put("google_domain", "google.com");
parameter.put("safe", "active");
parameter.put("start", "10");
parameter.put("device", "desktop");
JsonObject results = serpapi.search(parameter);Retrieve the same search from the archive:
// now search in the archive
String id = results.getAsJsonObject("search_metadata").getAsJsonPrimitive("id").getAsString();
// retrieve search from the archive with speed for free
JsonObject archive = serpapi.searchArchive(id);
System.out.println(archive.toString());The archived JSON matches the original search result. In tests, the key is supplied via System.getenv("SERPAPI_KEY"); see SerpApiTest.java.
Map<String, String> parameter = new HashMap<>();
parameter.put("api_key", "your_api_key");
SerpApi serpapi = new SerpApi(parameter);
JsonObject account = serpapi.account();
System.out.println(account.toString());it prints your account information.
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "bing");
parameter.put("q", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "baidu");
parameter.put("q", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "yahoo");
parameter.put("p", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "youtube");
parameter.put("search_query", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/YoutubeTest.java see: https://serpapi.com/youtube-search-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "walmart");
parameter.put("query", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/WalmartTest.java see: https://serpapi.com/walmart-search-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "ebay");
parameter.put("_nkw", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "naver");
parameter.put("query", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "home_depot");
parameter.put("q", "table");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/HomeDepotTest.java see: https://serpapi.com/home-depot-search-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "apple_app_store");
parameter.put("term", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/AppleAppStoreTest.java see: https://serpapi.com/apple-app-store
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "duckduckgo");
parameter.put("q", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/DuckduckgoTest.java see: https://serpapi.com/duckduckgo-search-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google");
parameter.put("q", "coffee");
parameter.put("engine", "google");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleTest.java see: https://serpapi.com/search-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_scholar");
parameter.put("q", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleScholarTest.java see: https://serpapi.com/google-scholar-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_autocomplete");
parameter.put("q", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleAutocompleteTest.java see: https://serpapi.com/google-autocomplete-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_product");
parameter.put("q", "coffee");
parameter.put("product_id", "4887235756540435899");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleProductTest.java
see: https://serpapi.com/google-product-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_reverse_image");
parameter.put("image_url", "https://i.imgur.com/5bGzZi7.jpg");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleReverseImageTest.java see: https://serpapi.com/google-reverse-image
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_events");
parameter.put("q", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleEventsTest.java see: https://serpapi.com/google-events-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_maps");
parameter.put("q", "pizza");
parameter.put("ll", "@40.7455096,-74.0083012,15.1z");
parameter.put("type", "search");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleMapsTest.java see: https://serpapi.com/google-maps-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_jobs");
parameter.put("q", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleJobsTest.java see: https://serpapi.com/google-jobs-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_play");
parameter.put("q", "kite");
parameter.put("store", "apps");
JsonObject results = client.search(parameter);
JsonArray sections = results.getAsJsonArray("organic_results");
int appCount = 0;
for (JsonElement section : sections) {
JsonObject sectionObj = section.getAsJsonObject();
if (sectionObj.has("items") && sectionObj.get("items").isJsonArray()) {
appCount += sectionObj.getAsJsonArray("items").size();
}
}
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GooglePlayTest.java see: https://serpapi.com/google-play-api
// setup serpapi client
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);
// run search
Map<String, String> parameter = new HashMap<>();
parameter.put("engine", "google_images");
parameter.put("engine", "google_images");
parameter.put("tbm", "isch");
parameter.put("q", "coffee");
JsonObject results = client.search(parameter);
System.out.println(results.toString());- source code: src/test/java/serpapi/example/GoogleImagesTest.java see: https://serpapi.com/images-results
We use JUnit, GitHub Actions (see workflow), and Gradle.
Run the full test suite locally (integration tests call the live API when a key is present):
export SERPAPI_KEY='your_key' # optional: without it, many tests skip; some tests require the key and will fail if unset
./gradlew testRegenerate README.md from the template after editing examples:
make readme # requires Ruby `erb`Clone the repository:
git clone https://github.com/serpapi/serpapi-java.git
cd serpapi-javaBuild (use the wrapper):
./gradlew buildThe main library JAR is under build/libs/ (for example serpapi-1.1.0.jar, name follows version in build.gradle). Copy it into your project’s lib/ directory if you are not using Maven/Gradle dependency resolution.
javax.net.ssl.SSLHandshakeException
SerpApi is served over HTTPS (TLS). Very old JRE/JDK builds may lack the TLS versions or cipher suites required to connect.
Use a current JDK (this project is tested on JDK 21). On macOS you can select an installed JDK, for example:
/usr/libexec/java_home -V
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
java -versionOn Windows, install a current JDK from your vendor and point JAVA_HOME at it.
MIT license
- 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