org.agorava.twitter.model

Interface SearchService

public interface SearchService

Interface defining the operations for searching Twitter and retrieving trending data.

Author:

Craig Walls, Antoine Sabot-Durand

Method Summary

Methods

Modifier and Type	Method and Description
SavedSearch	createSavedSearch(String query) Creates a new saved search for the authenticating user.
void	deleteSavedSearch(long searchId) Deletes a saved search
List<Trends>	getDailyTrends() Retrieves the top 20 trending topics, hourly for the past 24 hours.
List<Trends>	getDailyTrends(boolean excludeHashtags) Retrieves the top 20 trending topics, hourly for the past 24 hours.
List<Trends>	getDailyTrends(boolean excludeHashtags, String startDate) Retrieves the top 20 trending topics, hourly for a 24-hour period starting at the specified date.
Trends	getLocalTrends(long whereOnEarthId) Retrieves the top 10 trending topics for a given location, identified by its "Where on Earth" (WOE) ID.
Trends	getLocalTrends(long whereOnEarthId, boolean excludeHashtags) Retrieves the top 10 trending topics for a given location, identified by its "Where on Earth" (WOE) ID.
SavedSearch	getSavedSearch(long searchId) Retrieves a single saved search by the saved search's ID.
List<SavedSearch>	getSavedSearches() Retrieves the authenticating user's saved searches.
List<Trends>	getWeeklyTrends() Retrieves the top 30 trending topics for each day in the past week.
List<Trends>	getWeeklyTrends(boolean excludeHashtags) Retrieves the top 30 trending topics for each day in the past week.
List<Trends>	getWeeklyTrends(boolean excludeHashtags, String startDate) Retrieves the top 30 trending topics for each day in a given week.
SearchResults	search(String query) Searches Twitter, returning the first 50 matching Tweets
SearchResults	search(String query, int page, int pageSize) Searches Twitter, returning a specific page out of the complete set of results.
SearchResults	search(String query, int page, int pageSize, long sinceId, long maxId) Searches Twitter, returning a specific page out of the complete set of results.

Method Detail

search

SearchResults search(String query)

Searches Twitter, returning the first 50 matching Tweets

Parameters:

query - The search query string

Returns:

a SearchResults containing the search results metadata and a list of matching Tweets

Throws:

ApiException - if there is an error while communicating with Twitter.

See Also:

SearchResults, Tweet

search

SearchResults search(String query,
                   int page,
                   int pageSize)

Searches Twitter, returning a specific page out of the complete set of results.

Parameters:

query - The search query string

page - The page to return

pageSize - The number of Tweets per page

Returns:

a SearchResults containing the search results metadata and a list of matching Tweets

Throws:

ApiException - if there is an error while communicating with Twitter.

See Also:

SearchResults, Tweet

search

SearchResults search(String query,
                   int page,
                   int pageSize,
                   long sinceId,
                   long maxId)

Searches Twitter, returning a specific page out of the complete set of results. Results are filtered to those whose ID falls between sinceId and maxId.

Parameters:

query - The search query string

page - The page to return

pageSize - The number of Tweets per page

sinceId - The minimum Tweet ID to return in the results

maxId - The maximum Tweet ID to return in the results

Returns:

a SearchResults containing the search results metadata and a list of matching Tweets

Throws:

ApiException - if there is an error while communicating with Twitter.

See Also:

SearchResults, Tweet

getSavedSearches

List<SavedSearch> getSavedSearches()

Retrieves the authenticating user's saved searches.

Returns:

a list of SavedSearch items

Throws:

ApiException - if there is an error while communicating with Twitter.

MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getSavedSearch

SavedSearch getSavedSearch(long searchId)

Retrieves a single saved search by the saved search's ID.

Parameters:

searchId - the ID of the saved search

Returns:

a SavedSearch

Throws:

ApiException - if there is an error while communicating with Twitter.

MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

createSavedSearch

SavedSearch createSavedSearch(String query)

Creates a new saved search for the authenticating user.

