JSONP API - Competition results

This page actually displays the competition results on your website. You fetch the JSON data from our servers then render it onto the page.

Go to the Publish page for any competition in your organisation. In the JSONP API section you will see a link like:
http://sportsgen.net/your-organisation-custom-url/api/competition-results/?competition=3

You can visit the link in your browser or click the Preview link to view the JSON. If you are using Firefox you can download an add-on like JSONovich which displays the JSON in a nice readable format. Alternatively if you have Firebug installed, open Firebug, then open the Net menu, then expand (+) the GET link for the page returned. Now click the JSON tab below the link to view the data. There are also extensions for Google Chrome. Here is a live example you can use to test your browser add-on/extension.

Download a working code example for displaying the competition draw in JavaScript / jQuery.

API Request Data

To get the data from the server there are some query string parameters that you can add to the URL:

Parameter Type Description Example
apiVersion integer Pass in the API version you are wishing to retrieve data for. The current version is 1. It is important to pass in the API version because if you don't it will use the latest version by default. This may be problematic as future versions of the API may break backwards compatibility slightly. We will however leave support for older API versions when a new version is released so existing sites won't break. 1
callback string An optional callback for the JSONP request. Pass in the function name which you want to be called once the request has been completed. The callback is the correct way to work around the same origin policy restrictions that are set on web browsers so you can retrieve data from other domains. For further information on JSONP and why it's needed check the Wikipedia link above. Modern browsers may work fine with basic JSON as we send a CORS Access-Control-Allow-Origin: * header in the response but JSONP is a safer idea as it supports older browsers like IE9 and lower.

If you're requesting the data from a server side language like PHP you don't need the callback. If you're using jQuery this will be handled seamlessly for you if you set the dataType to "jsonp" in the jQuery.ajax request which means you won't have to add the callback parameter yourself, you'll just need to put your processing code in the success closure function which will run your code when the JSON data has been downloaded.
displayDraw
competition integer Pass in the unique competition number 3

If using jQuery the full generated request URL might look like this:
http://sportsgen.net/examples/api/competition-results/?competition=3&apiVersion=1&callback=jQuery18184_135730

Because the callback parameter is present, this means we're using JSONP so the returned JSON data gets wrapped in a function call which is automatically created by jQuery e.g.
jQuery18184_135730({ "apiVersion": 1, "competition": 3, "name": "Test tournament", ... });

This all gets put inside a <script></script> tag on the page by jQuery and the function automatically runs. jQuery does some magic behind the scenes and the JSON data flows through to the success closure function and your code in there can process the data. For example:

	$.ajax({
		url: 'http://sportsgen.net/examples/api/competition-results/',
		dataType: 'jsonp',
		data: { 'apiVersion': 1, 'competition': 3 },
		success: function(data)	{

			// You can work with the downloaded data here and it's now a standard JavaScript object
			console.log(data);
		}
	});
	
API Response Data

When the JSONP data is returned from the server it will return it in a single JavaScript object which you can use immediately. See a live example. See image of JSON data example above. If using the jQuery method outlined above or in the code examples then you won't need to parse the JSON data to native JavaScript. If you're using a server side language then you'll need to parse/deserialize the JSON data to an array or object in that language so you can work with it.

Property name Type Description Example
competition integer The unique number for this competition on SportsGen. This is a required field so will always be present. 3
name string The competition name. This is a required field so will always be present. "Test tournament"
description string The competition description. If there's no description this property will be null. "Testing tournament"
type string The competition type e.g. Round-robin, Double round-robin etc. This is a required field so will always be present. "Group stage + knockout"
sport string The competition sport. This is a required field so will always be present. "Basketball"
timeZone string The time zone of the competition e.g. "Pacific/Auckland", "Australia/Sydney" etc. This time zone is set when the competition is created or edited and all the dates and times for the games use this time zone. A list of time zones is available from here. If you are pulling the JSON feed and parsing it server side with a language like PHP it is possible to use the timestamps provided and convert dates and times to a time zone you need. External libraries may also exist for JavaScript to do this as well. This is a required field so will always be present. "Australia/Sydney"
timeZoneOffset string The general timezone offset from UTC/GMT for the timezone listed above (format is +12:00 hours or -11:30 hours). This is for display purposes only and should not be used for calculations as it won't work with Daylight Saving Time. This is a required field so will always be present. "+10:00"
startTimestamp integer A UNIX timestamp for the start date and time of the competition. This is a calculated value which determines the earliest game in the competition. Use this value if you will be displaying the datetime for the user in their local time zone using JavaScript in the browser with the Date() function or if you need to convert the timestamp to a different time zone using an external library.

