Tools for web site administrators

Folkjam.org provides a handful of useful tools to web admins who maintain folk music web sites.

If you want to direct your users to folkjam.org, we provide folkjam logos in varying sizes on our linking guidelines page.

We provide access to our database of jams through RSS, which is an internet standard for delivering feeds from web sites. What sort of feeds? Well, that depends on the web site. A news site is likely to provide a list of current news headlines. A jam site provides lists of jams. You can read more about what RSS feeds are available from our site on our jam feeds page.

What can you do with an RSS feed? A whole bunch. Modern web browsers allow users to create dynamic bookmarks based on RSS feeds. These bookmark lists show the current subjects from a site's RSS feed. Or, an RSS client can be installed on your computer that will notify you when there are new subjects on a site's RSS feed. And, most critically for you as a web site administrator, you can pull content from an RSS feed and place it in your web pages.

Do you currently hand-maintain HTML pages with lists of jams sponsored by your organization? With a combination of RSS and a little JavaScript you can display a list of upcoming jams in your city that always remains current, just like our 'upcoming jams' display on the front page. You don't need to know JavaScript either - you simply need to be comfortable with editing HTML files.

Go to this page, type in the full URL of the folkjam.org RSS feed you want to incorporate into your site and then select Generate JavaScript. Take the script this tool generates and place it in an appropriate location on your HTML based web site. From now on your users will see an updated display of the jams you choose to show them on folkjam.org.

We encourage you to maintain all of your organization's jams on folkjam.org. Your users will always see current information on local jams, and more people will be able to find your jam sessions through folkjam.org.

Linking to folkjam

We appreciate it when other sites link to folkjam.org. It provides your users with an additional resource, and it provides more visibility to us.

Here are several folkjam.org logos in varying sizes, and a few requests in how to use them.

  • We ask that you always show a link to our home page, folkjam.org, even if you are also linking deeper into the site. Our home page presents visitors with a concise display of jams in their area, and we would like to give all users the opportunity to start with this view. For example, you could write Check out the map of jams and festivals in the US over at folkjam.org.
  • Pick one of our logos, place it on your site and link it to our home page, www.folkjam.org.
  • You can force people who follow your link to default to a specific city with the following syntax: http://www.folkjam.org?start=city,ST. For example, to create a link that shows all jam sessions in the greater St. Louis area you would use http://www.folkjam.org?start=St.%20Louis,MO. The %20 is what you use to represent a space.

Our full size logo, 500x100


<a href="http://www.folkjam.org"><img src="http://www.folkjam.org/logo/folkjam-linklogo-s100.png" border="0"></a>

One of our alternate banners, 168x60


<a href="http://www.folkjam.org"><img src="http://www.folkjam.org/logo/folkjam-play-well-168x60.png" border="0"></a>

A medium sized version of our logo, 300x60


<a href="http://www.folkjam.org"><img src="http://www.folkjam.org/logo/folkjam-linklogo-s60.png" border="0"></a>

The smallest our logo will go and remain legible, 225x45


<a href="http://www.folkjam.org"><img src="http://www.folkjam.org/logo/folkjam-linklogo-s45.png" border="0"></a>

A medium sized badge version of our logo, 150x40


<a href="http://www.folkjam.org"><img src="http://www.folkjam.org/logo/folkjam-badge-medium.png" border="0"></a>

A small folkjam.org badge, 80x15


<a href="http://www.folkjam.org"><img src="http://www.folkjam.org/logo/folkjam-badge.png" border="0"></a>

RSS feeds from folkjam.org

We provide several different ways to pull content from folkjam.org via RSS. You may use our RSS feeds to show local jams on your web site, display a list of upcoming jams as a bookmark in your browser or anywhere an RSS feed can be used. We do ask that you leave all attribution as is in the RSS feed.

Feed basics

Folkjam.org shows you content based on your location, and our RSS feeds are built on the same principle. We supply five different types of RSS inquiry: jams based on zip code proximity, jams based on latitude/longitude proximity, jams contributed by a particular user, a group of specific jams, and jams that you have placed on your personal jam calendar (NOTE: The personal calendar feed type is not likely to be in the early versions of folkjam.org).

Postal (zip) code proximity feeds

http://www.folkjam.org/feed/jam/postcode/CC/PPPPP
This feed brings back a list of jams and/or festivals within a radius of a postal code. The CC portion of the URL is the two letter country code, and the PPPPP portion is the post/zip code. For example, a list of jam sessions near New York City could be retrieved with the RSS feed http://www.folkjam.org/feed/jam/postcode/us/10005.

The postal code feed can be customized with the distance, sort, count and type parameters described below.

Geographic lat/lon proximity feeds

http://www.folkjam.org/feed/jam/geo/LAT/LON
This RSS feed returns a list of jams and/or festivals within a radius of the latitude and longitude you supply. The LAT portion of the URL is the latitude and the LON portion is the longitude. For example, a list of jam sessions near Kansas City could be retrieved with the RSS feed http://www.folkjam.org/feed/jam/geo/38.96/-94.74.

