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
Show all changes
37 commits
Select commit Hold shift + click to select a range
ab9fb56
initial commit. rename package due to #3
xSAVIKx Feb 18, 2016
bfc296e
update gradle build information
xSAVIKx Feb 19, 2016
0fd6654
code refactored hardly
xSAVIKx Feb 19, 2016
8d5065e
added unit tests and javadoc
xSAVIKx Feb 21, 2016
b0a326a
added exception handling support
xSAVIKx Feb 22, 2016
021c857
remove javadoc from repo and update readme
xSAVIKx Feb 22, 2016
d4eb322
separate client from query and change Language enum a bit
xSAVIKx Feb 23, 2016
8a08295
check in travis CI config file
xSAVIKx Feb 23, 2016
81acc40
Update .travis.yml
xSAVIKx Feb 23, 2016
f69ba59
Update .travis.yml
xSAVIKx Feb 23, 2016
6f077a8
add build status to readme
xSAVIKx Feb 23, 2016
a07a499
added support for env API key. added betamax dependencies
xSAVIKx Feb 23, 2016
37fcf95
Update build.gradle
xSAVIKx Feb 24, 2016
b5fbfa4
added groovy support for spock tests
xSAVIKx Feb 24, 2016
56540b9
fix gradlew execution permissions
xSAVIKx Feb 29, 2016
a476f32
fix gradlew execution permissions
xSAVIKx Feb 29, 2016
9514010
Merge remote-tracking branch 'origin/master'
xSAVIKx Feb 29, 2016
d8ec63e
Updated gradlew and gradlew.bat permissions from ubuntu
xSAVIKx Feb 29, 2016
97bacfe
refactored clients and removed betamax from dependencies
xSAVIKx Feb 29, 2016
9b61fee
updated build for future publising, updated javadoc and readme
xSAVIKx Feb 29, 2016
edd3b90
added fixture tests
xSAVIKx Feb 29, 2016
ba05bac
fix travis CI build
xSAVIKx Feb 29, 2016
b0f5040
update test for travis ci
xSAVIKx Feb 29, 2016
e92a1d1
Merge remote-tracking branch 'origin/master'
xSAVIKx Feb 29, 2016
56f3f0e
update jaxb-dependency and fix unmarshalling test for java 1.7
xSAVIKx Feb 29, 2016
2eb1db8
ensure file ends with new line, remove license obsolete file and misc…
xSAVIKx Mar 2, 2016
f055f46
#1 - removed ApacheHttpClient as obsolete
xSAVIKx Mar 2, 2016
9d3e2a0
#3 extend exception types and refactor domain model
xSAVIKx Mar 2, 2016
6cce8c5
#3 update readme with new exception types
xSAVIKx Mar 2, 2016
4ad5066
#4 #7 - added lists initialization in Post and Result. Added filtrati…
xSAVIKx Mar 2, 2016
2c8a771
#5 extended test to test all properties of minimal valid result
xSAVIKx Mar 2, 2016
2029b44
#6 Empty searchpattern should throw exception
xSAVIKx Mar 2, 2016
31479d4
#5 extended test to test all properties of minimal valid result
xSAVIKx Mar 2, 2016
23091f2
#8 updated system property for twingly search key and readme
xSAVIKx Mar 3, 2016
82ed813
added examples
xSAVIKx Mar 3, 2016
a4d2445
update build.gradle for example to fix build
xSAVIKx Mar 3, 2016
aefe054
updated SearchPostsStream example
xSAVIKx Mar 3, 2016
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
112 changes: 112 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Created by .ignore support plugin (hsz.mobi)
### Maven template
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
pom.xml.next
release.properties
dependency-reduced-pom.xml
buildNumber.properties
.mvn/timing.properties
### JetBrains template
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio

*.iml

## Directory-based project format:
.idea/
# if you remove the above rule, at least ignore the following:

# User-specific stuff:
# .idea/workspace.xml
# .idea/tasks.xml
# .idea/dictionaries

# Sensitive or high-churn files:
# .idea/dataSources.ids
# .idea/dataSources.xml
# .idea/sqlDataSources.xml
# .idea/dynamic.xml
# .idea/uiDesigner.xml

# Gradle:
# .idea/gradle.xml
# .idea/libraries

# Mongo Explorer plugin:
# .idea/mongoSettings.xml