If you're using the timestamp value in JavaScript, remember to multiply it by 1000, because JavaScript uses time in milliseconds instead of seconds. This property will be null if it has not been set.
1343034000
startDate string The start date of the competition in the time format set for the competition (default format is Mon 27 Aug 2012). This is a calculated value which determines the earliest game in the competition. Use this value if you want to use the time zone which was set for the competition when it was created or last edited. This property will be null if it has not been set. "Mon 23 Jul 2012"
startTime string The start time of the competition in the time format set for the competition (default format is 24-hour time e.g. 14:41). This is a calculated value which determines the earliest game in the competition. Use this value if you want to use the time zone which was set for the competition when it was created or last edited. This property will be null if it has not been set. "19:00"
endTimestamp integer A UNIX timestamp for the end date and time of the competition. This is a calculated value which determines the last game in the competition. Use this value if you will be displaying the datetime for the user in their local time zone using JavaScript in the browser with the Date() function or if you need to convert the timestamp to a different time zone using an external library.

If you're using the timestamp value in JavaScript, remember to multiply it by 1000, because JavaScript uses time in milliseconds instead of seconds. This property will be null if it has not been set.
1346062080
endDate string The end date of the competition in the time format set for the competition (default format is Mon 27 Aug 2012). This is a calculated value which determines the last game in the competition. Use this value if you want to use the time zone which was set for the competition when it was created or last edited. This property will be null if it has not been set. "Mon 27 Aug 2012"
endTime string The end time of the competition in the time format set for the competition (default format is 24-hour time e.g. 14:41). This is a calculated value which determines the last game in the competition. Use this value if you want to use the time zone which was set for the competition when it was created or last edited. This property will be null if it has not been set. "20:08"
lastUpdatedTimestamp integer A UNIX timestamp for the date and time the competition was last updated by the competition administrator. This is potentially useful for players and organisers to see if they've got the latest copy of the sports draw. Use this value if you will be displaying the datetime for the user in their local time zone using JavaScript in the browser with the Date() function or if you need to convert the timestamp to a different time zone using an external library.

If you're using the timestamp value in JavaScript, remember to multiply it by 1000, because JavaScript uses time in milliseconds instead of seconds. This property will be null if it has not been set.
1342845309
lastUpdatedDate string The date the competition was last updated by the competition administrator (default format is Mon 27 Aug 2012). This is potentially useful for players and organisers to see if they've got the latest copy of the sports draw. Use this value if you want to use the time zone which was set for the competition when it was created or last edited. This property will be null if it has not been set. "Sat 21 Jul 2012"
lastUpdatedTime string The time the competition was last updated by the competition administrator (default format is 24-hour time e.g. 14:41). This is potentially useful for players and organisers to see if they've got the latest copy of the sports draw. Use this value if you want to use the time zone which was set for the competition when it was created or last edited. This property will be null if it has not been set. "14:35"
totalRounds integer The total number of rounds in the competition. This property will be set to 0 if there are no rounds. 6
totalGames integer The total number of games in the competition. This property will be set to 0 if there are no games. 32
gameTimeLength integer The length of the game time in seconds for all games in the competition. This includes allowances for half time, overtime etc. This is a required field so will always be set. 2880
scoringMethod string How each game is scored for this competition. For example in hockey teams win by the highest number of goals and in rugby the game is won by the most number of points. This is mainly useful if your organisation manages competitions for different sports, so for each competition you can automatically adjust whether the page says "points scored" or "goals scored" etc. This is a required field so will always be set. "goals"
winPoints integer How many overall competition points are awarded for winning a game. This property will always be at least 0 points. 3
drawPoints integer How many overall competition points are awarded for a draw. This property will always be at least 0 points. 1
lossPoints integer How many overall competition points are awarded for a loss. This property will always be at least 0 points. 0
tiebreakerCriteria array An array containing objects with the various tiebreaker criteria and the order in which they apply. This is useful if you want to display this data on the page so users can see how the placings are calculated when there is a tie. See the next section for more details about the data in each object. If there is no tiebreaker criteria this property will have an empty array. []
placings array An array of objects containing a summary of all the placings data for each pool/group. This shows how each team is currently placed/ranked in each pool of the competition and depends on results entered so far. Essentially from this data you can generate a points table for each pool with all the current rankings to display on the page. See the next section for more details about the data in each object.

