SODA is built atop open standards and open protocols. Its technical objective is to make our content as easy as possible to integrate into websites, applications, databases and editorial systems:
- Your software calls XML Team's web server periodically asking for document listings that match your search criteria. (Or you may choose to search and download the files manually using our one of our web tools.)
- XML Team sends back a free listing of relevant documents, including metadata and document URLs.
- Your software then requests and downloads the file(s) using the URLs in the listing, and your account is billed. After that, you are free to parse, transform, load, query, format, and/or display that content however you'd like (within the Fair Publishing Rights terms laid out in our License Agreement).
Photos, it should be noted, are currently only available via a manual downloading process. Clients interested in a hands-free photo feed should contact API Sportswire sales.
Our platform supports multiple formats for the free listings and for the documents themselves. The most common combination is RSS for listings, and SportsML for documents.
RSS, commonly known as "Rich Site Syndication" or "Really Simple Syndication," is employed by millions of users worldwide. It comes in many flavors, several of which we support. We recommend RSS 1.0. If you're new to RSS, then here are some technical resources:
|Mark Pilgrim's RSS Tutorial||RSS 1.0 Specification|
|Mark Nottingham's RSS Tutorial||RSS 2.0 Specification|
|O'Reilly RSS DevCenter||RSS 0.92 Specification|
SportsML is the open XML vocabulary for sports data, and is the only international standard designed for scores, standings, schedules, and statistics designed to accommodate every sport, country and language. For more information on SportsML, visit our Why XML? page or SportsML.org.
|Formats We Support|
|For Listings||For Data|
and permeated with
How to Request Listings
Listings are requested by making a standard, authenticated http request. You can manually request listings by just typing the appropriate URL into a web browser. Use our Query Builder tool to determine the parameters within the URL, or read our API Specification for details. Broken down and documented for clarity, one sample URL for Listings might look like this:
league-keys = l.nhl.com &
fixture-keys = event-stats &
max-result-count = 10 &
date-window = 24:00 &
stylesheet = sportsml-set2rss-1.0
SODA uses standard http authentication. When using a web browser to display Listings,
this means that a small popup window appears asking for your username and password.
Login information can also be included in the URL itself, as in:
Please note that Microsoft's Internet Explorer has dropped support for this type of URL. Microsoft cites security issues, and current updates of Internet Explorer no longer support adding the "username:password@" string to the start of a URL. See Microsoft's support page on this issue for more details.
How to Request Documents
Depending upon which format you've chosen for the Listings, you'll be able to determine what URL to use to retrieve the actual documents themselves.
If you've selected RSS, then the final-form URLs for the various documents are included in the <link> elements. Broken down and documented for clarity, one sample URL for Document might look like this:
Other parts of the RSS Listing give you the title of the document, its publication date, and other useful pieces of metadata.
Like with the Listings URL, document retrieval uses standard http authentication.
Key Practices When Automating Listing Requests and Doc Retrieval
XML Team currently does not provide software for querying the webservice, but the mechanics are not difficult for an experienced programmer. Here are some key requirements for any such software:
- You should be able to regularly schedule queries. You may query our database as many times as you like, within reason. Your queries should not overlap or duplicate each other. Each listing returns a unique, new set of documents. As a general rule, you should not query consistently for more than a day's worth of data.
- You should keep track of the document IDs that have already been downloaded. This is so that you don't download them again if they appear in a query listing — you will be charged twice. It's also so that you can match all downloaded doc-ids with the revision ID; a revision ID indicates the file may be an update of a previous file and may be downloaded for free. (If the doc-id and revision-id of the file in the listing match, then it is not an update.)
- You should be able to store each document locally.