Endpoints

get
seasons

https://api.natstat.com/v1/seasons
This endpoint is available for all 18 competition levels. A query to this endpoint without an id parameter will return a list of all the competition level's seasons and their id codes, including an overview of stat granularity availability. Passing an id parameter will return all metadata for the season as well as a list of sublevels and playoff results if available. Please note that this endpoint can be used synonymously as seasons.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid season ID code, which returns details for that season. (A list of available seasons can be retrieved from this endpoint by not passing an ID code.)
sublevel
optional
number
A valid sublevel (leagues, conferences) ID code. A list of sublevels can be retrieved from the glossary endpoint.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All WNBA seasons

https://api.natstat.com/v1/seasons/WNBA/?key=XXXX-XXXXXX&format=xml

seasons.xml

WNBA 2016 season detail

https://api.natstat.com/v1/seasons/WNBA/?key=XXXX-XXXXXX&format=xml&id=2016

seasons1.xml

get
teams

https://api.natstat.com/v1/teams
This endpoint services all 18 competition levels. A query to this endpoint without an id parameter will return a list of all teams for the competition level with their id codes. Filtering by season will show all teams active in that season. Passing an id parameter will return all metadata for the team, a list of seasons played, current ELO rating and social account information. Please note that this endpoint can be used synonymously as team.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid team ID code, which returns details for that team. (A list of available teams can be retrieved from this endpoint by not passing an ID code.)
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint.
search
optional
string
For general search of endpoint contents. Queries of four characters or less will be ignored.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All NHL teams

https://api.natstat.com/v1/teams/NHL/?key=XXXX-XXXXXX&format=xml

teams.xml

Florida Panthers

https://api.natstat.com/v1/teams/NHL/?key=XXXX-XXXXXX&format=xml&id=152

teams1.xml

Colorado Avalanche 2016

https://api.natstat.com/v1/teams/NHL/?key=XXXX-XXXXXX&format=xml&id=153&season=2016

teams2.xml

get
players

https://api.natstat.com/v1/players
This endpoint services all 18 competition levels. A query to this endpoint without an id parameter will return a list of all players for the competition level with their id codes, plus current team if active. Passing an id parameter will return all metadata for the player and a list of seasons played. Passing an additional season parameter will return a players basic game performance data, season stats/rankings, and data insights. Please note that this endpoint can be used synonymously as player.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid player ID code, which returns details for that player. (A list of available players can be retrieved from this endpoint by not passing an ID code.)
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint. Must be used in conjunction with id.
search
optional
string
For general search of endpoint contents. Queries of four characters or less will be ignored.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All KBO Players

https://api.natstat.com/v1/players/KBO/?key=XXXX-XXXXXX&format=xml

players.xml

Bae Him-chan

https://api.natstat.com/v1/players/KBO/?key=XXXX-XXXXXX&format=xml&id=330825

players1.xml

Henry Sosa 2018

https://api.natstat.com/v1/players/KBO/?key=XXXX-XXXXXX&format=xml&id=330573&season=2018

players2.xml

get
games

https://api.natstat.com/v1/games
This endpoint services all 18 competition levels. A query to this endpoint without an id parameter will return a list of all games for the competition level with their id codes, in reverse chronological order. Results can be filtered by season, sublevel, team, date, date range (start-end; last) or limit (in progress or today). Passing an id parameter will return all metadata for the game, a rundown of scoring plays, in-game score datapoints and basic play by play if available, and a summary of game forecasts (ELO probability, moneyline, spread and simulation). Please note that this endpoint can be used synonymously as game.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid game ID code, which returns details for that game. (A list of available games can be retrieved from this endpoint by not passing an ID code.)
sublevel
optional
number
A valid sublevel (leagues, conferences) ID code. A list of sublevels can be retrieved from the glossary endpoint.
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
limit
optional
string
The two valid values for this filter are =inprogress and =today.
date
optional
string
The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred..
start
optional
string
The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
end
optional
string
The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
last
optional
number
Number of days previous to today's date, to specify a date range from which to match results.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All NBA Games

https://api.natstat.com/v1/games/NBA/?key=XXXX-XXXXXX&format=xml

games.xml

NBA Games between 1/4/2017 and 1/5/2017

https://api.natstat.com/v1/games/NBA/?key=XXXX-XXXXXX&format=xml&start=20170104&end=20170105

games1.xml

Brooklyn vs. Cleveland 1/4/2014

https://api.natstat.com/v1/games/NBA/?key=XXXX-XXXXXX&format=xml&id=29828

games2.xml

get
stats

