stream-applications/functions/function/twitter-function

# Twitter Functions

This module provides couple of twitter functions that can be reused and composed in other applications.

To use those functions add the following dependency to your POM:

[source,XML]
----
 <dependency>
   <groupId>org.springframework.cloud.fn</groupId>
   <artifactId>twitter-function</artifactId>
   <version>${java-functions.version}</version>
 </dependency>
----

## 1. Twitter Trend Function

Functions can return either Trends topics or the Locations of the trending topics. The `twitter.trend.trend-query-type` property allows choosing between both types.

* Trends - `twitter.trend.trend-query-type` is set to `trend`. Leverages the https://developer.twitter.com/en/docs/trends/trends-for-location/api-reference/get-trends-place[Trends API] to return the https://help.twitter.com/en/using-twitter/twitter-trending-faqs[trending topics] near a specific latitude, longitude location.

* Trend Locations - the `twitter.trend.trend-query-type` is set `trendLocation`. Retrieve a full or nearby locations list of trending topics by location. If the `latitude`, `longitude` parameters are NOT provided the processor performs the https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-available[Trends Available API] and returns the locations that Twitter has trending topic information for.
If the `latitude`, `longitude` parameters are provided the processor performs the https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-closest[Trends Closest API] and returns the locations that Twitter has trending topic information for, closest to a specified location.

Response is an array of `locations` that encode the location's WOEID and some other human-readable information such as a canonical name and country the location belongs in.

### 1.1 Beans for injection

You can import the `TwitterTrendFunctionConfiguration` in a Spring Boot application and then inject the following bean.

`filterFunction`

You can use `Function<Message<?>, Message<byte[]>> twitterTrendFunction` as a qualifier when injecting.

Once injected, you can use the `apply` method of the `Function` to invoke it and get the result.

### 1.2 Configuration Options

TIP: For `SpEL` expression properties wrap the literal values in single quotes (`'`).

For more information on the various options available, please see link:../twitter-function/src/main/java/org/springframework/cloud/fn/twitter/trend/TwitterTrendFunctionProperties.java[TwitterTrendFunctionProperties.java]

### 1.3 Tests
See this link:src/test/java/org/springframework/cloud/fn/twitter/trend/TwitterTrendFunctionTests.java[test suite] for examples of how this function is used.

### 1.4 Other usage

Leveraging the Spring Cloud Function composability, you can compose the Trend function in your boot app like this:

[source,Java]
----
@SpringBootApplication
@Import(TwitterTrendFunctionConfiguration.class )
public class MyTwitterTrendBootApp {

	public static void main(String[] args) {
		SpringApplication.run(MyTwitterTrendBootApp.class,
		    "--spring.cloud.function.definition=trend|twitterTrendFunction|managedJson");
	}
}
----

## 2. Twitter Geo Function.

Function based on the https://developer.twitter.com/en/docs/geo/places-near-location/overview[Geo API] that retrieves Twitter place information based on query parameters such as (`latitude`, `longitude`) pair, an `IP` address, or a place `name`.

There are two types for geo search queries `search` and `reverse` controlled by the `twitter.geo.search.type` property.

* reverse - Given a latitude and a longitude, searches for up to 20 places that can be used as a `placeId` when updating a status.
This request is an informative call and will deliver generalized results about geography.

* search - Search for places that can be attached to statuses/update. Given a latitude and a longitude pair, an IP address, or a name, this request will return a list of all the valid places that can be used as the place_id when updating a status.

Conceptually, a query can be made from the user’s location, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location with a call to POST statuses/update.

This is the recommended method to use find places that can be attached to statuses/update. Unlike GET geo/reverse_geocode which provides raw data access, this endpoint can potentially re-order places with regard to the user who is authenticated. Use this approach for interactive place matching with the user.

Some parameters in this method are only required based on the existence of other parameters. For instance, “lat” is required if “long” is provided, and vice-versa. Authentication is recommended, but not required with this method.

NOTE: Limits: 15 requests / 15-min window (user auth).

### 2.1 Beans for injection

You can import the `TwitterGeoFunctionConfiguration` in a Spring Boot application and then inject the following bean.

`filterFunction`

You can use `Function<Message<?>, Message<byte[]>> twitterGeoFunction` as a qualifier when injecting.
Once injected, you can use the `apply` method of the `Function` to invoke it and get the result.

### 2.2 Configuration Options

TIP: For `SpEL` expression properties wrap the literal values in single quotes (`'`).

For more information on the various options available, please see link:../twitter-function/src/main/java/org/springframework/cloud/fn/twitter/geo/TwitterGeoFunctionProperties.java[TwitterGeoFunctionProperties.java]

### 2.3 Tests

See this link:src/test/java/org/springframework/cloud/fn/twitter/geo/TwitterGeoFunctionTest.java[test suite] for examples of how this function is used.

### 2.4 Other usage

Leveraging the Spring Cloud Function composability, you can compose the Geo function in your boot app like this:

[source,Java]
----
@SpringBootApplication
@Import(TwitterGeoFunctionConfiguration.class )
public class MyTwitterGeoProcessorBootApp {

	public static void main(String[] args) {
		SpringApplication.run(MyTwitterGeoProcessorBootApp.class,
		    "--spring.cloud.function.definition=messageToGeoQueryFunction|twitterSearchPlacesFunction|managedJson");
	}
}
----

## 3. Twitter Users Function

Retrieves users either by list of use ids and/or screen-names (https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup[Users Lookup API]) or by text search query (https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search[Users Search API]).
Uses SpEL expressions to compute the query parameters from the input message.
Use the single quoted literals to set static values (e.g. user-id: '6666, 9999, 10000').

Use `twitter.users.type` property allow to select the query approaches.

* https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup[Users Lookup API] - Returns fully-hydrated user objects for up to 100 users per request, as specified by comma-separated values passed to the `userId` and/or `screenName` parameters. Rate limits: (300 requests / 15-min window)
* https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search[Users Search API] - Relevance-based search interface to public user accounts on Twitter.
Querying by topical interest, full name, company name, location, or other criteria. Exact match searches are not supported. Only the first 1,000 matching results are available. Rate limits:(900 requests / 15-min window)

### 3.1 Beans for injection

You can import the `TwitterUsersFunctionConfiguration` in a Spring Boot application and then inject the following bean.

`filterFunction`

You can use `Function<Message<?>, Message<byte[]>> twitterUsersFunction` as a qualifier when injecting.
Once injected, you can use the `apply` method of the `Function` to invoke it and get the result.


### 3.2 Configuration Options

TIP: For `SpEL` expression properties wrap the literal values in single quotes (`'`).

For more information on the various options available, please see link:../twitter-function/src/main/java/org/springframework/cloud/fn/twitter/users/TwitterUsersFunctionProperties.java[TwitterUsersFunctionProperties.java]

### 3.3 Tests
See this link:src/test/java/org/springframework/cloud/fn/twitter/users/TwitterUsersFunctionTests.java[test suite] for examples of how this function is used.

### 3.4 Other usage