Category:RSS Reference

From KickApps API Reference

Contents 1 Introduction 2 Generating a feedID in the KickApps Feed Builder application 3 Configuring your custom RSS feeds using the generic URL 4 The best of both worlds 5 Some tips for the road 6 Configurable Parameters for RSS

Introduction

The KickApps RSS Feed API allows you to search all of your community's data (members, media, message board posts, groups, etc.), and sort and filter the results using a variety of parameters. For example you could create a list of the 50 most popular videos that have been uploaded to your community and tagged with "nature", or the 10 female community members with the most comments on their profile.

KickApps RSS Feeds can be accessed via two methods:

• by referencing a specific feedID in the RSS Feed URL
• by including a variety of configurable parameters in a generic RSS Feed URL

Generating a feedID in the KickApps Feed Builder application

You can access the Feed Builder's web-based interface in the Affiliate Center, under the App Studio tab. Simply click the Feed Builder subnavigation link and click the blue Create button to start building feeds.

When you create RSS feeds within the Feed Builder, it generates a URL with a feed like this:

http://serve.a-feed.com/service/getFeed.kickAction?feedId=####&as=####

Because the feed is defined by the feedId variable in the URL, you can change the feed's configuration (sorts and filters) in the Feed Builder and the feed contents will automatically be updated as soon as you save the changes.

Cool stuff, right? Well, it gets better...

Configuring your custom RSS feeds using the generic URL

You do not need a feedID in order to search your community via the RSS Feed API. All you need is this base URL:

http://serve.a-feed.com/service/getFeed.kickAction?as=####

(Note: If you have DNS masking enabled, you can use your DNS-masked domain, though the feeds will load less quickly.)

Grab the URL above and replace the "#" symbols with your AS number (you can see it in the URLs of any of your KickApps-powered community pages). You'll see a feed that is set with all of our default parameters, showing the 50 most recent videos, audio tracks, photos, blog posts, and members for your site.

Using the DubAndReggae community (AS ID = 5057) as an example, if you wanted to create that list of the 20 most recent videos, you could use this feed URL:

http://serve.a-feed.com/service/getFeed.kickAction?as=5057&mediaType=videos&sortType=recent&quantity=20

Remember that because you're defining the feed parameters in the URL instead of via a feedId variable, there's no management interface for this feed in the Affiliate Center — you've skipped right over it. If you want to edit this feed's configuration, you should do it directly within the URL.

The best of both worlds

Now that you've seen preconfigured feeds (defined by IDs) and custom feed configurations (defined by URL parameters), let's mix em up! To review, if you create a feed in the Affiliate Center Feed Manager, you'll see a URL that looks like

http://serve.a-feed.com/service/getFeed.kickAction?feedId=####&as=####

You can further customize this feed by adding or overriding any parameters you've set within the Feed Builder by simply adding variables to the URL. For example, if you create a feed that only contains your community's most recent videos in the Feed Builder, you could override the settings to show your most recent videos and photos with a new URL, like this:

http://serve.a-feed.com/service/getFeed.kickAction?feedId=####&as=####&mediaType=video,photo

You can use this to reconfigure sort orders, number of results, the list goes on and on!

The RSS feed content is generated on the fly per request, so using URL parameters to override a feed's settings won't affect other instances of your RSS feed that share the same feedId.

Some tips for the road

