Introducing EspnRb
For those who found this via Reddit here is a link to the repository.
EspnRb ('ESPN-ar-bee')
Since its release I've been working on creating a Ruby wrapper for the ESPN api. I began because it sounded fun to fiddle around with sports data for a change. And.. It was, I've had a blast building EspnRb. EspnRb allows you to use the Espn API with all that Ruby goodness we all know and love. Here I'll very briefly walk you through installation and getting the espn credentials, then we'll dive straight into some EspnRb examples.
ESPN api
In order to use the espn api you must have an api key. Your api key can be requested at the ESPN developer center website [1]. Just fill out the form and they'll assign you a key. Important note: the use of ESPN's api requires an attribution link (like above) which can be found here. The attribution links look pretty good and range from 50 by 14px to 200 by 75px, so finding one that fits your use shouldn't be too hard. Once you have the key you can begin working with EspnRb.
Installation
# On the command line.
# ~$ gem install espn_rb
# Or in a Gemfile
gem "espn_rb", "~> 0.0.4"
# ~$ bundle
# That's it.
Use it
The easiest way to set your api key for use with espn_rb is to export it as an environment variable. Do that like so:
# If you want to pass it in to your objects you may do so explicitly like so:
# espn = EspnRb.headlines(:api_key => YOUR_SUPER_SECRET_API_KEY)
$ export espn_api_key=YOUR_SUPER_SECRET_API_KEY
Get the headlines
require 'espn_rb'
espn = Espn.headlines
# Each sport available via the API can be called on the Espn.headlines
# [ :all, :golf, :boxing, :mma, :racing, :soccer, :tennis, :mlb
# :nba, :nfl, :nhl, :nascar, :wnba, :ncaa_basketball, :ncaa_football
# :ncaa_womens_basketball]
espn.all #=> HeadlineResponse
espn.nba(:news) #=> HeadlineResponse
espn.nfl(:top) #=> HeadlineResponse
espn.ncaa_football({:for_date => "2012-03-09"}) #=> HeadlineResponse # Will include all stories for that date
espn.nba({:for_athlete => "1234" #=> HeadlineResponse # Will include all stories for that athleteId
espn.all.response
#=> ESPN's response string as JSON
HeadlineResponse
# HeadlineResponse includes Enum so you can do things like this:
espn.all.map(&:title)
#=> ["Celtics-Clippers Preview",
# "Warriors 97, Clippers 93",
# "Hawks 106, Kings 99",
# "Warriors-Clippers, Box",
# "Warriors 97, Clippers 93",
# "Hawks 106, Kings 99",
# "Bucks-Nets Preview",
# "Hawks-Kings, Box",
# "Grizzlies 94, Nuggets 91",
# "Grizzlies-Nuggets, Box"]
# Some methods like titles, descriptions etc are available directly.
espn.all.titles
#=> Same as above.
HeadlineItem
The HeadlineResponse Object holds in it the contens of the ESPN JSON response split into HeadlineItems. Here is where you can get Specific information about each story. Some of the options are:
espn = EspnRb.headlines
headline_response = espn.nba[2] #=> HeadlineItem
headline_response.web_url #=> "http://sports.espn.go.com/espn/wire?section=nba&id=7664408&ex_cid=espnapi_public"
headline_response.id #=> 7664408
headline_response.title #=> "Mavericks-Kings Preview"
headline_response.athletes #=> ["Johnny B", "Freddie Flintstone", "Etc"]
headline_response.leagues #=> ["46"]
headline_response.athlete_ids #=> ["123", "132", "123"]
# More to come in future versions.
headline_response.headline #=> JSON hash from original response.
There is a lot more inside the gem, be sure to check out the source. ^_^
Documentation
So far I've built up a decent little readme [2] and there are YARD docs [3]. I'm also available if you need any help just ping me on github.
Conclusions
An example of espn_rb can be found here. It was created by Brian Jackson, a developer at ESPN.com (@jaxzin), and he plans to expand the examples over the next little while, so be sure to check back.
This is just a start. I hope to expand this gem to encompass more and more of the ESPN functionality. The folks at ESPN have done a good job of making their data available. I've had a lot of fun working on this project so far, and I hope you guys find some use for it. ^_^
References
1.Register for ESPN api key
2.Main EspnRb Repository
3.Yard for EspnRb
