How to query for SODA scoreboards
Posted by Casey Trauer on 22 May 2013 08:44 PM

The Sports On Demand API (SODA) service has two kinds of content queries:

  • 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 scoreboards.

The query parameters

All SODA queries have the same base URL:

The next URL segment concerns what type of query:

Next come the parameters for your query (* required). 

  • * league-keys: This is a key, such as, 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:,,,,, You can have multiple league keys separated by a comma.
  • max-result-count: The maximum number of events you want to return.
  • * date-offset:  Return one day of events. A value of 0 is today. A value of -1 is yesterday. A value of 1 is tomorrow. Etc. Any query must either use date-offset or start-date-time.
  • * date-offset-midnight: A value expressed as HHMM in GMT time that determines when the query determines whether to return yesterday's events or today's events. In other words, if you are making a query at 2 a.m. ET, you will likely still want events that started on the day before. A value of 1600 would make the "new day" start for query purposes in the late morning for U.S. eastern time. Any query using date-offset must use date-offset-midnight.
  • * start-date-time: A value expressed as yyyymmddThhmmss-zzzz (where zzzz is the time zone offset) that represents the beginning of a 24-hour period for which you want scoreboard results. Any query must either use date-offset or start-date-time.
  • * publisher-keys: At the moment, the only valid value is, 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-scoreboard.

The xml output

The first set of parent nodes in the result set focus on metadata for the query: the query string, query time, number of events returned, etc. The core content starts with the sports-event nodes, one for each event returned. Each sport has the same structure but may have slightly different content. Here is a partial sample for an MLB sports-event:

<event-metadata date-coverage-type="event-play" event-key=""" event-status="post-event" start-date-time="20130411T221000-0400" xts:game-of-day="1" xmlns:fs="" xmlns:xte="">
<event-metadata-baseball inning-value="9" inning-half="bottom"/>

<sports-property formal-name="event-score" value="xt.18168131-update-post-event"/>
<sports-property formal-name="event-stats" value="xt.18168161-box"/>
<sports-property formal-name="matchup" value="xt.18163422-matchup-tex-sea"/>
<sports-property formal-name="post-event-coverage" value="xt.18168302-recap"/>
<sports-property formal-name="pre-event-coverage" value="xt.18163098-preview"/>
<team-metadata team-key="" alignment="away" xmlns:fs="">
<name first="Texas" last="Rangers"/>
<team-stats event-outcome="win" score="4">
<sub-score period-value="1" score="0" xts:total-score="0"/>
<sub-score period-value="2" score="2" xts:total-score="2"/>
<sub-score period-value="3" score="0" xts:total-score="2"/>
<sub-score period-value="4" score="0" xts:total-score="2"/>
<sub-score period-value="5" score="2" xts:total-score="4"/>
<sub-score period-value="6" score="0" xts:total-score="4"/>
<sub-score period-value="7" score="0" xts:total-score="4"/>
<sub-score period-value="8" score="0" xts:total-score="4"/>
<sub-score period-value="9" score="0" xts:total-score="4"/>
<team-metadata team-key="" alignment="home" xmlns:fs="">
<name first="Seattle" last="Mariners"/>
<team-stats event-outcome="loss" score="3">
<sub-score period-value="1" score="1" xts:total-score="1"/>
<sub-score period-value="2" score="1" xts:total-score="2"/>
<sub-score period-value="3" score="0" xts:total-score="2"/>
<sub-score period-value="4" score="0" xts:total-score="2"/>
<sub-score period-value="5" score="0" xts:total-score="2"/>
<sub-score period-value="6" score="0" xts:total-score="2"/>
<sub-score period-value="7" score="0" xts:total-score="2"/>
<sub-score period-value="8" score="1" xts:total-score="3"/>
<sub-score period-value="9" score="0" xts:total-score="3"/>

Here are the key elements and the datapoints they will contain:

  • event-metadata: the event-key, event start time, event status
  • sports-property: a list of related documents, the IDs for which can be used in a getDocuments query.
  • team-metadata: team key, team name, home/away alignment
  • team-stats: score, outcome
  • sub-score: linescore with period values and period scores

This are generally the common elements between all league outputs.

What does it cost?

Every time you query a scoreboard, you will be charged credits.

League Credits
MLB ( 1
NFL ( 10
NBA ( 2
NHL ( 2
College football (* 10
College basketball (* 10









* Conference scoreboards

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

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