The Sports On Demand API (SODA) service has two kinds of content queries for xml documents:
- getScoreboard: The Scoreboard query allows you to query for game time and score information for all events on a given date. You will also be able to see the latest documents associated with that event for fixtures such as boxscores, recaps and previews (these are documents that you will find in the Sample Showcase).
- getListings: Unlike the Scoreboard query, the next two query types concern retrieving individual documents. The SODA system offers you access to a broad library of documents, including single-game scores, stats, rosters, standings and schedules for dozens of professional and collegiate leagues.
The getListings query will return a list of documents that match the criteria of your search. All getListings queries are free.
- getDocuments: When you have returned a document ID from a getListings or getScoreboard query, you can make a secondary query to retrieve the document. Check out our Sample Showcase for a list of what documents are available for SODA clients, as well as the price per document and details about each document.
This article will focus on how to query for listings and documents.
The query parameters for listings
All SODA queries have the same base URL: http://soda.xmlteam.com/api/
The next URL segment concerns what type of query:
The first query is necessary to retrieve a document id that allows you to execute the second.
Next come the parameters for your query (* required).
- * league-keys: This is a key, such as l.mlb.com, that represents a league. You can use the query builder interface to find the correct value for the league you are looking for. The most commonly used keys are: l.mlb.com, l.nfl.com, l.nba.com, l.nhl.com, l.ncaa.org.mbasket, l.ncaa.org.mfoot. You can have multiple league keys separated by a comma.
- * fixture-keys: A fixture is a document type, such as box score, recap, roster, etc. Check out our Sample Showcase for a list of what fixtures are available for SODA clients and the fixture-key values. You can have several fixture keys separated by commas.
- max-result-count: The maximum number of events you want to return.
- * date-window: A time value expressed as HHMM. All documents published HHMM ago that match the query criteria will be returned. Any query must either use date-window or earliest-date-time/latest-date-time.
- * earliest-date-time/latest-date-time: A value expressed as yyyymmddThhmmss-zzzz (where zzzz is the time zone offset) that represents the beginning and end of a period of your search. Any query must either use date-window or earliest-date-time/latest-date-time. If you query our system regularly, please query for narrow time periods, as it requires fewer resources. Any regular query that regularly asks for a months worth of data, for example, could tie up system resources.
- * revision-control: A value of "all" will return all documents. A value of "latest-only" will return only the latest version of a document for a unique event or team. For example, only the latest score document for a game. Or only the latest roster for a team.
- priorities: A value of "high" will return news documents that are tagged as high priority. Omitting the parameter will return all news stories.
- * publisher-keys: At the moment, the only valid value is sportsnetwork.com, representing data published by The Sports Network.
- stylesheet: If this parameter is not given, an xml listing will be returned. This is recommended. One option is for an HTML output, for which you would have the value of sportsml2html-listing-fod. There are also RSS formats.
Retrieving the documents
Once a doc-id is obtained from a listing query, it can be plugged into a getDocuments query:
Multiple doc-ids can added when separated by commas.
The xml output
Although there are several listing formats, we'll focus here on the SportsML/xml output, which requires no parameter.
The first set of parent nodes in the result set focus on metadata for the query: the query string, query time, number of matches returned, etc. The core content starts with the sports-content nodes, one for each document returned. Here is a sample, for an NBA boxscore:
<sports-metadata doc-id="xt.18428126-box" date-time="20130522T002800-0400"language="en-US" document-class="event-summary" fixture-key="event-stats" revision-id="l.nba.com-2012-e.18305-event-stats-sportsnetwork.com">
Boxscore: San Antonio vs. Memphis
<sports-content-code code-type="publisher" code-key="sportsnetwork.com"/>
<sports-content-code code-type="priority" code-key="normal"/>
<sports-content-code code-type="sport" code-key="15008000"/>
<sports-content-code code-type="league" code-key="l.nba.com"/>
<sports-content-code code-type="conference" code-key="c.western"/>
<sports-content-code code-type="team" code-key="l.nba.com-t.21" code-name="San Antonio Spurs"/>
<sports-content-code code-type="team" code-key="l.nba.com-t.19" code-name="Memphis Grizzlies"/>
Here are the key elements and the datapoints they will contain:
- sports-metadata: the doc-id, date-time (publish date), fixture-key, revision-id (see note below)
- sports-title: a title or general description of the document
- sports-content-codes: key metadata about the document, including what teams may be involved
Any software that is set up to retrieve documents probably pay special attention to two particular data points: the doc-id is obviously a key to retrieve the actual document, but since you will be charged for retrieving a document id multiple times, your system may want to have a log of which doc-ids have been retrieved so that it skips retrieving it a second time.
The revision-id is a code that will encompass all documents for, say, a given event or updates to a news story. it can be used to track updates to documents. When you have bought a score update for a game, you will not be charged for subsequent score updates. The revision id contains the event-key that will identify all score updates a part of the package. These event keys can be identified ahead of time from the schedules.
What does it cost?
The cost of a fixture can be viewed either in the Sample Showcase (click on the Details link for a fixture) or in the query builder interface. Listing queries are free.