The geo feed can be customized with the distance, sort, count and type parameters described below.

Jams contributed by a specific user

http://www.folkjam.org/feed/jam/contributor/UUU
The contributor feed returns a list of all folkjam events submitted by a specific user. This is useful if you only want to show 'your' jams/festivals on web pages you maintain instead of all of the events near you. If you run a jam session in your area, post it to folkjam.org and use our RSS feed to keep the 'next session' date of your jam current without having to edit your HTML pages after every jam.

The UUU portion of the URL is a numeric folkjam user ID. This is the ID of the user who contributed the jams you want to see.

A group of specific jams

http://www.folkjam.org/feed/jam/node/NNN
http://www.folkjam.org/feed/jam/node/NNN+NNN+NNN
The specific jam feed allows you to specify one or more jams to retrieve as an RSS feed. The jams are identified by the same number you see in the URL when viewing the jam session. If the jam you want to pull into an RSS feed is on URL http://www.folkjam.org/node/864, then you can pull an RSS feed of upcoming dates for that jam using http://www.folkjam.org/feed/jam/node/864. If you want to bring back multiple specific jams combined into a single RSS feed, then use the second form of the RSS feed URL where the jam session id numbers are separated by a plus sign(+). For example, http://www.folkjam.org/feed/jam/node/864+1961+1972+2078.

The 'distance' parameter is not valid for this feed type. 'sort', 'count' and 'type' are valid. This feed takes an additional parameter - 'title'. Use the title parameter to set the title that is presented on the RSS feed. For example, http://www.folkjam.org/feed/jam/node/1234+1235?title=My+two+favorite+jam+sessions.

Jams from your personal jam calendar

http://www.folkjam.org/feed/jam/personalcalendar/UUU
NOTE: This feature will not be part of the initial release of folkjam.org and is planned for early 2007.

Feed parameters

All of our RSS feeds can take additional parameters to fine tune the data you receive from folkjam.org. These parameters are appended to the URL you construct with a ? followed by the parameter name, an equals sign, the parameter value and optionally an & followed by another parameter name. Confused? See the examples.

distance=##
Constrain the distance of the events presented in the RSS feed. Defaults to 90 miles. ## must be a numeric value, in miles. The distance cannot exceed a 200 mile radius.
sort=[title|upcoming]
Determines the sort order for the events presented in the RSS feed. A value of 'title' will return a list of events in alphabetic order (up to the 'count' parameter). A value of 'upcoming' will return a list of events in chronological order. The main difference is that the 'title' feed will show one entry for every jam on the feed with the date of the next session, where the 'upcoming' list will show jams in the order they happen, and any given jam may be in the list multiple times.
count=##
Constrains the number of items that will be returned in the RSS feed. Defaults to 10. Has a maximum of 75.
type=[festival|jam|camp]
Event types to return in the RSS feed. This is a comma separated list of the event types that will be delivered in the RSS feed. If no type parameter is supplied it defaults to 'jam' and does not return information on festivals.

We offer a JavaScript RSS utility for embedding RSS in your HTML pages. For an example of an RSS feed embedded in an HTML web page, view Scott's Kansas City Area Jam Sessions page.

Example RSS Feeds

Folkjam.org provides several different ways to extract jam sessions and festivals through RSS. The rules for building up a valid folkjam.org RSS feed URL can be found here.

This is a list of examples on how to format our RSS feed URLs.

Description RSS Feed URL
Jams nearAshburn, VA, your current location. http://www.folkjam.org/feed/jam/postcode/us/
A list of upcoming jams near Tampa, Florida http://www.folkjam.org/feed/jam/postcode/us/33601
Jams near lat/lon 27.95/-82.46 (which also happens to be Tampa, FL) http://www.folkjam.org/feed/jam/geo/27.95/-82.46
Alphabetic list of jams within a 40 mile radius of St. Louis, MO http://www.folkjam.org/feed/jam/postcode/us/63119?sort=title&distance=40
List of upcoming festivals in a 20 mile radius of Winfield, Kansas http://www.folkjam.org/feed/jam/postcode/us/67156?type=festival&distance=20&sort=upcoming
List of festivals and jams in a 35 mile radius of Winfield, Kansas listed by title http://www.folkjam.org/feed/jam/postcode/us/67156?type=festival,jam&distance=35&sort=title
A feed showing only the weekly sessions of a bluegrass jam in Woodstock, New York with a custom title http://www.folkjam.org/feed/jam/node/2081?title=Pizza+and+bluegrass+together+again
The next six upcoming sessions of the Hudson Valley Bluegrass Association jams and the weekly Woodstock bluegrass jam http://www.folkjam.org/feed/jam/node/2081+2078?count=6