If there are no teams in the system for the competition then this property will contain an empty array. Generally if that happens it means the competition is incomplete and will need to be recreated. If the competition has been created properly you will have at least one object in the array.
[]
games array Contains an array of game objects for the competition. See the next section for more details about the data in each object. If there are no games this property will have an empty array. []
Objects inside the tiebreakerCriteria array
Property name Type Description Example
order integer The order in which the tiebreaker criteria is applied when calculating the placings, 1 is applied first, 4 last. This property will always have a value of at least 1. 2
shortDescription string A brief description of the tiebreaker criteria. This is a required field so will always be set. "Highest total game scores"
longDescription string A longer description/explanation of the tiebreaker criteria. This could be used if you put the information in a title attribute then when they hover the mouse over the short description they can get more information. This is a required field so will always be set. "Total of game scores (points/goals etc) irrespective of score conceeded."
Objects inside the placings array
Property name Type Description Example
pool string The pool/group letter that the teams are in e.g. A, B, C. If this is a round-robin or double round-robin competition which doesn't have pools then the value will be null. "A"
teams array An array of objects for each team in the pool. Each object contains information about a team's statistics in the round-robin or pool play stage. For example it will contain their current placing, number of overall points, number of games played etc. See the next section for more details about the statistics data in each object. This property should always contain at least two team objects in the array. []
Objects inside the teams array

This section contains the team statistics for games that have currently been played in the round-robin or pool play stage of a competition. In the pool play stage of a group stage tournament (e.g. World Cup), statistics for the games are totalled up and the best two teams go through to the knockout stage. Statistics for knockout stage games are not included into the statistics from the pool play stage.

