We created Output Filters for each of our SDKs so that you can easily retrieve the API data that you're most interested in.
By now, you should have gone through one of the Output Filter tutorials and show have a good idea of what Output Filters are all about. As we've learned, an Output Filter is constructed with three parameters in the format:
Choreo.addOutputFilter(result_label, data_path, choreo_output).
In this tutorial, we'll focus on the data_path parameter in more detail. We'll demonstrate some of the small differences you'll encounter when dealing with JSON versus XML responses, and we'll also show some other tips and tricks for making the most of Output Filters.
These tips should translate to any of the languages supported in our SDKs, however, for the purpose of going through some examples we'll use Java.
The data_path is used to identify the particular item(s) within a JSON or XML response that you’d like to have returned. The data path can either be an XPath statement, or a JSON path. You can think of it as a map that tells Temboo where to find the data that we're interested in retrieving. The remainder is split into two sections, one focusing on data paths in XML and the other in JSON.
Since different datasets have characteristics and features that we can use to our benefit, we'll look at how to use Output Filters with datasets from the three following Choreos.
Let's say our goal is to use Yahoo! Weather to retrieve just the high forecast for each day of the week.
1Run the Yahoo > Weather > GetWeatherByAddress Choreo. Remember to print data to the console so that we can see what data is returned by adding the following line at the end of your code:
// print all of the results System.out.println(getWeatherByAddressResults.getOutputs());
You should see a long XML result, similar to the screenshot below.
(The full XML response has been shortened here for clarity)
2Identify the path that tells Temboo the location of those data elements. We’ll want to retrieve the value of the "day" and "high" attribute within the
/rss/channel/itemyweather:forecast/@day /rss/channel/itemyweather:forecast/@high
3Plugging these paths into output filters for Yahoo! Weather will look like this:
getWeatherByAddressInputs.addOutputFilter("day", "/rss/channel/item/yweather:forecast/@day", "Response");
getWeatherByAddressInputs.addOutputFilter("high", "/rss/channel/item/yweather:forecast/@high", "Response");
4Add the Output Filters right before the execute() method and run the code. Now we see just the data that we've filtered for:
{high=["77","71","72","77","79"], day=["Tue","Wed","Thu","Fri","Sat"]}
This is great, but we can make this data even more useful.
5Let's loop through each list of data so that we can correlate day and temperature with one another when we print to the console.
// System.out.println(GetWeatherByAddressResults.getOutputs());
for(int i = 0; i > GetWeatherByAddressChoreo.getResultList("day").length(); i++) {
System.out.println(GetWeatherByAddressChoreo.getResultList("day").get(i));
System.out.println(GetWeatherByAddressChoreo.getResultList("high").get(i));
}
Now each day is associated with the high forecast for that day.
6Let's get more specific with which day we'd like to know the high forecast for. We'll use the square bracket syntax to specify which element in the array you want. Array indices here start at 1 (rather than 0), so to retrieve the second element in the /rss/channel/yweather:forecast/@day array, you'd use:
/rss/channel/yweather:forecast[2]/@day /rss/channel/yweather:forecast[2]/@high
Let's say our goal is to retrieve a single element as well as a collection of child components from a parent. Specifically, we'll use Google Geocoding to retrieve the full formatted address and all of the individual address components that make up that address. First we need to see the XML data that is returned.
1Run the Google > Geocoding > GeocodeByAddress Choreo. Remember to print data to the console so that we can see the returned data by adding the following line at the end of your code:
// print all of the results System.out.println(geocodeByAddressResults.getOutputs());
You'll receive a long XML result, similar to the screenshot below. Since there's more information than we need, let's create an Output Filter.
2Identify the path that tells Temboo the location of the data elements of interest. If you follow the nested element names, you'll see formatted_address which provides the full address as a string, and multiple elements called long_name that give us the extended name of each part of the address. We can see that our XPath statements will be:
/GeocodeResponse/result/formatted_address /GeocodeResponse/result/address_component/long_name
3Plugging these paths into output filters for Google Geocoding will look like this:
geocodeByAddressInputs.addOutputFilter("address", "/GeocodeResponse/result/formatted_address", "Response");
geocodeByAddressInputs.addOutputFilter("components", "/GeocodeResponse/result/address_component/long_name", "Response");
4Let's add the Output Filters right before the execute() method. When we run the code now, we have just the data that we've filtered for:
{address=104 Franklin Street, New York, NY 10013, USA, components=["104","Franklin Street","Lower Manhattan","Manhattan","New York","New York County","New York","United States","10013"]}
5This is great, but it turns out that we can make this filtered data more useful by specifying the result_label when we call the getResultString() method in our print statement.
Replace the line System.out.println(geocodeByAddressResults.getOutputs()); with the following.
System.out.println(geocodeByAddressResults.getResultString("address");
6We can do the same for "components", however since this is a collection of elements. we'll use the getResultsList() function. Then we'll loop through and print out each list element on a new line. Let's give it a try:
for(int i = 0; i < geocodeByAddressResults.getResultList("components"). length(); i++) {
System.out.println(geocodeByAddressResults.getResultList("components"). get(i));
}
Now let's learn how to create Output Filters for the Choreos that return JSON results.
Let's say our goal is to retrieve several name/value pairs within an Array of JSON Objects. Specifically, we'll use the Twitter Search Choreo to parse the latest Tweets about robotics, the name of the person who Tweeted, and the time that the Tweet was published.
1Run the Twitter > Search > Tweets Choreo with "robotics" as the query input. Make sure to print outputs to console so that you can see what data is returned.
// print all of the results System.out.println(tweetResults.getOutputs());
You'll receive a long JSON result, similar to what you see below. Since there's more information than we need, let's create an Output Filter.
The first thing we'll need to do is identify the JSON path or data_path that tells Temboo the location of the data elements that we're interested in.
2You'll notice that within statuses, we can retrieve text for the Tweet, and user/screen_name for the Twitter handle. If we want to include when the Tweet was posted, we'll create a filter for statuses/created_at
/statuses/text /statuses/user/screen_name /statuses/created_at
3Plugging these paths into output filters for Twitter Search Tweets will look like this:
// create a filter for tweets
tweetInputs.addOutputFilter("statuses", "/statuses/text", "Response");
// create a filter for users
tweetInputs.addOutputFilter("users", "/statuses/user/screen_name", "Response");
// create a filter for dates
tweetInputs.addOutputFilter("dates", "/statuses/created_at", "Response");
4Add the output filters right before the execute() method. When we run the code now, we see just the data that we've filtered for.
{users=["_Talus","jlweich","goodlaura","huntsvillealnow","Plagia3","RoboticsNewsNow","RoboticsNewsNow","RoboticsNewsNow","RoboticsNewsNow","RoboticsNewsNow","RoboticsNewsNow","RoboticsNewsNow","RoboticsNewsNow","RoboticsNewsNow","RobotOverlord01","aislingmorrin","9232_5770","LeroyThomass","Ohal_robotics","OWI_Robotics"], dates=["Wed Jun 11 22:55:37 +0000 2014","Wed Jun 11 22:55:20 +0000 2014","Wed Jun 11 22:54:27 +0000 2014","Wed Jun 11 22:54:00 +0000 2014","Wed Jun 11 22:53:04 +0000 2014","Wed Jun 11 22:51:36 +0000 2014","Wed Jun 11 22:51:36 +0000 2014","Wed Jun 11 22:51:35 +0000 2014","Wed Jun 11 22:51:34 +0000 2014","Wed Jun 11 22:51:34 +0000 2014","Wed Jun 11 22:51:33 +0000 2014","Wed Jun 11 22:51:33 +0000 2014","Wed Jun 11 22:51:32 +0000 2014","Wed Jun 11 22:51:31 +0000 2014","Wed Jun 11 22:49:17 +0000 2014","Wed Jun 11 22:49:17 +0000 2014","Wed Jun 11 22:48:36 +0000 2014","Wed Jun 11 22:48:13 +0000 2014","Wed Jun 11 22:47:59 +0000 2014","Wed Jun 11 22:47:26 +0000 2014"], statuses=["Interesting: Robotics Helps Enrich Kids' Literacy - MyArkLaMiss: MyArkLaMiss Robotics Helps Enrich Kids' Literacy MyArkLaMiss \"They've...","I just backed #HummingbirdDuo: A Robotics Kit for Ages 10 to 110 on @Kickstarter and you should too! http://t.co/9dpkjBTfYM","Go Go Gadget Teens! >> Jesuit High underwater robotics team heading to Michigan to defend title http://t.co/lni8JL2oW9 via @Sacbiz","Bentley announces funds for third phase of Tanner robotics park: MADISON, Ala. (WAAY) - The Alabama Robotic... http://t.co/EyUaPXW1qO","RT @FranzTiani: Computer program passed the Turing Test for artificial intelligence.\nhttp://t.co/tjmlwJY86l\n#Robotics #AI #Software","Cheap, tiny robots serve as terrain scouts for expensive ones (video) - Engadget http://t.co/8bOIg7Eltj #Robot","Robotics Helps Enrich Kids' Literacy - MyArkLaMiss http://t.co/rxz5A1YmaL #Robot","MIT Develops Self-Assembling, Easy-Bake ]}
Great! Now let's get more specific. We could loop through each of the element lists and correlate Users with Tweets and timestamp.
5What if there is one Tweet we're really interested in? We can use the square bracket syntax to specify which element in the array index that we want. Array indices here start at 1 (rather than 0). So to retrieve the tenth element in the array for each filter, you'd use:
/statuses[10]/text /statuses[10]/user/screen_name /statuses[10]/created_at
Now you should be able to retrieve the data you need from any Choreo! Why not try filtering data on your own? If you'd like to try something different, you can try applying Output Filters to any of our 2000+ Choreos.
We're always happy to help. Just email us at support@temboo.com, and we'll answer your questions.