## File-based project format:
*.ipr
*.iws

## Plugin-specific files:

# IntelliJ
/out/

# mpeltonen/sbt-idea plugin
.idea_modules/

# JIRA plugin
atlassian-ide-plugin.xml

# Crashlytics plugin (for Android Studio and IntelliJ)
com_crashlytics_export_strings.xml
crashlytics.properties
crashlytics-build.properties
### Gradle template
.gradle
build/

# Ignore Gradle GUI config
gradle-app.setting

# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
!gradle-wrapper.jar
### Eclipse template
*.pydevproject
.metadata
bin/
tmp/
*.tmp
*.bak
*.swp
*~.nib
local.properties
.settings/
.loadpath

# Eclipse Core
.project

# External tool builders
.externalToolBuilders/

# Locally stored "Eclipse launch configurations"
*.launch

# CDT-specific
.cproject

# JDT-specific (Eclipse Java Development Tools)
.classpath

# Java annotation processor (APT)
.factorypath

# PDT-specific
.buildpath

# sbteclipse plugin
.target

# TeXlipse plugin
.texlipse
### Java template
*.class

# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*

5 changes: 5 additions & 0 deletions .travis.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
language: java
jdk:
- openjdk7
- oraclejdk7
- oraclejdk8
36 changes: 0 additions & 36 deletions BuildJar.xml

This file was deleted.

24 changes: 0 additions & 24 deletions LICENSE.txt

This file was deleted.

115 changes: 104 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,117 @@
# twingly-analytics-api-java
# twingly-search-api-java [![Build Status](https://travis-ci.org/xSAVIKx/twingly-search-api-java.svg?branch=master)](https://travis-ci.org/xSAVIKx/twingly-search-api-java)

Java API for [Twingly Search](http://developer.twingly.com/resources/search/) (previously known as Twingly Analytics).
Java API for [Twingly Search](https://developer.twingly.com/resources/search/) (previously known as Twingly Analytics).

To use the API you need an API key. To obtain an API key, contact us at [email protected].

### Example usage
## Example usage

```Java
Query q = new Query(yourApiKey); // create a request object using your api key
q.setDocumentLang("en"); // only search for posts in english
Result result = q.makeRequest("spotify"); // find posts containing the word spotify
for (Post p : result.getPosts())
System.out.println(p.getUrl()); // print the url for each post
// create Query object using your API key

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be good to have the needed imports listed in the example too and wrap this in a main method.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not full example, while I'll provide one later today, so I think there is no need for such imports and main method in readme file.

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

Later you can repeat the search for any new posts that have come in since your last request:
Later you can repeat the search for any new posts with same or other parameters:

```Java
q.setStartTime(result.getNewestPost()); // only search for posts newer than the last result
result = q.makeRequest("spotify"); // request new posts containing the word spotify
// 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


### 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`):
```Java
Query query = new Query(); // create query 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:
```gradle
gradlew build -DTWINGLY_SEARCH_KEY=some_key_value
```
## Requirements

* API key, contact [sales](mailto:[email protected]) via [twingly.com](https://www.twingly.com/try-for-free/) to get one
* Java:
* v 1.7
* v 1.8


## Development

### Tests

Make sure you have all the dependencies
```gradle
gradlew assemble
```
Run the tests
```
gradlew check
```

### Exception handling

Given exception hierarchy is now available:
* TwinglySearchException - super class for any TwinglySearch-related exception
* TwinglySearchServerException - super class for all server exceptions
* TwinglySearchServerAPIKeyDoesNotExistException - should be thrown when no API key was found
* TwinglySearchServerAPIKeyUnauthorizedException - should be thrown when API key is not authorized for any action
* TwinglySearchServerServiceUnavailableException - should be thrown when service is not available

### JavaDoc generation

To generate java docs just run gradle task `javadoc`:
```
gradlew javadoc
```
This will save javadocs in `docs` folder under build-folder.


### One-jar generation

To generate one fat jar library with all compile dependencies just run gradle task `generateOneJar`:
```
gradlew generateOneJar
```
This will save JAR file with all needed dependencies in `build/libs/` with `-all` suffix. (like `twingly-search-api-java-all-0.0.1.jar`)

## License

The MIT License (MIT)

Copyright (c) 2012-2016 Twingly AB

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Loading