JSONP API - Competition draw

This page actually displays the competition draw 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-draw/?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.

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-draw/?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-draw/',
		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);
		}
	});
	

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
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 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