Client Access

XML feeds are accessed using an HTTP pull method. The feeds can be accessed in two ways:

1. Reload the feed files over HTTP periodically.
2. Use our Atom feeder to know which feeds have updated and then download the updated files.

Access Controls and Throttling

Access to the feeds is restricted by customer and the type of contract they have with Sports Direct.  We identify customers either by the IP-address of the computer making the request or an API key parameter (apiKey) supplied in the request URL itself.  If a customer is to be identified by IP, they must supply us with a set of addresses for the network they will be making requests from.  Usually, the preferred method is by API key which is a unique hexadecimal string that is automatically generated for each customer when their account is created in our system.  Customers should receive their API Key in an initial email from our sales department and can then be appended to each request URL.  The apiKey parameter can be used in direct XML feed requests as well as Atom requests, for example:

http://xml.sportsdirectinc.com/Atom?feed=/football/nfl/boxscores/2014-2015/
http://xml.sportsdirectinc.com/Atom?feed=/football/nfl/boxscores/2014-2015/&apiKey=<customer-API-Key>

http://xml.sportsdirectinc.com/sport/v2/football/NFL/boxscores/2014-2015/boxscore_NFL_42137.xml
http://xml.sportsdirectinc.com/sport/v2/football/NFL/boxscores/2014-2015/boxscore_NFL_42137.xml?apiKey=<customer-API-Key>

We use throttling to control the frequency of access to various feeds. The purpose of throttling is to keep the service running and available for all the customers even when there is customer software that behaves badly due to a programming error or any other cause. The throttling limits are set so that any unreasonable frequency of access is limited. While the limits are rather generously set, we recommend that our customers use good judgment when accessing the feeds and study the feed documentation for suitable access frequency. For testing purposes, we recommend that you download the feeds to your local server and test against local data when possible.

The access frequency is configured on per customer and feed basis so that if any limit is exceeded only that particular feed will experience limited access for the customer in question.

When accessing the feeds, you may encounter the following HTTP return codes in various situations:

• 401 - Unauthorized access. You will receive this error code if we can not authenticate you. The content of the response will detail the cause.
• 403 - Forbidden. You will receive this error code if you do not have authorization to access to a feed.
• 429 - Too many requests. You will receive this error code when you have exceeded the hit limit for a feed. The content of the response will contain more details.

Atom Syndication

We use Atom Syndication to notify our clients about resource updates on our servers. Clients can poll the syndication feed periodically for updates, and once updates are available, the client can request the files from our servers. This is a much superior approach to repeatedly requesting the same files behind known URLs. There are also cases where the resource URLs are not easily otherwise known to clients when new resources are constantly being created. We recommend that our clients use the Atom feeder almost exclusively to be notified about updates on our servers.

The Atom service is available at:

http://xml.sportsdirectinc.com/Atom

Atom Service Parameters

The Atom service accepts the following parameters, which must be specified in the query string of the URL request:

feed

feed parameters are case-sensitive!

The feed parameter specifies which types of feeds should be returned. If not specified, no filtering based on feed type is done. An invalid feed parameter will result in a response with an error message and an HTTP status code of 400.

The following feed keywords are allowed:

The feed parameter must conform to the following pattern:

/feed-keyword+

For example,

/baseball
/boxscores
/basketball/players
/hockey/nhl/schedules
/football/nfl

When specifying the feed parameter, feed keywords should be specified in the order of least specific to most specific:

/boxscores
/baseball/players
/basketball/nba/injuries
/hockey/nhl/boxscores

When specifying a season keyword in the feed parameter, the season should be the last keyword:

/boxscores/2006
/baseball/player-stats/2007

Not all feeds exist on a per-season basis; for example, schedules, injuries, livescores and odds feeds exist only for the current season. If a season keyword is specified in the feed parameter, none of these feeds will be returned.

newerThan

The newerThan parameter specifies that only feeds that have been updated after a specific date/time should be returned. If not specified, no filtering based on last update date is done. Note that dates are converted to our local time when parsed, so timezones are optional. An invalid feed parameter will result in a response with an error message and an HTTP status code of 400.

