You can deliver your content to CBS Interactive using either a web interface, or programmatically using HTTP. If you are delivering a small amount of content and you don't want to write the code needed to deliver via HTTP, you should use the web interface. If you are delivering a large amount of content or updating your content regularly, it will be more efficient to deliver it via the HTTP interface.


Creating a content app


Before you can deliver your content, you must set up a content app. You only have to do this once. To set up a content app:

          1. Log into the Development Center.
          2. Under MY APPS on the Development Center home page, click Create New App. The ABOUT THIS APPLICATION page appears.
          3. Select consists solely of content that will be uploaded in CSV or XML format. Additional form fields appear.
          4. Fill in the remaining fields and click Save & Continue. The ADDITIONAL INFORMATION page appears.
          5. Either, supply additional information about your app and click Save and Continue.
              OR
              Click Skip this step.
              The Development Center home page is displayed. Your new app is listed under MY APPS.







Preparing your content for delivery to CBS Interactive


Whether you deliver your content via the web interface or programmatically via HTTP, you must prepare your content in the appropriate form. You must submit your content as either XML or CSV, depending on the required format for the content you are submitting. The exact format of the XML or CSV documents to submit are described below.

Your data must identify players, sports, positions, and stats categories using official CBS Interactive codes. The procedure for obtaining these codes is given below.

Preparing player outlooks data


The fields for player outlooks are as follows:

Field Name Description
player_outlooks The outlook data root node
player_outlooks/@sport The CBS Interactive sports code for the sport covered by the outlooks
player_outlooks/@timestamp (optional) The timestamp of the outlook record in UNIX timestamp format. If you omit the timestamp field, the upload date and time will be used as the timestamp.
player_outlooks/player_outlook The outlook for the player, as plain ASCII text. Any links or other HTML codes will be stripped from the field on submission. Any non-ASCII characters will cause an exception and must be fixed before your submission is accepted. Newlines in the text will be retained. A warning will be issued if anything is stripped from the content, but the content record will be accepted, in its stripped form.
player_outlooks/player_outlook/@player_id The CBS Interactive player ID for the player whose outlook is being given.
player_outlooks/player_outlook/@timestamp (optional) The timestamp of the player record in UNIX timestamp format. If you omit the timestamp field, the upload date and time will be used as the timestamp.

You must format your content as an XML file, as in the following example:

<?xml version="1.0" encoding="utf-8"?> <player_outlooks sport="baseball" timestamp="1321046902"> <player_outlook player_id="223571" timestamp="1321046902"><![CDATA[Albert Pujols took a step back in 2010, but he was still one of the most productive players in baseball. His 42 homers and 118 RBI were both down from the year prior, as were his .312 average and .596 slugging percentage. But the 31-year-old still finished second in NL MVP voting and produced his 10th consecutive year of at least 30-plus homers and 100 RBI. Consider Pujols a top 5 Fantasy pick on Draft Day.]]></player_outlook> <player_outlook id="589256" timestamp="1321046902"> . . . </player_outlook> </player_outlooks>

Preparing player updates data


The fields for player updates are as follows:

Field Name Description
player_updates The player updates data root node.
player_updates/@sport The CBS Interactive sports code for the sport covered by these updates.
player_updates/@timestamp (optional) The timestamp of the updates in UNIX timestamp format. If you omit the timestamp field, the upload date and time will be used as the timestamp.
player_updates/player_update The root node for the individual player update.
player_updates/player_update/@player_id The CBS Interactive player ID for the player whose update is being given.
player_updates/player_update/@timestamp (optional) The timestamp of the player's update in UNIX timestamp format. If you omit the timestamp field, the upload date and time will be used as the timestamp.
player_updates/player_update/@status (optional) The status of the update, as one of the following: hot, cold, normal. If you do not specify the status field, it will default to normal.
player_updates/player_update/headline The news headline for a player, as plain ASCII text. Any HTML codes or non-ASCII characters will be stripped from the field on submission.
player_updates/player_update/news The news for the player, as plain ASCII text. Any HTML codes or non-ASCII will be stripped from the field on submission.
player_updates/player_update/analysis (optional) The analysis of the news for the player, as plain ASCII text. Any HTML codes or non-ASCII will be stripped from the field on submission. If anything is stripped from the content, a warning will be issued, but the submission will be accepted.