https://api.natstat.com/v1/stats
This endpoint services all 18 competition levels. A query to this endpoint with a valid type and stat parameter will return a table of statistics, in descending ranking order. Results can be filtered by season, sublevel, team or player, with an option of placing a limit on qualifiers only for player stats. Player and team stats and rankings are re-tabulated at approximately 3 am ET every night during the season. Please note that this endpoint can be used synonymously as stat.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
type
optional
string
Limit results to =player or =team.
Headers
optional
string
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
stat
required
string
A valid stat type code. A list of codes can be retrieved from the glossary endpoint.
limit
optional
string
The only valid value for this filter is =qualifiers, when used with the player type.
sublevel
optional
string
A valid sublevel (leagues, conferences) ID code. A list of sublevels can be retrieved from the glossary endpoint.
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint. The default value is the current season.
player
optional
string
A valid player ID code. A list of teams can be retrieved from the players endpoint.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

NBA Players % of Points Scored, Qualifiers only

https://api.natstat.com/v1/stats/NBA/player/?key=XXXX-XXXXXX&format=xml&stat=%PTS&limit=qualifiers

stats1.xml

MBB Teams Free Throws Attempted

https://api.natstat.com/v1/stats/MBB/team/?key=XXXX-XXXXXX&format=xml&stat=FTA

stats.xml

get
playerperfs

https://api.natstat.com/v1/playerperfs
This endpoint services all 18 competition levels. A query to this endpoint without an id parameter will return a list of all player performances for the competition level with their id codes, in reverse chronological order. Results can be filtered by season, sublevel, player, game, team, date or date range (start-end; last). Passing an id parameter will return a single performance (with no additional metadata). Please note that this endpoint can be used synonymously as playerperf.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid performance ID code, which returns details for that performance. (A list of available performances can be retrieved from this endpoint by not passing an ID code.)
sublevel
optional
number
A valid sublevel (leagues, conferences) ID code. A list of sublevels can be retrieved from the glossary endpoint.
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint.
player
optional
number
A valid player ID code. A list of teams can be retrieved from the players endpoint.
game
optional
number
A valid game ID code. A list of games can be retrieved from the games endpoint.
date
optional
string
The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
start
optional
string
The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
end
optional
string
The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
last
optional
number
Number of days previous to today's date, to specify a date range from which to match results.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All KHL Player Performances

https://api.natstat.com/v1/playerperfs/KHL/?key=XXXX-XXXXXX&format=xml

performances.xml

2016-17 Metallurg Magnitogorsk Player Performances

https://api.natstat.com/v1/playerperfs/KHL/?key=XXXX-XXXXXX&format=xml&team=5016&season=2017

performances1.xml

get
teamperfs

https://api.natstat.com/v1/teamperfs
This endpoint services all 18 competition levels. A query to this endpoint without an id parameter will return a list of all team performances for the competition level with their id codes, in reverse chronological order. Results can be filtered by season, sublevel, player, game, team, date or date range (start-end; last). Passing an id parameter will return a single performance (with no additional metadata). Please note that this endpoint can be used synonymously as teamperf.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid performance ID code, which returns details for that performance. (A list of available performances can be retrieved from this endpoint by not passing an ID code.)
sublevel
optional
string
A valid sublevel (leagues, conferences) ID code. A list of sublevels can be retrieved from the glossary endpoint.
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint.
game
optional
number
A valid game ID code. A list of games can be retrieved from the games endpoint.
date
optional
string
The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
start
optional
string
The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
end
optional
string
The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
last
optional
number
Number of days previous to today's date, to specify a date range from which to match results.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

Recent NHL Team Performances

https://api.natstat.com/v1/teamperfs/NHL/?key=XXXX-XXXXXX&format=xml

teamperfs.xml

MiLB Team Performances, within the last two days

https://api.natstat.com/v1/teamperfs/MiLB/?key=XXXX-XXXXXX&format=xml&last=2

teamperfs1.xml

get
playbyplay

https://api.natstat.com/v1/playbyplay
This endpoint currently services CBB, KBO, KHL, MBB, MB2, MB3, MHK, MiLB, MLB, NBA, NHL, NPB, WBB and WNBA. A query to this endpoint without an id parameter will return a list of all play-by-play for the competition level with their id codes, in reverse chronological order. Results can be filtered by season, player, game, team, date or date range (start-end; last). Passing an id parameter will return a single PBP entry (with no additional metadata). Please note that this endpoint can be used synonymously as pbp.
Request
Response
Path Parameters
level
required
string
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid play-by-play ID code, which returns details for that entry. (A list of available play-by-play entries can be retrieved from this endpoint by not passing an ID code.)
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint.
search
optional
string
For general search of endpoint contents. Queries of four characters or less will be ignored.
player
optional
number
A valid player ID code. A list of teams can be retrieved from the players endpoint.
game
optional
number
A valid game ID code. A list of games can be retrieved from the games endpoint.
date
optional
string
The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
start
optional
string
The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
end
optional
number
The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
last
optional
number
Number of days previous to today's date, to specify a date range from which to match results.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All MLB Play-by-Play