Parameters:

query - the search query to save

Returns:

the SavedSearch

Throws:

ApiException - if there is an error while communicating with Twitter.

MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

deleteSavedSearch

void deleteSavedSearch(long searchId)

Deletes a saved search

Parameters:

searchId - the ID of the saved search

Throws:

ApiException - if there is an error while communicating with Twitter.

MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getDailyTrends

List<Trends> getDailyTrends()

Retrieves the top 20 trending topics, hourly for the past 24 hours. This list includes hashtagged topics.

Returns:

a list of Trends objects, one for each hour in the past 24 hours, ordered with the most recent hour first.

Throws:

ApiException - if there is an error while communicating with Twitter.

getDailyTrends

List<Trends> getDailyTrends(boolean excludeHashtags)

Retrieves the top 20 trending topics, hourly for the past 24 hours.

Parameters:

excludeHashtags - if true, hashtagged topics will be excluded from the trends list.

Returns:

a list of Trends objects, one for each hour in the past 24 hours, ordered with the most recent hour first.

Throws:

ApiException - if there is an error while communicating with Twitter.

getDailyTrends

List<Trends> getDailyTrends(boolean excludeHashtags,
                          String startDate)

Retrieves the top 20 trending topics, hourly for a 24-hour period starting at the specified date.

Parameters:

excludeHashtags - if true, hashtagged topics will be excluded from the trends list.

startDate - the date to start retrieving trending data for, in MM-DD-YYYY format.

Returns:

a list of Trends objects, one for each hour in the given 24 hours, ordered with the most recent hour first.

Throws:

ApiException - if there is an error while communicating with Twitter.

getWeeklyTrends

List<Trends> getWeeklyTrends()

Retrieves the top 30 trending topics for each day in the past week. This list includes hashtagged topics.

Returns:

a list of Trends objects, one for each day in the past week, ordered with the most recent day first.

Throws:

ApiException - if there is an error while communicating with Twitter.

getWeeklyTrends

List<Trends> getWeeklyTrends(boolean excludeHashtags)

Retrieves the top 30 trending topics for each day in the past week.

Parameters:

excludeHashtags - if true, hashtagged topics will be excluded from the trends list.

Returns:

a list of Trends objects, one for each day in the past week, ordered with the most recent day first.

Throws:

ApiException - if there is an error while communicating with Twitter.

getWeeklyTrends

List<Trends> getWeeklyTrends(boolean excludeHashtags,
                           String startDate)

Retrieves the top 30 trending topics for each day in a given week.

Parameters:

excludeHashtags - if true, hashtagged topics will be excluded from the trends list.

startDate - the date to start retrieving trending data for, in MM-DD-YYYY format.

Returns:

a list of Trends objects, one for each day in the given week, ordered with the most recent day first.

Throws:

ApiException - if there is an error while communicating with Twitter.

getLocalTrends

Trends getLocalTrends(long whereOnEarthId)

Retrieves the top 10 trending topics for a given location, identified by its "Where on Earth" (WOE) ID. This includes hashtagged topics. See http://developer.yahoo.com/geo/geoplanet/guide/concepts.html for more information on WOE.

Parameters:

whereOnEarthId - the Where on Earth ID for the location to retrieve trend data.

Returns:

A Trends object with the top 10 trending topics for the location.

Throws:

ApiException - if there is an error while communicating with Twitter.

getLocalTrends

Trends getLocalTrends(long whereOnEarthId,
                    boolean excludeHashtags)

Retrieves the top 10 trending topics for a given location, identified by its "Where on Earth" (WOE) ID. See http://developer.yahoo.com/geo/geoplanet/guide/concepts.html for more information on WOE.

Parameters:

whereOnEarthId - the Where on Earth ID for the location to retrieve trend data.

excludeHashtags - if true, hashtagged topics will be excluded from the trends list.

Returns:

A Trends object with the top 10 trending topics for the given location.

Throws:

ApiException - if there is an error while communicating with Twitter.