If submitting your updates using HTTP, you would format your content as an XML file, as in the following example:

<?xml version="1.0" encoding="utf-8"?> <player_updates sport="baseball" timestamp="1321046902"> <player_update player_id="223571" timestamp="1321046902" status="hot"> <headline>Pujols set to run the bases</headline> <news><![CDATA[A day after being activated from the disabled list, Cardinals 1B Albert Pujols was in the starting lineup posted for Wednesday's game against Cincinnati. The Cardinals decided to activate Pujols on Tuesday after he received medical clearance and went through a strenuous workout prior to the team's game against Cincinnati. He did not play in the game, however. Pujols finished 1 for 6 with an RBI single in the extra-inning win. "That was awesome, man," he said. "For us to be the winning team you're going to have to do things like that. We're not going to give up."]]> </news> <analysis><![CDATA[Pujols, who had been on the DL since late June, was made available to play Tuesday if needed. He appeared to be good to go without any restrictions or limitations initially. That alone makes him worthy of activating in Fantasy leagues. Monitor him on a day to day basis in the early stages of his comeback as the Cardinals could opt to give him a day off here or there, but it seems all systems are go for Pujols and his Fantasy owners again.]]> </analysis> </player_update> <player_update id="589256" timestamp="1321046902"> . . . </player_update> </player_updates>

Projections


The fields for each projection record are as follows:

Field Name Description
player_id A CBS Interactive player ID.
sport A CBS Interactive sport name.
timestamp (optional) The timestamp of the update record in UNIX timestamp format. If you omit the timestamp field, the upload date and time will be used as the timestamp.
timeframe The timeframe covered by the projections, as a year in the format YYYY. This must be the year in which the current season started.
period The following periods are available for Football and Baseball:
season - projections for the entire season
weekX - projections for the week (where 'X' is the period number as an integer, ex. week6)


The following periods are available for Baseball only:
restofweek - remainder of the week
7d - Next 7 days
14d - Next 14 days
monthX - projections for the month (where 'X' is the month number as an integer, ex. month8)
restofseason - remainder of the season
YYYYMMDD - Single day
(stats categories)* One field for each stats category for which you are providing a projection. The name of each field is a CBS Interactive stats category code. The value of each field is the value of that stat in the appropriate format for that stat. You do not have to specify a projection for every stats category.

If you've already uploaded projections for a player for a period and want to make an update, the only Stats Categories that will update are the ones included in your new upload -- all other Stats Categories will remain unchanged. So, if you want to zero out a stat, you will need to upload the stat with a value of zero.

*Note: You can not upload Projections for Stats Categories that are calculated. They will be calculated for you based on the projections you've uploaded for the component stats -- see the list of calculated stats categories in the tables below.

The format of a projections submission is a CSV file, as in the following example, where the first row contains the field names, as described above, and the following rows contain the values, one record per row.

player_id,sport,timestamp,timeframe,period,1B,2B,3B,HR,H,AB,RBI 589256,baseball,1321046902,2012,season,107,33,5,29,174,565,97 393458,baseball,1321046902,2012,season,111,38,3,25,177,570,102 589256,baseball,1321046902,2012,restofseason,2,0,1,8,24,4,3 589256,baseball,1321046902,2012,20110708,1,1,0,0,2,4,1 589256,baseball,1321046902,2012,7d,1,1,0,0,2,4,1


Baseball Pitching Categories that are Calculated (you can not upload these categories):