https://api.natstat.com/v1/playbyplay/MLB/?key=XXXX-XXXXXX&format=xml

playbyplay.xml

MLB PBP for 7/1/2016

https://api.natstat.com/v1/playbyplay/MLB/?key=XXXX-XXXXXX&format=xml&date=20160701

playbyplay1.xml

get
pitch

https://api.natstat.com/v1/pitch
This endpoint currently services MLB and MiLB. A query to this endpoint without an id parameter will return a list of all pitches for the competition level with their id codes, in reverse chronological order. Results can be filtered by season, player, game, team, date or date range (start-end; last). Passing an id parameter will return a single pitch entry (with no additional metadata). Please note that this endpoint can be used synonymously as pitchfx.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid pitch ID code, which returns details for that pitch. (A list of available pitch entries can be retrieved from this endpoint by not passing an ID code.)
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint.
search
optional
string
For general search of endpoint contents. Queries of four characters or less will be ignored.
player
optional
number
A valid player ID code. A list of teams can be retrieved from the players endpoint.
game
optional
number
A valid game ID code. A list of games can be retrieved from the games endpoint.
date
optional
string
The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
start
optional
string
The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
end
optional
string
The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
last
optional
number
Number of days previous to today's date, to specify a date range from which to match results.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

MLB Pitch Data for 8/4/2017

https://api.natstat.com/v1/pitch/MLB/?key=XXXX-XXXXXX&format=xml&date=20170804

pitch.xml

Pitch Data for Colorado vs. Arizona, 4/28/2015

https://api.natstat.com/v1/pitch/MLB/?key=XXXX-XXXXXX&format=xml&game=529691

pitch1.xml

get
officials

https://api.natstat.com/v1/officials
This endpoint currently services MBB, MB2, MB3, NBA, WNBA, MiLB and MLB. Support for WBB is limited due to poor inbound data quality, use at your own risk. A query to this endpoint without an id parameter will return a list of all officials/umpires for the competition level with their id codes. Results can be filtered by season. Passing an id parameter will return metadata for a single official/umpire, and their game record plus statistics. Results are limited to a single season; if no season parameter is passed, the current season is the default. Please note that this endpoint can be used synonymously as official, umpire and umpires.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid official ID code, which returns details for one season of that official. (A list of available officials can be retrieved from this endpoint by not passing an ID code.)
season
optional
number
A valid season ID code, formatted as the year the season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint. The default value is the current season.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All MBB Officials for 2017-18

https://api.natstat.com/v1/officials/MBB/?key=XXXX-XXXXXX&format=xml&season=2018

officials.xml

Eric Anderson (MBB Official)

https://api.natstat.com/v1/officials/MBB/?key=XXXX-XXXXXX&format=xml&id=39560

officials1.xml

get
venues

https://api.natstat.com/v1/venues
This endpoint currently services all 18 competition levels. A query to this endpoint without an id parameter will return a list of all venues for the competition level. Passing an id parameter will return metadata for a single venue, and a listing of all games played there in the course of a season. If no season parameter is passed, the current season is the default. Please note that this endpoint can be used synonymously as venue.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid venue ID code, which returns details for that venue. (A list of available venues can be retrieved from this endpoint by not passing an ID code.)
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All venues for EuroBB

https://api.natstat.com/v1/venues/EuroBB/?key=XXXX-XXXXXX&format=xml

venues.xml

Beit Maccabi

https://api.natstat.com/v1/venues/EuroBB/?key=XXXX-XXXXXX&format=xml&id=2047

venues1.html

get
elo

https://api.natstat.com/v1/elo
This endpoint currently services all 18 competition levels. A query to this endpoint without a date parameter will return the current ELO rankings and ratings for all active teams within the competition level. Passing a date parameter will return an ELO rankings and ratings "snapshot" for that date if data is available. Passing a team parameter (in conjunction with season) will return a series of data points and detailed changes in team ELO ratings over the course of the season.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint.
date
optional
string
Returns a snapshot of ELO ratings and rankings for that date. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred. Entering a date will supercede the season parameter.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

WBB ELO Rankings 2/3/2016

https://api.natstat.com/v1/elo/WBB/?key=XXXX-XXXXXX&format=xml&date=20160203

elo.xml

Mississippi State WBB ELO 2016

https://api.natstat.com/v1/elo/WBB/?key=XXXX-XXXXXX&format=xml&team=1319&season=2017

elo1.xml

get
rpi

