Skip to content
This repository was archived by the owner on Jun 8, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 31 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,39 +5,31 @@ Java client for Twingly Search API (previously known as Twingly Analytics API).
## Example usage

```Java
// create Query object using your API key
Query query = new Query(apiKey);

// find posts containing word "spotify" in English language created from startDate to endDate
Result result = query.makeRequest("spotify", Language.English, startDate, endDate);
import com.twingly.search.*;
public class Test{
public static void main(String[] args){
String apiKey = "API_KEY";
// create Client object using your API key
Client client = new UrlConnectionClient(apiKey);
// Create Query object using QueryBuilder for results in English published from startTime to endTime
Query query = QueryBuilder.create("spotify").documentLanguage(Language.English).startTime(startTime).endTime(endTime).build();
Result result = client.makeRequest(query);
// Get the total number of matches returned
int numberOfMatchesReturned = result.getNumberOfMatchesReturned();
// Get the total number of matches to the search query
int numberOfMatchesTotal = result.getNumberOfMatchesTotal();
// Get number of seconds it took to execute query
double secondsElapsed = result.getSecondsElapsed();
for (Post p : result.getPosts()){
System.out.println(p.getUrl()); // print url for each post
System.out.println(p.getTitle()); // print title for each post
}
}
}

// Get the total number of matches returned
int numberOfMatchesReturned = result.getNumberOfMatchesReturned();

// Get the total number of matches to the search query
int numberOfMatchesTotal = result.getNumberOfMatchesTotal();

// Get number of seconds it took to execute query
double secondsElapsed = result.getSecondsElapsed();

// Iterate through the results
for (Post p : result.getPosts())
System.out.println(p.getUrl()); // print url for each post
System.out.println(p.getTitle()); // print title for each post
```

Later you can repeat the search for any new posts with same or other parameters:

```Java
// find posts containing word "spotify" in English language created from startDate (up to now)
query.makeRequest("spotify", Language.English, startDate);

// find posts containing word "spotify" in English language (all posts, without any time limits)
query.makeRequest("spotify", Language.English);

// find posts containing word "spotify" (all posts, withou time and language limits)
query.makeRequest("spotify");
```
A Query object can be reused for several requests.

To learn more about the features of this client, check out the example code that can be found in [example](example).

Expand All @@ -47,16 +39,21 @@ To learn more about the capabilities of the API, please read the [Twingly Search

### API key from Java system properties

Additionally, you can create Query object with API key from Java system properties (property name is `TWINGLY_SEARCH_KEY`):
Additionally, you can create Client object with API key from Java system properties (property name is `TWINGLY_SEARCH_KEY`):

```Java
Query query = new Query(); // create query object with API key from java system property
import com.twingly.search.client.*;
public class Test{
public static void main(String[] args){
Client client = new UrlConnectionClient(); // create client object with API key from java system property
}
}
```

To do so, you will need to run Java with property. For example, run `gradlew` with twingly search key property:
To do so, you will need to run Java with property. For example, run your own `jar` file with twingly search key property:

```
gradlew build -DTWINGLY_SEARCH_KEY=some_key_value
java -jar myJar.jar -DTWINGLY_SEARCH_KEY=some_key_value
```

### Exception handling
Expand Down
2 changes: 0 additions & 2 deletions example/build.gradle
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
version '1.0.0'

apply plugin: 'java'

sourceCompatibility = 1.7
Expand Down
10 changes: 6 additions & 4 deletions example/src/main/java/HelloWorld.java
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
import com.twingly.search.Query;
import com.twingly.search.QueryBuilder;
import com.twingly.search.client.Client;
import com.twingly.search.client.UrlConnectionClient;
import com.twingly.search.domain.Post;
import com.twingly.search.domain.Result;

Expand All @@ -10,11 +13,10 @@ public class HelloWorld {

public static void main(String[] args) {
// set java system property TWINGLY_SEARCH_KEY
Query query = new Query();
Date startDate = new Date(System.currentTimeMillis() - ONE_DAY);
String queryString = query.buildRequestQuery("\"Hello World!\"", null,
startDate, null);
Result result = query.query(queryString);
Query query = QueryBuilder.create("\"Hello World!\"").startTime(startDate).build();
Client client = new UrlConnectionClient();
Result result = client.makeRequest(query);
for (Post post : result.getPosts()) {
System.out.println(post.getUrl());
}
Expand Down
27 changes: 15 additions & 12 deletions example/src/main/java/SearchPostsStream.java
Original file line number Diff line number Diff line change
@@ -1,24 +1,33 @@
import com.twingly.search.Query;
import com.twingly.search.QueryBuilder;
import com.twingly.search.client.Client;
import com.twingly.search.client.UrlConnectionClient;
import com.twingly.search.domain.Post;
import com.twingly.search.domain.Result;

public class SearchPostsStream {
private static final String USER_AGENT = "MyCompany/1.0";
private Query query;
private final String searchPattern;
private Client client;
private Query query;
private int counter;

public SearchPostsStream(String keyword) {
searchPattern = String.format("sort-order:asc sort:published %s", keyword);
Client client = new UrlConnectionClient();
client = new UrlConnectionClient();
client.setUserAgent(USER_AGENT);
query = new Query(client);
query = QueryBuilder.create(searchPattern).build();
}

public static void main(String[] args) {
// set java system property TWINGLY_SEARCH_KEY
SearchPostsStream searchPostsStream = new SearchPostsStream("(github) AND (hipchat OR slack)");
searchPostsStream.each();
System.out.println("Iterated through " + searchPostsStream.getCount() + " results");
}

public void each() {
Result result = query.makeRequest(searchPattern);
Result result = client.makeRequest(query);
iterateAllPosts(result);
}

Expand All @@ -35,14 +44,8 @@ private void iterateAllPosts(Result result) {
return;
}
Post lastPost = result.getPosts().get(result.getPosts().size() - 1);
Result newResult = query.makeRequest(searchPattern, null, lastPost.getPublished());
query.setStartTime(lastPost.getPublished());
Result newResult = client.makeRequest(query);
iterateAllPosts(newResult);
}

public static void main(String[] args) {
// set java system property TWINGLY_SEARCH_KEY
SearchPostsStream searchPostsStream = new SearchPostsStream("(github) AND (hipchat OR slack)");
searchPostsStream.each();
System.out.println("Iterated through " + searchPostsStream.getCount() + " results");
}
}
2 changes: 1 addition & 1 deletion src/main/java/com/twingly/search/DateAdapter.java
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
* @see Constants#DATE_FORMAT
*/
public class DateAdapter extends XmlAdapter<String, Date> {
private SimpleDateFormat dateFormat = new SimpleDateFormat(Constants.DATE_FORMAT);
private final SimpleDateFormat dateFormat = new SimpleDateFormat(Constants.DATE_FORMAT);

/**
* {@inheritDoc}
Expand Down
Loading