Pitching StatNameFormula
BAABatting Average AgainstHA / ABA
BBd9Walks per NineBBI * 9 / INN (Note: INN is calculated by OUTS / 3)
ERAEarned Run AverageER * 9 / INN (Note: INN is calculated by OUTS / 3)
GdAOGround Outs/Air OutsGO / AO
HIPHits per InningHA / INN (Note: INN is calculated by OUTS / 3)
Hd9Hits per NineHA * 9 / INN (Note: INN is calculated by OUTS / 3)
INNInningsOUTS / 3
K-BBStrikeouts Minus WalksK - BBI
Kd9Strikeouts per NineK * 9 / INN (Note: INN is calculated by OUTS / 3)
MERAModified ERA800 * (4.5 - ERA) (Note: ERA is calculated by ER * 9 / INN and INN is calculated by OUTS / 3)
NWNet Wins2 * W - L
OBAOn Base Pct Against(HA + BBI + HB) / PA
Rd9Men on Base/ 9 Innings(HA + BBI + HB) * 9 / INN (Note: INN is calculated by OUTS / 3)
W-LWins Minus LossesW - L
WHIPWalks + Hits / Inning(BBI + HA) / INN (Note: INN is calculated by OUTS / 3)
WPCTWinning PctW / (W + L)


Baseball Batting Categories that are Calculated (you can not upload these categories):

Batting StatNameFormula
BABatting AverageH / AB
BPBases ProducedTB + SB
BPAPlate Appearances (Batter)AB + BB + HP + CI + SH + SF
COMComboBB + SB - KO
DTDoubles Plus Triples2B + 3B
FPCTFielding Pct(PO + AST) / FC
OBPOn Base Pct(H + BB + HP) / (AB + BB + HP + SF)
OPSOn Base plus Slugging Pct((H + BB + HP) / (AB + BB + HP + SF)) + (TB / AB)
PPProduction Pct((H + BB + HP) / (AB + BB + HP + SF)) + (TB / AB)
RBI-HRRBI Minus Home RunsRBI - HR
RPRuns ProducedR + RBI - HR
RPARuns Produced Average(R + RBI - HR) / AB
RdABRuns per At BatR / AB
SB-CSStolen Bases - Caught StealingSB - CS
SBPCTStolen Base Pct100 * SB / (SB + CS)
SDTSingles + Doubles + Triples1B + 2B + 3B
SLGSlugging PctTB / AB
TPATotal Pct AverageBA + ((H + BB + HP) / (AB + BB + HP + SF)) + (TB / AB)
XBHExtra Base Hits2B + 3B + HR


Football Defensive Categories that are Calculated (you can not upload these categories):

Defensive StatNameFormula
DFTDDefensive TDIntTD + DFRTD
DTDTotal Defensive and Special Teams TDIntTD + PRTD + KRTD + DFRTD + BFTD + BPTD + SFRTD
KRAvgKick Return Average (ST/DST)KRYd / KR
PRAvgPunt Return Average (ST/DST)PRYd / PR
STTDSpecial Teams TDPRTD + KRTD + BFTD + BPTD + SFRTD
YDSYards AllowedPaNetA + RuYdA


Football Offensive Categories that are Calculated (you can not upload these categories):

Offensive StatNameFormula
CmpPctCompletion PercentagePaCmp / PaAtt * 100
CmpPctMinCompletion Percentage, 10+ Pass AttemptsPaCmp / PaAtt * 100
IFRTDIndividual Fumble Recovery TDOFRTD + DFRTD + SFRTD
IKRTDIndividual Kick Return TDKRTD
IKRYdIndividual Kick Return YardsKRYd
IPRTDIndividual Punt Return TDPRTD
IPRYdIndividual Punt Return YardsPRYd
MFGMissed Field GoalFGA - FG
MXPMissed Extra PointXPAtt - XP
PaRuYdPassing and Rushing YardsPaYd + RuYd
ReAvgAverage per ReceptionReYd / Recpt
ReAvgMinAverage per Reception, 3+ ReceptionsReYd / Recpt
ReFDPctReceiving FD PctReFD / Recpt * 100
RuAvgRushing Average per AttemptRuYd / RuAtt
RuAvgMinRushing Average, 5+ RushesRuYd / RuAtt
RuReYdRushing and Receiving YardsRuYd + ReYd
TarPctTarget PercentageTar / PaAtt * 100
TotYdPassing, Rushing & Receiving YardsPaYd + RuYd + ReYd


