SerpApi Java Library

Integrate search data into your Java application. This library is the official wrapper for SerpApi.

SerpApi supports Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and more.

The full documentation is available here.

Installation

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.

Usage

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.

Documentation

SerpApi Search API — parameters, engines, and response formats
After cloning, run ./gradlew javadoc and open build/docs/javadoc/index.html for this library’s Javadoc.

Requirements

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

Location API

SerpApiserpapi = newSerpApi();
Map<String, String> parameter = newHashMap<String, String>();
parameter.put("q", "Austin");
parameter.put("limit", "3");
JsonArraylocation = 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).

LocationApiTest.java

Search Archive API

Run a search to obtain a search_id.

Map<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiserpapi = newSerpApi(auth);
Map<String, String> parameter = newHashMap<>();
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");
JsonObjectresults = serpapi.search(parameter);

Retrieve the same search from the archive:

// now search in the archiveStringid = results.getAsJsonObject("search_metadata").getAsJsonPrimitive("id").getAsString();
// retrieve search from the archive with speed for freeJsonObjectarchive = 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.

SerpApiTest.java

Account API

Map<String, String> parameter = newHashMap<>();
parameter.put("api_key", "your_api_key");
SerpApiserpapi = newSerpApi(parameter);
JsonObjectaccount = serpapi.account();
System.out.println(account.toString());

it prints your account information.

AccountApiTest.java

Examples in Java

Search bing

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "bing");
parameter.put("q", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/BingTest.java see: https://serpapi.com/bing-search-api

Search baidu

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "baidu");
parameter.put("q", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/BaiduTest.java see: https://serpapi.com/baidu-search-api

Search yahoo

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "yahoo");
parameter.put("p", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/YahooTest.java see: https://serpapi.com/yahoo-search-api

Search youtube

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "youtube");
parameter.put("search_query", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/YoutubeTest.java see: https://serpapi.com/youtube-search-api

Search walmart

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "walmart");
parameter.put("query", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/WalmartTest.java see: https://serpapi.com/walmart-search-api

Search ebay

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "ebay");
parameter.put("_nkw", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/EbayTest.java see: https://serpapi.com/ebay-search-api

Search naver

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "naver");
parameter.put("query", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/NaverTest.java see: https://serpapi.com/naver-search-api

Search home depot

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "home_depot");
parameter.put("q", "table");
JsonObjectresults = 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

Search apple app store

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "apple_app_store");
parameter.put("term", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/AppleAppStoreTest.java see: https://serpapi.com/apple-app-store

Search duckduckgo

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "duckduckgo");
parameter.put("q", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/DuckduckgoTest.java see: https://serpapi.com/duckduckgo-search-api

Search google

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google");
parameter.put("q", "coffee");
parameter.put("engine", "google");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleTest.java see: https://serpapi.com/search-api

Search google scholar

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_scholar");
parameter.put("q", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleScholarTest.java see: https://serpapi.com/google-scholar-api

Search google autocomplete

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_autocomplete");
parameter.put("q", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleAutocompleteTest.java see: https://serpapi.com/google-autocomplete-api

Search google product

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_product");
parameter.put("q", "coffee");
parameter.put("product_id", "4887235756540435899");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleProductTest.java

see: https://serpapi.com/google-product-api

Search google reverse image

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_reverse_image");
parameter.put("image_url", "https://i.imgur.com/5bGzZi7.jpg");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleReverseImageTest.java see: https://serpapi.com/google-reverse-image

Search google events

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_events");
parameter.put("q", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleEventsTest.java see: https://serpapi.com/google-events-api

Search google maps

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_maps");
parameter.put("q", "pizza");
parameter.put("ll", "@40.7455096,-74.0083012,15.1z");
parameter.put("type", "search");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleMapsTest.java see: https://serpapi.com/google-maps-api

Search google jobs

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_jobs");
parameter.put("q", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleJobsTest.java see: https://serpapi.com/google-jobs-api

Search google play

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_play");
parameter.put("q", "kite");
parameter.put("store", "apps");
JsonObjectresults = client.search(parameter);
JsonArraysections = results.getAsJsonArray("organic_results");
intappCount = 0;
for (JsonElementsection : sections) {
JsonObjectsectionObj = 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

Search google images

// setup serpapi clientMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
// run searchMap<String, String> parameter = newHashMap<>();
parameter.put("engine", "google_images");
parameter.put("engine", "google_images");
parameter.put("tbm", "isch");
parameter.put("q", "coffee");
JsonObjectresults = client.search(parameter);
System.out.println(results.toString());

source code: src/test/java/serpapi/example/GoogleImagesTest.java see: https://serpapi.com/images-results

Migration from google-search-results-java

If you are upgrading from the legacy google-search-results-java library, here is a summary of what changed.

Dependency

// before
implementation 'com.github.serpapi:google-search-results-java:2.0.0'// after
implementation 'com.github.serpapi:serpapi-java:1.1.0'

Class and method renames

Old (`google-search-results-java`)	New (`serpapi-java`)
`GoogleSearch`	`SerpApi`
`SerpApiSearch`	`SerpApi`
`client.getJson()`	`client.search(parameter)`
`client.getHtml()`	`client.html(parameter)`
`client.getSearchArchive(id)`	`client.searchArchive(id)`
`client.getAccount()`	`client.account()`
`client.getLocation(parameter)`	`client.location(parameter)`
`SerpApiSearchException`	`SerpApiException`

Example

// beforeMap<String, String> parameter = newHashMap<>();
parameter.put("q", "coffee");
parameter.put("api_key", "your_api_key");
GoogleSearchsearch = newGoogleSearch(parameter);
JsonObjectresults = search.getJson();
// afterMap<String, String> auth = newHashMap<>();
auth.put("api_key", "your_api_key");
SerpApiclient = newSerpApi(auth);
Map<String, String> parameter = newHashMap<>();
parameter.put("q", "coffee");
parameter.put("engine", "google");
JsonObjectresults = client.search(parameter);

Contributing

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 test

Regenerate README.md from the template after editing examples:

make readme # requires Ruby `erb`

How to build from source

Clone the repository:

git clone https://github.com/serpapi/serpapi-java.git
cd serpapi-java

Build (use the wrapper):

./gradlew build

The 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.

TLS / HTTPS and older JVMs

Symptom

javax.net.ssl.SSLHandshakeException

Cause

SerpApi is served over HTTPS (TLS). Very old JRE/JDK builds may lack the TLS versions or cipher suites required to connect.

Solution

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 -version

On Windows, install a current JDK from your vendor and point JAVA_HOME at it.

Inspiration

License

MIT license

Changelog

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

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.github/workflows		.github/workflows
demo		demo
gradle/wrapper		gradle/wrapper
src		src
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.md.erb		README.md.erb
build.gradle		build.gradle
gradlew		gradlew
settings.gradle		settings.gradle

Uh oh!

Folders and files

Latest commit

History

Repository files navigation