API Overview

This section includes basic information on how to format requests to the National Statistical API, an explanation of response structures and formats, as well as basic API governance policies.

Quickstart: Authorization and Basic Requirements

Building a URI to query the National Statistical API begins with four main requirements.

First, all National Statistical API URI requests begin with this base URI:

https://api.natstat.com/v1/

Second, each valid API request requires an endpoint name. The 17 available endpoints are league, season, team, player, game, performances, playbyplay, pitchfx, officials, venues, elo, rpi, news, transactions and social. (Please note that not all sports return data for each endpoint.)

More information on endpoints and full methods can be found here.

https://api.natstat.com/v1/seasons/

Third, each valid API request requires either a level or sport path parameter passed after the API endpoint is called. More information and a glossary of codes can be found here.

https://api.natstat.com/v1/seasons/NBA/

Fourth, 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). The account's API key can be found on the National Statistical account page (requires login), located underneath the list of active subscriptions.

If you have found that your API key (or code containing the key) has been compromised, a new key can be generated easily on the National Statistical account page with one click.

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

Data Format Options

Data from the National Statistical API is available in four different formats: JSON, XML, CSV or Excel. Users can specify which format to return with the format query parameter.

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

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

CSV or Excel requests which result in errors will return empty files with no error notification. Please test any queries with JSON or XML first before using them to create spreadsheets in an automated environment. If you are receiving empty files, please try the XML or JSON options to view any applicable errors or status messages before contacting support.

Basic Response Blocks

Success

Responses in JSON and XML include a success block. If 1 is returned, the passed URI query is completely valid, and the database has been successfully queried.

If 0 is returned, more information on the reason why the request failed will be included in the error or meta block.

[success] => 1

Error

Below are common errors returned by the API. These will be contained in the error block.

AUTHORIZE_FAILED

The token is incorrect, invalid, or expired. Please refer to the account page (requires login) to check the API key.

TOO_MANY_REQUESTS

The API key has exceeded its rate limit. Please refer to information on rate limits.

NO_ENDPOINT

A valid endpoint has not been specified. Please refer to the list of endpoints for guidance.

PARAMETER_MISSING

A valid sport or level path parameter has not been specified. Please refer to the list of acceptable values.

UNAUTHORIZED

The API key has exhausted its allocation of free tokens, and the account must be upgraded to a Full Pass, Monthly Full Pass or API Plus account in order for the key to be restored.

OUT_OF_RANGE

This message occurs when the API key is not valid for the sport requested (e.g. the API key is owned by a user with a valid NBA League Pass, and the MBB endpoint is called).

UNDER_MAINTENANCE

The API is undergoing maintenance or temporary downtime. In the case of scheduled maintenance, the meta block may include details on when the service will be active again.

BLOCKED

The API key has been temporarily suspended or permanently revoked due to multiple IP access, improperly written code that affects other customers' use of the API in any way, or construction of an identical app or website that utilizes a high percentage of National Statistical's data. Please review our three-strike policies on API abuse.

Below is a sample PHP-formatted error block for an account that has exhausted its allocation of free tokens.

[error] => SimpleXMLElement Object
(
[message] => UNAUTHORIZED
[detail] => Your account does not have API access. Please refer to http://natstat.com/subscribe for subscription options.
)

Meta

The meta block is stamped with the authorized National Statistical account username attached to the API key, the date and time of the query in the US Eastern timezone, results and pagination, and it also contains data on rate limits.

All times are US Eastern.

[meta] => SimpleXMLElement Object
(
[User] => National Statistical
[Processed_At] => 2018-06-05 06:32:29
[Processing_Time] => 0.77589797973633 sec
[Time_Zone] => America/New_York
[X-RateLimit-Remaining] => 3578
[X-RateLimit-Limit] => 3600
[X-RateLimit-Reset] => 2018-06-05 07:00:04
[Max_Results] => 100
[Total_Results] => 1563
[Page] => 1
[Total_Pages] => 16
[Next_Page] => https://api.natstat.com/v1/playbyplay/WNBA/?key=XXXX-XXXXXX&format=php&last=2&page=2
[Support] => https://natstat.com/contact
[Report_Data_Errors] => https://natstat.com/contact
)

Rate Limits

All National Statistical accounts receive 100 free tokens with which to test the system. If you find it useful, you can sign up for a membership.

Monthly Full Pass or lifetime Full Pass memberships are available for normal volume API usage, or for higher capacity needs we offer API Plus annual or lifetime memberships.

Sport Pass subscribers are rate limited to 1,000 hourly requests for their authorized sport(s).

Monthly Full Pass and single-sport Monthly Pass subscribers are rate limited to 2,500 hourly requests.

Lifetime Full Pass subscribers are rate limited to 5,000 hourly requests.

API Plus annual subscribers are rate limited to 50,000 hourly requests.

API Plus lifetime subscribers are rate limited to 100,000 hourly requests.

All rate limits reset at the top of each hour.

The meta block in XML and JSON-formatted data will include information on your API key's current rate limitation status. Please review our three-strike policies on API abuse.

Header

Description

X-RateLimit-Remaining

The number of API requests allowable before the time specified in X-Rate-Limit-Reset.

X-RateLimit-Limit

The number of API requests allowable each hour.

X-RateLimit-Reset

The time (US Eastern) when the rate limit will be reset to the number in X-RateLimit-Limit.

X-RateLimit-ClientLimit

The total number of API requests available to accounts with no current API subscription. This is typically set to 100.

X-RateLimit-ClientRemaining

The number of API requests remaining for accounts with no current API subscription.

Below is a sample PHP-formatted meta block for an Full Pass subscriber authorized to access the API.

[User] => Anna Lytic
[X-RateLimit-Remaining] => 3592
[X-RateLimit-Limit] => 5000
[X-Rate-Limit-Reset] => 2018-05-27 03:00:04

Below is a sample PHP-formatted meta block for a National Statistical account holder without an API-enabled subscription.

[User] => John Sports
[X-RateLimit-ClientRemaining] => 75
[X-RateLimit-ClientLimit] => 100

API Abuse

Please note that National Statistical reserves all rights to temporarily throttle data speeds or impose additional data limits in cases of abuse, an excessive number IP addresses accessing the API simultaneously via the same key, improperly written code that affects other customers' use of the API in any way, or construction of an identical paid app or website that utilizes a high percentage of National Statistical's data in an effort to directly replicate our services.

Offending parties will be given one written warning via the email address linked to their accounts, along with a manual API key reset. On the second infraction, API keys will be revoked, access will be temporarily suspended, with the option to cancel the account with a refund issued for any and all remaining account credit. On the third infraction, API access will be permanently terminated without any further recourse or refund.