Please note that the newerThan parameter actually does a >= comparison when finding new feeds; this is because originally the most specific unit of measurement in a timestamp was a second, and feeds could potentially update at any time within a second. This has since been updated to include additional precision (4 places after the second) but it was decided that the parameter would remain inclusive allowing customers to remain unaffected.

The newerThan parameter must conform to the following pattern:

yyyy-MM-dd'T'HH:mm:ss.ffff

yyyy-MM-dd'T'HH:mm:ss.ffffzzz

For example,

2007-06-29T14:31:41.1384
2007-06-29T14:31:41.1384-3:00

newerThan best practices

We recommend using the value of the previous Atom response's <feed>/<updated> element as the value of the newerThan parameter for your next request.

For example, if you make the following request:

http://xml.sportsdirectinc.com/Atom?feed=/mlb/livescores&newerThan=2013-01-29T12:03:02.6567-04:00

The response will contain an <updated> element:

<feed xmlns="http://www.w3.org/2005/Atom">
    <title>Feed Index</title>
    <link href="http://xml.sportsdirectinc.com/Atom?feed=/baseball&amp;newerThan=2013-01-29T12:03:02.6567-04:00"/>
    <updated>2013-01-29T12:04:02.8112-04:00</updated>
    ...
</feed>

Your next Atom request should look like this:

http://xml.sportsdirectinc.com/Atom?feed=/mlb/livescores&newerThan=2013-01-29T12:04:02.8112-04:00

Repeat this for each Atom response and next request.  

This should guarantee that you will never miss an updated feed.  However, as mentioned above, the newerThan parameter actually does a >= time comparison for updated feeds, so you will potentially end up getting the last updated feed again in your next request.  You can prevent this by adding a millisecond to the timestamp before using it in your next Atom request, but that will introduce a the potential to miss a feed if it updates < 1ms since your last Atom request.

maxCount

The maxCount parameter specifies the maximum number of feeds to be returned. If not specified, the default value of 5000 is used. An invalid parameter will result in a response with an error message and an HTTP status code of 400.

The maxCount parameter must be an integer.

order

The order parameter specifics the order in which the feeds will be returned. Valid parameters are 'asc' and 'desc'. If not specified, the default order will be desc. An invalid parameter will result in a response with an error message and an HTTP status code of 400.

apiKey

The apiKey parameter specifies the unique API Key to be used to identify the customer and facilitate access control for the given request.  If supplied, the apiKey parameter will automatically be appended to each feed URL returned by the Atom request.  If not supplied, access control falls back to IP-address identification.

Example Requests

Requests for all baseball feed entries newer than 2006-06-30T01:56:35.2345-3:00

Requests for all latest 1000 feed entries newer than 2007-06-29T14:31:41.1384-3:00

Requests for all NFL boxscores

Requests for NBA boxscores newer than 2010-07-21T14:25:27.7248-3:00 in oldest first order

Handling Large Volumes of Updated Feeds

While receiving updates via the Atom feed is convenient, Atom requests must still be sensible for best results. As described above, this generally involves proper usage of time stamps to query for changes since the last Atom request was made. It is the client's responsibility to track which entries it has already handled and the time the previous request was made. Consider the following example protocol for frequent polling of NBA live scores: 

1. INITIAL ATOM REQUEST -  for 10 NBA live scores in ascending order (oldest first):

   http://xml.sportsdirectinc.com/Atom?feed=/nba/livescores&order=asc&maxCount=10

2. Loop; for each entry in feed response
   
   • request the URL of the entry
   • if entry was consumed successfully, store the value of the <updated> element within the entry
   • if failed, abort handling entries (exit loop)
     
     

3. Wait and make another Atom request specifying the newerThan parameter with the <updated> value of the last successfully parsed feed entry, plus 1 tick, for example:

   i.e. http://xml.sportsdirectinc.com/Atom?feed=/nba/livescores&order=asc&maxCount=10&newerThan=<updated>

4. Repeat!

This only works correctly if you sort the entries in ascending order, otherwise you will only get the 10 most recent updates. This protocol allows you to start from the oldest update and keep consuming until you have caught up.

This pattern is very powerful because it allows us to handle a very large number of clients and requests while not having to keep track of any client state. By having the client remember its own state, we can achieve robust transaction-like semantics with very little cost to the client or the server. The client is now able to retry or walk the feed forward and backward!