Overview
The American Football Fourth Down Predictions feed provides pre-game and live game Fourth Down predictions during the course of an American Football match.
The feed includes traditional match data such as match information, competition information, team details, and venue information, together with predictive information for Fourth Down decisions.
Problem Statement & Use Cases
This API solves the business problem of evaluating likely fourth-down decisions during live American Football game situations. It combines fixture context, game clock context, play context, team identity, and prediction outputs to support real-time decision analytics for whether a team is predicted to go for it, attempt a field goal, or punt.
| Use Case |
Description |
| Live game decision support |
Surface Fourth Down predictions to analysts, coaches, or operations teams during live match situations. |
| Broadcast and editorial graphics |
Display fourth-down decision recommendations, success likelihood, and associated win probability scenarios during a live game. |
| Fan engagement experiences |
Power in-game widgets that explain whether a team is predicted to go for it, attempt a field goal, or punt. |
| Predictive model enrichment |
Use Fourth Down prediction type and value fields as features in downstream American Football decision or win-probability models. |
Compliance & Guidelines
Authentication and API Security
To comply with Stats Perform API security and best-practice requirements, refer to the Stats Perform FAQs, API Overview, and Authentication Guide.
Authentication uses the OAuth method to fetch data.
Polling Frequency
Do not exceed the rate confirmed by Stats Perform. Contact a Stats Perform representative for higher rate limits or clarification.
| Feed |
Polling Frequency |
| Fourth Down Predictions (MA5) |
Once every 30 seconds |
Request Formatting Rules
All URLs are case-sensitive. URL strings must contain the correct case, operators, and required parameters, or the API returns an error.
| Rule |
Requirement |
| Query string start |
Begin the query parameter string with ? immediately after the feed name. |
| Parameter separator |
Separate query parameters with &. |
| Multiple values: AND |
Use & for multiple values where the API treats them as AND. |
| Multiple values: OR |
Use , only if the parameter supports OR-style multiple values. |
| NOT operator |
Use ! only if the parameter supports negation. |
| Underscore-prefixed parameters |
Include the required _ prefix for parameters such as _fmt and _clbk. |
| Placeholder braces |
Remove placeholder curly braces {} from production API calls. They are documentation examples only. |
| Case sensitivity |
Preserve exact URL, parameter, and operator case. |
| Base URL reference |
The base URL format is {protocol}://{requestDomain}/{feedResource}. |
JSONP Requirements
If _fmt=jsonp is used, it must be combined with the callback parameter _clbk.
| Constraint |
Requirement |
Reason |
| JSONP callback |
Use _fmt=jsonp together with _clbk. |
JSONP requires a callback wrapper function. |
| Fixed callback value |
Use a fixed _clbk value whenever possible. |
Random callback names can reduce cacheability and violate API best-practice logic. |
| JavaScript frameworks |
Override framework-generated random callback names, including defaults from common frameworks such as jQuery. |
Some frameworks generate random JSONP function names unless explicitly configured. |
Endpoints
Base URL
https://api.statsperform.com
Feed Resource
/sdapi/v1/footballdata/fourthdownpredictions
Get Fourth Down Predictions by Fixture Path Parameter
GET /sdapi/v1/footballdata/fourthdownpredictions/{fixtureUUID}?{queryParameters}
Get Fourth Down Predictions by fx Query Parameter
GET /sdapi/v1/footballdata/fourthdownpredictions?fx={fixtureUUID}&{queryParameters}
Endpoint Usage
| Usage |
Feed |
| Get Fourth Down predictions information by fixture inline path URL. |
/sdapi/v1/footballdata/fourthdownpredictions/{fixtureUUID}?{queryParameters} |
| Get Fourth Down predictions information by fixture UUID query parameter. |
/sdapi/v1/footballdata/fourthdownpredictions?fx={fixtureUUID}&{queryParameters} |
Query Parameters
This feed uses Global query parameters and the feed-specific query parameters listed below.
The /fourthdownpredictions feed must be queried by a specific fixture or match UUID.
Feed-Specific Query Parameters
| Query Parameter |
Description |
Example Request |
fixtureUUID |
Get Fourth Down predictions information by fixture inline path URL. |
GET https://api.statsperform.com/sdapi/v1/footballdata/fourthdownpredictions/{fixtureUUID}?_fmt=xml |
fx |
Get Fourth Down predictions information by fixture UUID query parameter. |
GET https://api.statsperform.com/sdapi/v1/footballdata/fourthdownpredictions?fx={fixtureUUID}&_fmt=xml |
Parameter Definitions
| Parameter |
Location |
Description |
Accepted Values / Format |
Required |
fixtureUUID |
Path |
Fixture or match UUID passed directly in the URL path. |
String; alphanumeric UUID |
Conditional |
fx |
Query |
Fixture or match UUID passed as a query parameter. |
String; alphanumeric UUID |
Conditional |
_fmt |
Query |
Response data format. |
Example: xml; other global formats may be supported by the API. |
No |
_clbk |
Query |
JSONP callback function name. |
Fixed callback function name. |
Required when _fmt=jsonp |
Fixture Identifier Requirements
| Requirement |
Description |
| Specific fixture required |
Every request must identify a specific fixture or match. |
| Path parameter method |
Use /fourthdownpredictions/{fixtureUUID} when passing the fixture identifier in the URL path. |
| Query parameter method |
Use /fourthdownpredictions?fx={fixtureUUID} when passing the fixture identifier as a query parameter. |
| Placeholder removal |
Remove {} braces from actual production requests. |
Output Schema
The feed response fields are documented using XML element names. JSON responses contain similar fields, but some XML-only nodes are omitted or represented differently.
`<fourth
DownPredictions>`
| Property |
Value |
| Nesting |
fourthDownPredictions |
| Description |
Required root element of the fields related to Fourth Down Predictions. |
| JSON behavior |
Attribute list is empty for JSON. |
| XML behavior |
XML feeds include the XML namespace attribute listed below. |
| Attribute |
Format |
Required |
Description |
Values |
xmlns:footballdata |
XML only |
No |
Schema reference returned for XML only. |
http://www.performgroup.com/schema/footballdata |
`<match
Info>`
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo |
| Description |
Required root element of the fields related to match information. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the fixture or match. |
String; alphanumeric UUID |
date |
No |
UTC start date of the fixture or match. |
Date in format YYYY-MM-DDZ |
time |
No |
Start time in UTC of the fixture or match. |
String |
localDate |
Yes |
Start date of the fixture according to the local time zone. |
Date in format YYYY-MM-DDZ |
localTime |
Yes |
Start time of the fixture according to the local time zone. |
Time in format hh:mm:ssZ |
week |
Yes |
Week in which the game takes place. |
Integer |
coverageLevelId |
No |
Level at which Stats Perform is covering the fixture. |
Integer |
lastUpdated |
Yes |
UTC date and time when the information or record was last updated. |
Date/Time in format YYYY-MM-DDThh:mm:ssZ |
<description>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/description |
| Description |
Required description of the fixture or match, giving the name of each contestant participating in the match. |
| Value |
String |
| Attributes |
None |
<sport>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/sport |
| Description |
Required root element of the fields related to the sport. |
| XML value |
String giving the sport name. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the sport. |
String; alphanumeric UUID |
name |
Yes |
Name of the sport. JSON only. |
String; alphanumeric UUID |
<ruleset>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/ruleset |
| Description |
Required root element of the fields related to the ruleset. |
| XML value |
String giving the ruleset name. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the ruleset. |
String; alphanumeric UUID |
name |
Yes |
Name of the ruleset. JSON only. |
String |
<competition>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/competition |
| Description |
Required root element of the fields related to the competition associated with the fixture or match. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the competition. |
String; alphanumeric UUID |
name |
Yes |
Name of the competition. |
String |
abbreviation |
Yes |
Abbreviated name of the competition. |
String |
<country> under <competition>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/competition/country |
| Description |
Root element of the related fields for the country where the competition is based. |
| XML value |
String giving the country name. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the country where the competition is based. |
String; alphanumeric UUID |
name |
Yes |
Name of the country where the competition is based. JSON only. |
String |
`<tournament
Calendar>`
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/tournamentCalendar |
| Description |
Required root element of the fields related to a tournament calendar. |
| XML value |
String giving the tournament calendar name. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the tournament calendar. |
String; alphanumeric UUID |
startDate |
Yes |
Start date of the tournament calendar. |
Date in format YYYY-MM-DDZ |
endDate |
Yes |
End date of the tournament calendar. |
Date in format YYYY-MM-DDZ |
name |
Yes |
Name of the tournament calendar. JSON only. |
String |
<stage>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/stage |
| Description |
Root element of the fields related to the stage. |
| XML value |
String giving the stage name. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the stage. |
String; alphanumeric UUID |
startDate |
Yes |
Start date of the stage. |
Date in format YYYY-MM-DDZ |
endDate |
Yes |
End date of the stage. |
Date in format YYYY-MM-DDZ |
name |
Yes |
Name of the stage. JSON only. |
String |
<contestants>
| Property |
Value |
| Format |
XML only |
| Nesting |
fourthDownPredictions/matchInfo/contestants |
| Description |
Required root element of the fields related to contestants. |
| Attributes |
None |
<contestant>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/contestants/contestant |
| Description |
Root element of the related fields for a contestant. |
The source documentation lists this node under matches/match/matchInfo/contestants/contestant. In this normalized reference, the node is represented under the MA5 Fourth Down Predictions feed root.
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the contestant. |
String; alphanumeric UUID |
name |
Yes |
Name of the contestant. |
String |
position |
Yes |
Indicates whether the contestant is the home or away side. |
home, away |
nickname |
No |
Nickname of the team. |
String |
location |
Yes |
Location to which the team belongs. |
String |
abbreviation |
Yes |
Abbreviation of the team name. |
String |
playoffSeed |
No |
Position at which the team is seeded in playoffs. |
Integer |
<country> under <contestant>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/contestants/contestant/country |
| Description |
Root element of the country-related fields for a contestant. |
| XML value |
String giving the country name. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the country the contestant is from. |
String; alphanumeric UUID |
name |
Yes |
Name of the country the contestant is from. JSON only. |
String |
<venue>
| Property |
Value |
| Nesting |
fourthDownPredictions/matchInfo/venue |
| Description |
Root element of the related fields for the venue. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the venue. |
String; alphanumeric UUID |
name |
Yes |
Name of the venue where the fixture is scheduled to be played. |
String |
city |
Yes |
Name of the city where the venue is located. |
String |
stateId |
Yes |
UUID of the state where the venue is located. |
String; alphanumeric UUID |
state |
Yes |
Name of the state where the venue is located. |
String |
countryId |
Yes |
UUID of the country where the venue is located. |
String; alphanumeric UUID |
country |
Yes |
Name of the country where the venue is located. |
String |
latitude |
Yes |
Latitude of the venue. |
String |
longitude |
Yes |
Longitude of the venue. |
String |
zipcode |
Yes |
Zip code of the venue. |
String |
neutral |
Yes |
Neutral venue indicator. |
String |
<predictions>
| Property |
Value |
| Nesting |
fourthDownPredictions/predictions |
| Description |
Required root element of the fields related to predictions. |
| Attributes |
None |
`<live
Predictions>`
| Property |
Value |
| Nesting |
fourthDownPredictions/predictions/livePredictions |
| Description |
Required root element of the fields related to live predictions. |
| Attribute |
Required |
Description |
Values |
timeMin |
Yes |
Game time in minutes. |
Integer |
timeSec |
Yes |
Game time in seconds. |
Integer |
periodId |
Yes |
Unique ID of the period in the game. |
String |
playId |
Yes |
Unique ID of the play. |
String |
contestantId |
Yes |
Unique UUID of the contestant. |
String; alphanumeric UUID |
lastUpdated |
Not specified |
UTC date and time when the prediction information was last updated. |
Date/Time in format YYYY-MM-DDThh:mm:ssZ |
`<fourth
Down>`
| Property |
Value |
| Nesting |
fourthDownPredictions/predictions/livePredictions/fourthDown |
| Description |
Required root element of the fields related to Fourth Down Predictions. |
| Attribute |
Required |
Description |
Values |
type |
Yes |
Type of Fourth Down prediction being made. |
Go for it, Field Goal, Punt |
<prediction>
| Property |
Value |
| Nesting |
fourthDownPredictions/predictions/livePredictions/fourthDown/prediction |
| Description |
Required root element of the fields related to prediction output values. |
| Attribute |
Required |
Description |
Values |
type |
Yes |
Type of prediction being made. |
Success, Win probability if made, Win probability if failed, Win probability if decision |
value |
Yes |
Predicted final value for type. |
String |
