Skip to content

Commit a75b32e

Browse files
jvmvikjvmvik
committed
add proper readme
1 parent f92763d commit a75b32e

File tree

4 files changed

+226
-7
lines changed

4 files changed

+226
-7
lines changed

‎.github/workflows/gradle.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,6 @@ jobs:
2323
- name: Grant execute permission for gradlew
2424
run: chmod +x gradlew
2525
- name: test
26-
run: make test
26+
run: ./gradlew test
2727
env:
2828
API_KEY: ${{secrets.API_KEY}}

‎Makefile‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.PHONY: build
22

3-
all: clean test
3+
all: clean build test readme doc
44

55
# clean
66
clean:
@@ -18,6 +18,10 @@ build: clean
1818
oobt: build
1919
$(MAKE) -C demo all
2020

21+
# Ruby must be installed (ERB is located under $GEM_HOME/bin or under Ruby installation)
22+
readme:
23+
erb -T '-' README.md.erb > README.md
24+
2125
doc:
2226
gradle javadoc --info --warning-mode all
2327

‎README.md‎

Lines changed: 218 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,218 @@
1-
Early development in progress
1+
# SerpApi Java Library
2+
3+
![test](https://github.com/serpapi/serpapi-java/workflows/test/badge.svg)
4+
5+
Integrate search data into your Java application. This library is the official wrapper for SerpApi (https://serpapi.com).
6+
7+
SerpApi supports Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and more.
8+
9+
[The full documentation is available here.](https://serpapi.com/search-api)
10+
11+
## Installation
12+
13+
Using Maven / Gradle.
14+
15+
Edit your build.gradle file
16+
```java
17+
repositories {
18+
maven { url "https://jitpack.io" }
19+
}
20+
21+
dependencies {
22+
implementation 'com.github.serpapi:serpapi:1.0.0'
23+
}
24+
```
25+
26+
To list all the version available.
27+
https://jitpack.io/api/builds/com.github.serpapi/serpapi
28+
29+
or you can download the jar file from https://github.com/serpapi/serpapi-java.git
30+
31+
Note: jitpack.io enables to download maven package directly from github release.
32+
33+
## Usage
34+
35+
To get started with this project in Java.
36+
We provided a fully working example.
37+
```bash
38+
git clone https://github.com/serpapi/serpapi-java.git
39+
cd serpapi-java/demo
40+
make run api_key=<your private key>
41+
```
42+
Note: You need an account with SerpApi to obtain this key from: https://serpapi.com/dashboard
43+
44+
file: demo/src/main/java/demo/App.java
45+
```java
46+
public class App {
47+
public static void main(String[] args) throws SerpApiException {
48+
if(args.length != 1) {
49+
System.out.println("Usage: app <secret api key>");
50+
System.exit(1);
51+
}
52+
53+
String location = "Austin,Texas";
54+
System.out.println("find the first Coffee in " + location);
55+
56+
// parameters
57+
Map<String, String> parameter = new HashMap<>();
58+
parameter.put("q", "Coffee");
59+
parameter.put("location", location);
60+
parameter.put("api_key", args[0]);
61+
62+
// Create search
63+
SerpApi serpapi = new SerpApi(parameter);
64+
65+
try {
66+
// Execute search
67+
JsonObject data = serpapi.search(parameter);
68+
69+
// Decode response
70+
JsonArray results = data.get("local_results").getAsJsonObject().get("places").getAsJsonArray();
71+
JsonObject first_result = results.get(0).getAsJsonObject();
72+
System.out.println("first coffee: " + first_result.get("title").getAsString() + " in " + location);
73+
} catch (SerpApiException e) {
74+
System.out.println("oops exception detected!");
75+
e.printStackTrace();
76+
}
77+
}
78+
}
79+
```
80+
81+
The [SerpApi.com API Documentation](https://serpapi.com/search-api) contains a list of all the possible parameters that can be passed to the API.
82+
83+
84+
## Documentation
85+
86+
Documentation is [available on Read the Docs](https://serpapi-python.readthedocs.io/en/latest/).
87+
88+
## Requirements
89+
90+
This project is an implementation of SerpApi in Java 7.
91+
This code depends on GSON for efficient JSON processing.
92+
The HTTP response are converted to JSON Object.
93+
94+
An example is provided in the test.
95+
@see src/test/java/SerpApiImplementationTest.java
96+
97+
Runtime:
98+
- Java / JDK 8+ (https://www.java.com/en/download/)
99+
Older version of java do not support HTTPS protocol.
100+
The SSLv3 is buggy which leads to Java raising this exception: javax.net.ssl.SSLHandshakeException
101+
102+
For development:
103+
- Gradle 6.7+ (https://gradle.org/install/)
104+
105+
106+
### Location API
107+
108+
```java
109+
Map<String, String> parameter = new HashMap<String, String>();
110+
parameter.put("api_key", System.getenv("API_KEY"));
111+
SerpApi serpapi = new SerpApi(parameter);
112+
113+
parameter.put("q", "Austin");
114+
parameter.put("limit", "3");
115+
JsonArray location = serpapi.location(parameter);
116+
System.out.println(location.toString());
117+
```
118+
it prints the first 3 location matching Austin (Texas, Texas, Rochester)
119+
120+
### Search Archive API
121+
122+
Let's run a search to get a search_id.
123+
```java
124+
Map<String, String> parameter = new HashMap<>();
125+
parameter.put("api_key", System.getenv("API_KEY"));
126+
parameter.put("q", "Coffee");
127+
parameter.put("location", "Austin, Texas, United States");
128+
parameter.put("hl", "en");
129+
parameter.put("gl", "us");
130+
parameter.put("google_domain", "google.com");
131+
parameter.put("safe", "active");
132+
parameter.put("start", "10");
133+
parameter.put("num", "10");
134+
parameter.put("device", "desktop");
135+
136+
SerpApi serpapi = new SerpApi(parameter);
137+
JsonObject results = serpapi.search(parameter);
138+
139+
140+
141+
```
142+
143+
Now let retrieve the previous search from the archive.
144+
```java
145+
// now search in the archive
146+
String id = results.getAsJsonObject("search_metadata").getAsJsonPrimitive("id").getAsString();
147+
148+
// retrieve search from the archive with speed for free
149+
JsonObject archive = serpapi.searchArchive(id);
150+
System.out.println(archive.toString());
151+
```
152+
it prints the search from the archive which matches 1:1 to previous search results.
153+
154+
### Account API
155+
Get account API
156+
```java
157+
Map<String, String> parameter = new HashMap<>();
158+
parameter.put("api_key", "your_api_key");
159+
160+
SerpApi serpapi = new SerpApi(parameter);
161+
JsonObject account = serpapi.account();
162+
System.out.println(account.toString());
163+
```
164+
it prints your account information.
165+
166+
### Contributing
167+
168+
We love true open source, continuous integration and Test Drive Development (TDD).
169+
We are using JUnit test, Git action, gradle [our infrastructure around the clock](https://travis-ci.org/serpapi/serpapi-java) to achieve the best QoS (Quality Of Service).
170+
171+
To run the test:
172+
```gradle test```
173+
174+
#### How to build from the source ?
175+
176+
You must clone this repository.
177+
```bash
178+
git clone https://github.com/serpapi/serpapi-java.git
179+
```
180+
Build the jar file.
181+
```bash
182+
gradle build
183+
```
184+
Copy the jar to your project lib/ directory.
185+
```bash
186+
cp build/libs/serpapi-java.jar path/to/yourproject/lib
187+
```
188+
189+
## Java limitation
190+
### SSL handshake error.
191+
#### symptom
192+
193+
javax.net.ssl.SSLHandshakeException
194+
195+
#### cause
196+
SerpApi is using HTTPS / SSLv3. Older JVM version do not support this protocol because it's more recent.
197+
198+
#### solution
199+
Upgrade java to 1.8_201+ (which is recommended by Oracle).
200+
201+
* On OSX you can switch versino of Java.
202+
```sh
203+
export JAVA_HOME=`/usr/libexec/java_home -v 1.8.0_201`
204+
java -version
205+
```
206+
207+
* On Windows manually upgrade your JDK / JVM to the latest.
208+
209+
### Inspiration
210+
* http://www.baeldung.com/java-http-request
211+
* https://github.com/google/gson
212+
213+
## License
214+
MIT license
215+
216+
## Changelog
217+
- 1.0.0 - Fully revisit API naming convention, and generalize client usage to match serpapi.com latest development
218+

README.erb.md renamed to README.md.erb

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# SerpApi Java Library
22

3-
![test](https://github.com/serpapi/google-search-results-java/workflows/test/badge.svg)
3+
![test](https://github.com/serpapi/serpapi-java/workflows/test/badge.svg)
44

55
Integrate search data into your Java application. This library is the official wrapper for SerpApi (https://serpapi.com).
66

@@ -166,10 +166,8 @@ it prints your account information.
166166
### Contributing
167167

168168
We love true open source, continuous integration and Test Drive Development (TDD).
169-
We are using RSpec to test [our infrastructure around the clock](https://travis-ci.org/serpapi/google-search-results-ruby) to achieve the best QoS (Quality Of Service).
169+
We are using JUnit test, Git action, gradle [our infrastructure around the clock](https://travis-ci.org/serpapi/serpapi-java) to achieve the best QoS (Quality Of Service).
170170

171-
The directory test/ includes specification/examples.
172-
173171
To run the test:
174172
```gradle test```
175173

0 commit comments

Comments
 (0)