README.md

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

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

LocationApiTest.java

Search Archive API

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.

SerpApiTest.java

Account API

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.

AccountApiTest.java

Examples in Java

Search bing

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

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

Search baidu

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

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

Search yahoo

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

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

Search youtube

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

Search walmart

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

Search ebay

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

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

Search naver

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

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

Search home depot

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

Search 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", "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

Search duckduckgo

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

Search google

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

Search google scholar

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

Search google autocomplete

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

Search google product

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

Search 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_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

Search google events

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

Search google maps

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

Search google jobs

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

Search google play

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

Search google images

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

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

// before
Map<String, String> parameter = new HashMap<>();
parameter.put("q", "coffee");
parameter.put("api_key", "your_api_key");
GoogleSearch search = new GoogleSearch(parameter);
JsonObject results = search.getJson();

// after
Map<String, String> auth = new HashMap<>();
auth.put("api_key", "your_api_key");
SerpApi client = new SerpApi(auth);

Map<String, String> parameter = new HashMap<>();
parameter.put("q", "coffee");
parameter.put("engine", "google");
JsonObject results = 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

• https://www.baeldung.com/java-http-request
• https://github.com/google/gson

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