Rankings (coming soon)

The ability to create Content Applications for Rankings will not be available for the launch of the Fantasy Platform, but will be coming soon.







OBTAINING CBS INTERACTVE ID CODES


To obtain the official CBS Interactive ID codes to identify players, sports, positions, and stats categories you must request the appropriate resources using the Fantasy Platform API. For more information on the Fantasy Platform API and the resources available from it, see the Fantasy Platform API documentation.

There is currently no HTML interface to the Fantasy Platform API. To get the codes you can either type the URL of the resource into a browser and copy or save the XML or JSON document it returns for the browser window, or you can call the API from your application code using a standard HTTP request method.

To access the Fantasy Platform API, you will need an access token. You must pass the access token to the Fantasy Platform API as a parameter to the URL. For example, to request the Positions resource for the sport of baseball, you would use the following URL:

http://api.cbssports.com/fantasy/positions?access_token=xyz123abc789&SPORT=baseball



Obtaining an access token


To obtain an access token make an HTTP POST request to the following URL:

https://api.cbssports.com/general/oauth/generate_token

with the following POST parameters:

app_id - The ID listed on the Application Detail page for this Application in the "About This App" box.

app_secret - The Secret listed on the Application Detail page for this Application in the "About This App" box.

response_format - (optional) The format you want the response in, either XML or JSON (defaults to XML).



For example:

      POST /general/oauth/generate_token HTTP/1.1
      Host: api.cbssports.com
      User-Agent: Mozilla/4.0
      Content-Length: 49
      Content-Type: application/x-www-form-urlencoded
      app_id=myAppID&app_secret=myAppSecret


The response will contain your access token, or an error message, if your login fails.



XML response format:

<?xml version="1.0"?> <result uriAlias="/oauth/generate_token" uri="/oauth/generate_token" statusCode="200" statusMessage="OK"> <body> <access_token>XXXXX</access_token> </body> </result>

JSON response format:

{ "body" : { "access_token" : "XXXXX" }, "uriAlias" : "/oauth/generate_token", "statusMessage" : "OK", "uri" : "/oauth/generate_token", "statusCode" : 200 }

Possible Error Messages:

  • missing required parameter: app_id
  • missing required parameter: app_secret
  • unable to validate app_id/app_secret


URLs for obtaining the ID codes


The URLs for the Players, Sports, Positions, and Stats Categories are as follows. See the Fantasy Platform API documentation for details on how to call each of these URLs.

Resource URL
Players http://api.cbssports.com/fantasy/players/list
Sports http://api.cbssports.com/fantasy/sports
Positions http://api.cbssports.com/fantasy/positions
Stats Categories http://api.cbssports.com/fantasy/stats


Keeping up to date


With the exception of the player data, you should not need to retrieve the ID codes more than once per season. Due to player trades and other changes in status, the Players resource may change at any time during the season. To ensure that you are working with the most up-to-date information, you should request a new copy of the Players resource before preparing your content to submit to CBS Interactive.



Delivering your content using the web interface


