api_scrape: Scrape stats.nba.com API and return statsnbaR data

In stephematician/statsnbaR: R interface to stats.nba.com

Description

Perform a query on a recognised endpoint of stats.nba.com, and format the output as a data.frame with inferred data types for each attribute based on statsnbaR's internal YAML specifications.

Usage

api_scrape(endpoint, filters, method = NULL, ...)

Arguments

endpoint	Character string which identifies the statsnbaR endpoint
filters	Named list of statsnbaR key-value filters for the query
method	Optional user-supplied function to retrieve JSON from stats.nba.com

Details

The endpoints, data types returned and filter specifications are given in the internal YAML which is available on https://www.github.com/stephematician/statsnbaR/tree/master/data-raw/ADL.yaml

The YAML specifies four main things, the;

• host (stats.nba.com);

• names of accepted filters and their mappings to stats.nba.com;

• result data conversion parameters (such as class or mapping); and

• the endpoint APIs, what filters they accept and what data they should return.

How the last three items are specified is briefly described in the following sections.

Value

A list of data.frames of the resultSets returned by stats.nba.com with inferred data types.

‘statsnbaR filters’ YAML

filters  :
    league :
        mapping : {
            NBA      : "00",    # NBA
            D-league : "20"     # D-League
            }
        default : NBA

This is hopefully fairly self-explanatory:

• The mapping is from values that statsnbaR uses internally such as NBA, to the value that stats.nba.com expects.

• Default values are specified for each filter.

‘statsnbaR datatype’ YAML

The desired properties of the returned data types and/or a way to map them to desired types is specified in the YAML in a fashion similar to the following example:

data    :
    person_id :
        class   : numeric
  &active roster_status :
       class   : logical
       mapping : {
           0 : FALSE,    # not active
           1 : TRUE      # active player
           }

Things to note are:

• The class of the data-type will refer to a specific type converter from type_converters.

• THe mapping for a data type may not guarantee the correct type and so the type converter is employed after the mapping.

End-point YAML

The endpoint defined in the YAML might look like

endpoints :
    PlayerCommon :
        api.name     : "commonallplayers"
        api.path     : "stats"
        api.referrer : "http://stats.nba.com/players"
        api.filters  :
            league       : "LeagueID"
        api.results :
            CommonAllPlayers : {
                person_id    : "person_id",
                }

• The first three items under PlayerCommon are passed to httr::GET.

• The api.filters item is a mapping from filter names that statsnbaR uses internally to filter names that the stats.nba.com endpoint uses.

• The api.results item maps the attribute names of the data returned by stats.nba.com to names that statsnbaR uses internally. see the section ‘Data specification YAML’.

stephematician/statsnbaR documentation built on May 30, 2019, 3:17 p.m.