Property name Type Description Example
team integer The unique number for this team on SportsGen. This number could likely be used in future API functionality to get more details about a team but for now it's not used. This property is a required field so will always exist. 48
teamName integer The name of the team. This property is a required field so will always exist. "Chicago Bulls"
placing integer The current placing for this team in the competition. For first place this would be 1, second place would be 2 etc. As more games are played and results updated on SportsGen, the placings of the teams can change. The placing is calculated as the highest number of overall points in the competition. Then if two teams have the same number of overall points, then their placings are decided by the tiebreaker criteria. This property is a required field so will always exist. 2
gamesPlayed integer The total number of games played by this team in the competition. This property will be 0 if not set. 3
gamesWon integer The total number of games won by this team in the competition. This property will be 0 if not set. 2
gamesDrawn integer The total number of games that have been played by this team in the competition that have resulted in a tie with the other team. This property will be 0 if not set. 0
gamesLost integer The total number of games lost by this team in the competition. This property will be 0 if not set. 1
scoreFor integer Score means the number of goals/points a team scored in a game. This property will contain the total goals/points they've scored for games they've played in this competition. This property will be 0 if not set. 105
scoreAgainst integer Score means the number of goals/points a team scored in a game. This property will contain the total goals/points other teams have scored against this team in this competition. This property will be 0 if not set. 87
scoreAverage float Score means the number of goals/points a team scored in a game. This property is calculated as number of goals/points scored by this team in the competition divided by the number of goals/points scored against it. This value is rounded to a maximum of 3 decimal places. This property will be 0 if not set. 1.207
scoreDifference integer Score means the number of goals/points a team scored in a game. This property is calculated as number of goals/points scored by this team in the competition minus the number of goals/points scored against it. It is possible for this value to go into negative integers. This property will be 0 if not set. 18
overallPoints integer This is the overall number of points scored by this team so far in the competition. Every time a game is played, the team gets a certain number of overall points depending on whether the result was a win, draw or a loss. This is the first ranking criteria for the points table. So the team with the highest number of overall points would be top of the points table. If two teams have the same number of overall points, then the placing is decided by the tiebreaker criteria. This property will be 0 if not set. 6
Objects inside the games array
Property name Type Description Example
game integer The unique number for this game on SportsGen. Will likely be used in future API functionality to get more details about a game, for example game statistics. This is a required field so will always be set. 17
roundNumber integer The round number for the game e.g. 1, 2, 3. This property is a required field and will be always be set to at least 1. 1
pool integer The pool/group letter for the game e.g. A, B, C. If this is not set e.g. it's a knockout round game, or it's a round-robin competition which doesn't have pools then the value will be null. A
knockoutRoundNameShort string A shortened version of the knockout round name e.g. for Quarter-final 2 the value would be QF2. If this is not a knockout round then this value will be null. QF2
knockoutRoundName string The full knockout round name e.g. Pre-quarter final 3, Quarter-final 2, Semi-final 1, Bronze Final, Final. If this is not a knockout round then this value will be null. Quarter-final 2
venueName string The name of the venue for the game. If there is no venue set, then this property will be null. Amway Center
gameStartTimestamp integer A UNIX timestamp for the start date and time of the game. Use this value if you will be displaying the datetime for the user in their local time zone using JavaScript in the browser with the Date() function or if you need to convert the timestamp to a different time zone using an external library.

If you're using the timestamp value in JavaScript, remember to multiply it by 1000, because JavaScript uses time in milliseconds instead of seconds. This property will be null if it has not been set.
1343034000
gameStartDate string The start date of the game in the time format set for the competition (default format is Mon 27 Aug 2012). Use this value if you want to use the time zone which was set for the competition when it was created or last edited. This property will be null if it has not been set. Mon 23 Jul 2012
startTime string The start time of the game in the time format set for the competition (default format is 24-hour time e.g. 14:41). Use this value if you want to use the time zone which was set for the competition when it was created or last edited. This property will be null if it has not been set. 19:00
firstTeamName string The name of the first team playing in the game. This will either contain the actual team name, or if that hasn't been determined yet (e.g. it's a knockout game and there aren't enough results entered to determine who will be playing) then it will contain a placeholder name e.g. Quarter-final 1 winner. This is a required field so will always be set. Denver Nuggets
secondTeamName string The name of the second team playing in the game. This will either contain the actual team name, or if that hasn't been determined yet (e.g. it's a knockout game and there aren't enough results entered to determine who will be playing) then it will contain a placeholder name e.g. Semi-final 1 winner. This is a required field so will always be set. Chicago Bulls
firstTeamScore integer The game score in points/goals for the first team in the game. If a score is set to 0 then this is a valid game result meaning they didn't score any points/goals in the game. This will be set to null if the results haven't been entered yet. If using JavaScript and checking for this, then use the === operator which checks the value and type. 12
secondTeamScore integer The game score in points/goals for the second team in the game. If a score is set to 0 then this is a valid game result meaning they didn't score any points/goals in the game. This will be set to null if the results haven't been entered yet. If using JavaScript and checking for this, then use the === operator which checks the type and value. 12
HTML5 Powered with Connectivity / Realtime, CSS3 / Styling, Performance & Integration, and Semantics