To deliver your content using the web interface:

          1. Log on to the Developer Center.
          2. Under MY APPS on the DEVELOPMENT CENTER HOME page, choose your content app (the app you created under Creating a content app above).
          3. Click the Upload Content button near the top of the page (it's right above the About This App box).
          4. Set the Content Type field to the type of your content.
          5. Either, chose the file you want to upload in the Upload File field
              OR
              Cut and past the the file contents into the Content field.
          6. Press Submit. Your content will be validated and any errors or warnings will be displayed.



Delivering your content using HTTP


To deliver your content using HTTP, create an application to submit your content using the HTTP POST method. The POST method is supported by most programming and scripting languages, either natively or through a library. You must use the content type multipart/form-data.

Your content should be POSTed to the appropriate URL from the following list. Note that the access token must be included as a URL parameter named access_token.

Param Value
access_token Your CBSSports access token (In the sample below, the value xyz123abc789 is used to represent your access token.)
type The type of content you are submitting: updates, projectionss or outlooks
response_format The format in which you want the system to respond: json or xml (Note that this is NOT the format in which you are submitting your data. You MUST submit your data in XML.)
data Your content, in XML or CSV format, as appropriate for the type of content you are submitting.
validate_only (optional) A Boolean value indicating whether to save the data or just to validate the data and not actually save it. 1 (only validate the content) or 0 (validate and save the content).

The data you submit will be validated by the server when received. If the content is not valid, an error response code will be returned, along with a message detailing the validation errors.

If you submit several player updates or outlooks in a single transmission, they will be validated separately and the valid entries will be accepted. You will receive an error response code along with a message detailing which entries failed validation and why.

If your content submission is received and validated correctly, the API will return an HTTP status code of 200 OK.



Example POST message

POST http://api.cbssports.com/upload/content/player Content-Length: 2657 Content-Type: multipart/form-data; boundary=xYzZY --xYzZY Content-Disposition: form-data; name="access_token" xyz123abc789 --xYzZY Content-Disposition: form-data; name="data" <?xml version="1.0" encoding="utf-8"?> <player_outlooks sport="baseball" timestamp="1324399486"> <player_outlook player_id="223571" timestamp="1324399486"><![CDATA[Albert Pujols took a step back in 2010, but he was still one of the most productive players in baseball. His 42 homers and 118 RBI were both down from the year prior, as were his .312 average and .596 slugging percentage. But the 31-year-old still finished second in NL MVP voting and produced his 10th consecutive year of at least 30-plus homers and 100 RBI. He heads into the 2011 campaign as one of the elite Fantasy 1B and should be able to keep pace with what he has done his entire career. His career .624 slugging percentage and .426 on-base percentage are rare for any position and his high walk-to-strikeout rate means that he should continue to produce at a high level. He has been the model of consistency since coming into the league in 2001 and usually gets better as the season goes on. Consider Pujols a top 5 Fantasy pick on Draft Day.]]></player_outlook> <player_outlook player_id="292238" timestamp="1324399486"><![CDATA[After three straight years of the same all-or-nothing numbers, Uggla threw a wrench in the equation last year, emerging as arguably the best offensive second baseman in the National League in a year when Chase Utley was limited by injuries. He set career highs in batting average, on-base percentage and OPS, which led to career highs in home runs and RBI as well. His performance forced the Marlins to trade him to the Braves, knowing they couldn\'t re-sign him in the offseason. The biggest change for him was consistency. He hit .290 or better in four of the season\'s six months after doing so a total of three months over the previous three seasons. He\'ll be 31 by opening day, so he picked an awkward time to take a step forward. But considering his increasing walk rate over the last few years, his improvement in other categories was a logical next step. His high strikeout rate leaves him vulnerable to a low batting average, but given his career .354 batting average, 12 homers and 1.051 OPS at Turner Field, he could have more good times ahead. Expect him to go off the board soon after the elite four of Robinson Cano, Utley, Dustin Pedroia and Ian Kinsler.]]></player_outlook> </player_outlooks> --xYzZY Content-Disposition: form-data; name="type" outlooks --xYzZY Content-Disposition: form-data; name="response_format" json --xYzZY--

Response format

The response format conforms to the following structure

If validate_only parameter is true:

<summary> <incoming_records> # number of records received <validated_records> # number of records validated successfly</validate_records> </summary> <warnings> <warning>Text describing the warning</warning> ... </warnings> <exceptions> <exception>Text describing the exception</exception> ... </exceptions>

If validate_only parameter is false and extra saved_records node is added to the summary specifying how many records were saved.:

<summary> <incoming_records> # records received</incoming_records> <validated_records># records validated</validate_records> <saved_records># records saved</saved_records> </summary> ...

A 200 response will always be returned with the exception of a 500 for missing parameters and a 404 response will be returned if your access_token refers to an invalid application.