Query Parameters

This section describes parameters that may be sent to the National Statistical API attached to the URI in [?&]param=value format. Query parameters are optional except for the API key.

Required Parameters

key

Each valid API request requires the inclusion of a valid API key as a query parameter. A key contains 11 characters (four alphanumeric characters, a dash, then six alphanumeric characters). Your account's current API key can be found on the National Statistical account page (requires login), located underneath the list of active subscriptions.

https://api.natstat.com/v1/seasons/MLB/?key=XXXX-XXXXXX

If no key is specified, an AUTHORIZE_FAILED error will be returned. If an invalid key is specified, a UNAUTHORIZED error will be returned.

Output Parameters

format

Data from the National Statistical API is available in four different formats: JSON, XML, or PHP array formatted as a SimpleXML object. Users can specify which format to return with the format query parameter.

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

If no data format is specified, the API will send JSON-formatted data by default.

max

The number of max results per page. The default is 100, and the maximum allowed is 1000.

https://api.natstat.com/v1/playerperfs/MiLB/?key=XXXX-XXXXXX&season=2017&max=5

page

The subset of results within pagination as a numbered page. If there are more than the results specified in max (or 100 as default), the URL for the next page will be included in the meta block.

https://api.natstat.com/v1/games/WBB/?key=XXXX-XXXXXX&season=2018&page=2

Focus Parameters

id

Specifying an id will return all available information regarding a single data record. With most endpoints, not specifying an id will result in an overview list of available records that will contain valid id codes.

https://api.natstat.com/v1/seasons/WBB/?key=XXXX-XXXXXX&id=2018

This parameter is valid for the following endpoints: seasons, teams, players, games, playerperfs, teamperfs, playbyplay, pitchfx, officials, venues, news, social.

sublevel

A sublevel is a league within a competition level (for competition levels like AmerBB, EuroBB and MiLB) where teams do not or rarely play outside of its sublevel. Sublevels are three- to five- letter abbreviation codes.

A list of sublevels can be retrieved from the seasons endpoint; pass a valid season to view all available sublevel codes for that season.

https://api.natstat.com/v1/games/MiLB/?key=XXXX-XXXXXX&sublevel=INT&format=php

This parameter is valid for the following endpoints: seasons (when id is also present), games, playerperfs, teamperfs.

team

A numeric code representing a team. Each team id number is unique and not replicable across competition levels. A list of team id numbers can be retrieved from the teams endpoint.

https://api.natstat.com/v1/playerperfs/WNBA/?key=XXXX-XXXXXX&team=980

This parameter is valid for the following endpoints: games, playerperfs, teamperfs, playbyplay, pitchfx, elo, rpi, news, social.

season

A numeric code representing a season, in the format of the YYYY year that the season concludes in. A list of season id numbers can be retrieved from the seasons endpoint.

https://api.natstat.com/v1/games/WBB/?key=XXXX-XXXXXX&season=2016

This parameter is valid for the following endpoints: teams, players, playerperfs, teamperfs, playbyplay, pitchfx, officials, elo, rpi.

limit

Used to return a very small predefined subset of results.

https://api.natstat.com/v1/games/KBO/?key=XXXX-XXXXXX&limit=today

This parameter is valid for the following endpoints: games (=inprogress and =today), social (=team and =player), stats (=qualifiers).

stat

Returns results for a certain team or player stat. A list of valid stat codes can be retrieved from the glossary endpoint.

https://api.natstat.com/v1/games/KBO/?key=XXXX-XXXXXX&limit=today

This parameter is valid and always required when using the following endpoint: stats.

A text string to query endpoint contents. Search strings shorter than four characters are ignored. Search results are returned in order of descending relevance to the query.

https://api.natstat.com/v1/news/MLB/?key=XXXX-XXXXXX&search=new%20york%20mets

This parameter is valid for the following endpoints: teams, players, games, playbyplay, pitchfx, news, social.

player

A numeric code representing a player. Each player id number is unique and is not replicable across competition levels. A list of player id numbers can be retrieved from the players endpoint.

https://api.natstat.com/v1/seasons/MLB/?key=XXXX-XXXXXX&player=10898

This parameter is valid for the following endpoints: playerperfs, teamperfs, playbyplay, pitchfx, social.

game

A numeric code representing a game. Game id numbers are not unique and may be not replicable across competition levels. A list of game id numbers can be retrieved from the games endpoint.

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

This parameter is valid for the following endpoints: playerperfs, teamperfs, playbyplay, pitchfx, news, social.

Time Parameters

date

Will limit results to a single date. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.

https://api.natstat.com/v1/elo/AsiaBB/?key=XXXX-XXXXXX&date=20180104

This parameter is valid for the following endpoints: games, playerperfs, teamperfs, playbyplay, pitchfx, elo, rpi, news, social.

start

The date to begin a timeframe with which to limit results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.

https://api.natstat.com/v1/playerperfs/NHL/?key=XXXX-XXXXXX&start=20180102&end=20180104

This parameter is valid for the following endpoints: games, playerperfs, teamperfs, playbyplay, pitchfx, news, social.

end

The date to end a timeframe with which to limit results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred.

https://api.natstat.com/v1/playbyplay/KHL/?key=XXXX-XXXXXX&start=20171221&end=20171223

This parameter is valid for the following endpoints: games, playerperfs, teamperfs, playbyplay, pitchfx, news, social.

last

Number of days previous to today's date, to specify a date range from which to match results.

https://api.natstat.com/v1/playbyplay/WNBA/?key=XXXX-XXXXXX&last=2

This parameter is valid for the following endpoints: games, playerperfs, teamperfs, playbyplay, pitchfx, news, social.