• Four “special characters” are reserved as operators in our feeds system. If you use any of these characters in the arguments that you pass to us, they must be converted to their URL-encoded values. (? should be %3F), (= should be %3D), (& should be %26), (# should be %23).
• URL-encode multiword strings within the feed URLs. For instance, if you want to find all media with titles that include "great vid," you'd use mediaTitle=great%20vid (%20 is the URL code for a space).
• Asterisks serve as wildcard values when placed at the beginning or end of any of the strings that support comma-separated lists. As an example, "dog*" would return results for dog, dogs, and doghouse.
• Multiple filter variables are treated as a logical AND (all must be true in order for the result to be included). When multiple values are allowed for a single variable they're treated as a logical OR statement.
• Some of these parameters won't mix and match. For instance, if you set mediaType to "blog" and filter on a forum, you won't get any results. Groups, Forums, and Discussions are three filters that can limit your options. To get a sense of what's available within each, take a look at the relevant KickApps-powered pages.
• If you set mediaType=tags, you can create a tag cloud (we automatically sort tags by their popularity and always return 50 listings).
• Tired of Member Widgets full of default images? Set memberHasProfilePhoto=on to create a feed of members who have included their profile photos.
• Use the members= argument to create a feed of contributions from one or more special members.
• Use the fromDate and toDate arguments to restrict the feed to only include contributions made within a specific timeframe.
• Don't worry about making a mistake – if you enter an invalid parameter or value, we'll simply ignore it and give you and the result set won't be affected.
• The mediaDesc parameter, added March 21, searches media descriptions and member "about me" and custom question responses.
• You can paginate your feed with then quantity, p, and totalItems arguments, for longer results. If you leave these arguments undeclared then the p value defaults to 1 if it's left blank; the quantity value defaults to 1000. As an example, a feed for the second page of most recent results with 25 results per page would look like this:

http://serve.a-feed.com/service/getFeed.kickAction?as=####&quantity=25&p=2&totalItems=1000

• If you assign an empty or invalid value to a parameter, we'll simply use the default value for each parameter.

Go to your site and give it a shot. If you find a great use for your community's Feed Builder, let us know on the KickDeveloper message boards – we'd love to hear about how you're using it.

The parameter names below are case sensitive if you use the incorrect case they will use the parameters default value.

Configurable Parameters for RSS

Variable	Value	Description	Required?
as	REQUIRED Integer.	Your affiliate site ID.	Y
adminTags	String. One or more comma-separated admin tags.	Filters for all content which contains the specified string(s). Note: There is a logical "AND" option for admin tag queries. Typically, RSS feed parameters that accept multiple comma-separated values treat those values as a logical OR (meaning the feed will include results that match any of the values). To use the logical AND argument, simply add "AND:" before the list of comma-separated admin tags, for example: "adminTags=AND:dog,cat" will filter the feed to only include results that were admin tagged both dog and cat.	N
categories	String. Any of your categories (comma separated for multiple categories); you can also use categoryName>subcategoryName to indicate a subcategory within a category.	Filters for results that have been assigned to the media categories and subcategories.	N
city	String. City name (single value).	Filters for all content that has been assigned to that city.	N
country	String. Country name (single value).	Filters for the given country.	N
discussion	String. A discussion title (single value).	Filters for message board posts within the specified discussion.	N
firstName	String. A member's first name.	Filters for members with a matching first name and groups that have at least one member with a matching first name. Use with the group and user mediaType arguments.	N
forum	String. A forum title (single value).	Filters for message board posts within the specified forum.	N
fromDate	String. {MM-dd-yyyy} format.	Filters for results that were created after this date.	N
groupID	Integer. One or more comma separated group ID's.	Filters for media and members that have been associated with the specified groups.	N
groups	String. One or more comma separated group names.	Filters for media and members that have been associated with the specified groups.	N
includeiTunes	true.	Will instruct the feed to include the nodes necessary for iTunes indexing.	N
keywords	String. One or more comma-separated search terms.	Filters for media with the search term(s) within the tags, admin tags, media title, media description and username.	N
lastName	String. A member's last name.	Filters for members with a matching last name and groups that have at least one member with a matching last name. Use with the group and user mediaType arguments.	N
level	String. One or more comma-separated search terms.	Used with the "mediaType=user" argument, filters for members who have the specified level. (For example "?mediaType=user&level=ninja")	N
maxPoints	Integer.	Used with the "mediaType=user" argument, filters for members who have accumulated no more than the number of points specified. (For example "?mediaType=user&minPoints=100&maxPoints=200" will return all members who have between 100 and 200 points)	N
minPoints	Integer.	Used with the "mediaType=user" argument, filters for members who have accumulated at least the number of points specified. (For example "?mediaType=user&minPoints=100&maxPoints=200" will return all members who have between 100 and 200 points)	N
mediaDesc	String. One or more comma-separated search terms.	Filters for media with the search term(s) within the description.	N
mediaId	String. One or more comma-separated search terms.	Filters for media the specific ID(s) listed. Must be used with a mediaType argument.	N
mediaTitle	String. One or more comma-separated search terms.	Filters for media with the search term(s) within the title.	N
mediaType	String. One or more comma-separated values from this list: video, audio, photo, blog, mb, tags, user, group, externalmedia.	Filters for specific media and member types.	N
memberHasProfilePhoto	String. Only possible value is on.	Filters to only include members who have uploaded a profile photo.	N
members	String. One or more comma-separated member usernames.	Filters profiles and media from the members listed. If used with groups, filters for groups that the stated member has joined.	N
p	Integer.	Specifies the page to be returned, if feed results are paginated (use with quantity and totalItems).	N
quantity	Integer. Max value is 1000.	Quantity items in a feed; if results are paginated (with the p and totalItems arguments), this value determines the number of listings per page. If undeclared, the feed will default to 25 results.	N
query	String. One or more comma-separated text strings.	Like the keywords parameter, query searches media, blog posts, members, groups, and message board post titles, descriptions, categories, tags, admin tags, and other metadata. By default, it performs an exact match search (if you include query=app in your RSS feed, the results would include a photo titled "app," but not one titled "apps" or "kickapp").	N
sortType	String. One value from this list: recent, popular, favorite, rating, commented, relevant, points.	Defines how the results are sorted.	N
state	String. A US or Canadian state abbreviation (single value).	Filters for the given state or province.	N
tags	String. One or more comma-separated tags.	Filters for all items with matching tags.	N
toDate	String. {MM-dd-yyyy} format.	Filters for results that were created before this date.	N
totalItems	Integer.	Total number of results for all pages in paginated results (use with quantity and p).	N
zipPostalCode	String. A single ZIP/postal code.	Filters for the given ZIP/postal code value.	N

This category currently contains no pages or media.

This page was last modified on 26 June 2009, at 16:58. - This page has been accessed 488 times. -

About KickApps API Reference