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 |
