Knowledgebase
What is SportsCaster API?
Posted by Casey Trauer on 28 May 2013 07:43 PM

The SportsCaster API makes it easier to query for sports content. You can use a standard URL to do the following typical tasks:

  • Find a document (or set of documents) that match certain criteria. For example, find all MLB box scores published in the past five minutes. Or find all Boston Red Sox box scores for the past week. There are lots of permutations.
  • Retrieve a specific SportsML source file.
  • Retrieve a specific SportsML source file and run it through a xslt transform to format the information in a different way (HTML, JSON, a different XML format, etc.)
  • Return a list of events for a given league for a specified period of time.
  • Return a list of events, plus their current status/score and all the latest documents that relate to that event. (e.g. scoreboard functionality)
  • Return a variety of information for one event.

The Sportscaster web service communicates to a database called SportsDB that gets populated by our FeedFetcherDeluxe (FFD) software. Every time FFD pulls down a file, it stores it in a local folder and updates the database with certain information about the file. Sportscaster makes it easy to query for those documents based on several criteria: time published, league, document type, teams, etc.

All these functions can be done by querying the SportsDB database directly, but the SportsCaster API provides you the shortcuts to quickly integrate this into your application over HTTP.

How can I use SportsCaster?

If you purchase the FeedFetcherDeluxe software, the SportsCaster API can be optionally downloaded at no extra cost. 

We also have a hosted SportsCaster Web Service where we maintain the FeedFetcherDeluxe/SportsDB architecture and clients can make queries against our database. (Please see our documentation on querying best practices!) The SportsCaster Web Service mode allows clients to have the full formatting flexibility of our delivered feed, without having to retrieve, process, and database thousands of files a day. We reserve the right to limit what kinds of clients may use the hosted SportsCaster based on scope of content or how many queries you might make.

What is required?

SportsCaster is a php application using the CodeIgniter PHP framework. It is open source and you may make changes/additions at your discretion. Sportscaster requires PHP 5.2 or better to run as configured. It may run properly on versions of PHP older than that but might require modifications that may not be supported by XML Team Solutions.

What are some query examples?

Let's take a look at some standard queries. Each of these queries show a typical use case for each of the API methods available (searchDocuments, getDocuments, searchEvents, getEvents):

Find all NHL boxscores published in the past 24 hours:

http://{domain.com}/gateway/php_ci/searchDocuments.php?league-keys=l.nhl.com&fixture-keys=event-stats&date-window=2400&revision-control=latest-only&publisher-keys=sportsnetwork.com&max-result-count=5&content-returned=metadata-only&content-format=sportsml&rendering-engine=xslt&gateway-theme=default&query-debug=false&stylesheet=sportsml2html-listing

[domain.com] would refer to either to the domain hosting the webservice, or if it is the hosted Sportscaster: sportscaster.xmlteam.com. Hosted clients will have a different URL: http://{domain.com}/unlimited/{username}/{API_method} ...

Let's break down the parameters to further explain how this works:

  • league-keys: This is how we identify a league in our metadata.
  • fixture-keys: This is how we identify each file type from the publisher. The fixture key for box scores is: event-stats. For a list of all fixture keys, look in our document inventory at http://showcase.xmlteam.com.
  • date-window: This tells us what publishing window we want to search in. 2400 is the last day. 0015 would be previous 15 minutes. There are other types of time parameters, but this is the most useful.
  • revision-control: "all" gets you all revisions, "latest-only" will get only the last version of each file.
  • publisher-keys: XML Team distributes data for a number of publishers. Our hosted webservice only supports The Sports Network (key: sportsnetwork.com) at the moment. 
  • max-result-count: The total number of files you want returned.
  • content-returned: "metadata-only" returns only basic information about the document. "all-content" will return the whole file for each document. 
  • stylesheet: The query result for a document listing can be displayed several ways: "none" will give you SportsML, "sportsml2html-listing" is a stylesheet for listing the result in HTML, "sportsml2rss-1.0" will return it in an RSS format. You can write your own stylesheet to control this.

Get me a specific document by document id:

 http://{domain.com}/gateway/php_ci/getDocuments.php?doc-ids=xt.R32885-box

Get me a list of events for yesterday (or tonight, whatever!) and their related documents:

 http://{domain.com}/gateway/php_ci/searchEvents.php?league-keys=l.nhl.com&date-offset=-1&date-offset-span=1&date-offset-midnight=1600&sort-order=asc&publisher-keys=sportsnetwork.com&max-result-count=200&content-returned=metadata-and-scores&content-format=sportsml&rendering-engine=xslt

You can actually build a scoreboard based on the data returned here. 

Get me information and related documents about a given event key:

 http://{domain.com}/gateway/php_ci/getEvents.php?event-keys=l.nhl.com-2011-e.14509&publisher-keys=sportsnetwork.com&content-returned=metadata-and-scores&content-format=sportsml&rendering-engine=xslt&gateway-theme=default&query-debug=false

This is basically the same as the one above it but narrowing down to one specific event. You can have several events separated by commas.

 

These methods are explained in more detail in the rest of our SportsCaster documentation.

(1 vote(s))
This article was helpful
This article was not helpful

Comments (0)
Post a new comment
 
 
Full Name:
Email:
Comments:
Help Desk Software by Kayako Resolve