https://api.natstat.com/v1/rpi
This endpoint currently services MBB, MB2, MB3, WBB and CBB. A query to this endpoint without a date parameter will return the current RPI rankings and ratings for all active teams within the competition level. Passing a date parameter will return an RPI rankings and ratings "snapshot" for that date if data is available. Passing a team parameter (in conjunction with season) will return a series of data points and detailed changes in team RPI ratings over the course of the season.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
season
optional
number
A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint.
date
optional
string
Returns a snapshot of RPI ratings and rankings for that date. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred. Entering a date will supercede the season parameter.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

Current CBB RPI

https://api.natstat.com/v1/rpi/CBB/?key=XXXX-XXXXXX&format=xml

rpi.xml

Kentucky CBB RPI

https://api.natstat.com/v1/rpi/CBB/?key=XXXX-XXXXXX&format=xml&team=3408

rpi1.xml

get
news

https://api.natstat.com/v1/news
This endpoint currently services all 18 competition levels. A query to this endpoint without an id parameter will return all news items in reverse chronological order. Results can be filtered by game, team, date, date range (start-end; last), and search. Passing an id parameter will return all metadata for a news item.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
number
A valid news ID code, which returns details for that news item. (A list of available news items can be retrieved from this endpoint by not passing an ID code.)
team
optional
string
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
search
optional
string
For general search of endpoint contents. Queries of four characters or less will be ignored.
game
optional
number
A valid game ID code. A list of games can be retrieved from the games endpoint.
date
optional
string
The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
start
optional
string
The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
end
optional
string
The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
last
optional
number
Number of days previous to today's date, to specify a date range from which to match results.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

MiLB Recent News

https://api.natstat.com/v1/news/MiLB/?key=XXXX-XXXXXX&format=xml

news.xml

MiLB News for 8/4/2017

https://api.natstat.com/v1/news/MiLB/?key=XXXX-XXXXXX&format=xml&date=20170804

news1.xml

get
transactions

https://api.natstat.com/v1/transactions
This endpoint currently services NBA, GL, WNBA, NHL, MLB, MiLB and MBB. A query to this endpoint without an id parameter will return all transactions in reverse chronological order. Results can be filtered by team, date, date range (start-end; last), and search. Posting an id parameter will return all metadata for a transaction.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
string
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
string
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
team
optional
string
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
date
optional
string
The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
start
optional
string
The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
end
optional
string
The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
200: OK

get
social

https://api.natstat.com/v1/social
This endpoint currently services all 18 competition levels. A query to this endpoint without an id parameter will return all social accounts in reverse chronological order of last post. Results can be filtered by team, limit (team or player accounts only) and search. Passing an id parameter (a social handle, case insensitive) will return all posts for that account in reverse chronological order. Results can be filtered by date or date range (start-end; last).
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
max
optional
number
The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block.
page
optional
number
The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned.
id
optional
string
A valid social media account handle, which returns details for that account. (A list of available accounts can be retrieved from this endpoint by not passing an ID code.) Case insensitive.
team
optional
number
A valid team ID code. A list of teams can be retrieved from the teams endpoint.
limit
optional
string
The two valid values for this filter are =team and =player, to show only social media accounts for either type.
search
optional
string
For general search of endpoint contents. Queries of four characters or less will be ignored.
player
optional
number
A valid player ID code. A list of teams can be retrieved from the players endpoint.
game
optional
number
A valid game ID code. A list of games can be retrieved from the games endpoint.
date
optional
string
The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
start
optional
string
The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
end
optional
string
The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

Golden State Warriors Social Accounts

https://api.natstat.com/v1/social/NBA/?key=XXXX-XXXXXX&format=xml&team=25

social.xml

Stephen Curry Posts

https://api.natstat.com/v1/social/NBA/?key=XXXX-XXXXXX&format=xml&id=StephenCurry30

social1.xml

All @warriors tweets from 10/4/2017 to 11/7/2017

https://api.natstat.com/v1/social/NBA/?key=XXXX-XXXXXX&format=xml&id=warriors&start=20171004&end=20171107

social2.xml

get
glossary

https://api.natstat.com/v1/glossary
This endpoint currently services all 18 competition levels. A query to this endpoint will return a list of ID codes, explanations for various metadata in the API; for example: explanations of statistical abbreviations, a level's sublevels (leagues or conferences), . Currently available types values are levels, sublevels, stats and nations. Queries to this endpoint return all data records and are not paginated.
Request
Response
Path Parameters
level
required
string
The competition level to retrieve information for. A full glossary can be found in the Path Parameters section.
type
optional
string
The data dictionary to retrieve. Acceptable values are levels, stats, nations and sublevels.
Query Parameters
key
required
string
A valid API key in XXXX-XXXXXX format.
format
optional
string
The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json.
200: OK

Examples

These are examples of properly formatted query URI's and downloadable sample API output (in XML format) from this endpoint.

All competition levels

https://api.natstat.com/v1/glossary/NBA/levels/?key=XXXX-XXXXXX&format=xml

levels.xml