Title: Access the U.S. National Provider Identifier Registry API
Version: 0.2.0
Description: Access the United States National Provider Identifier Registry API https://npiregistry.cms.hhs.gov/api/. Obtain and transform administrative data linked to a specific individual or organizational healthcare provider, or perform advanced searches based on provider name, location, type of service, credentials, and other attributes exposed by the API.
License: MIT + file LICENSE
URL: https://github.com/ropensci/npi/, https://docs.ropensci.org/npi/, https://npiregistry.cms.hhs.gov/api/
BugReports: https://github.com/ropensci/npi/issues/
Depends: R (≥ 3.1)
Imports: checkLuhn, checkmate, curl, dplyr, glue, httr, magrittr, purrr, rlang, stringr, tibble, tidyr, utils
Suggests: covr, httptest, knitr, mockery, rmarkdown, spelling, testthat (≥ 2.1.0)
VignetteBuilder: knitr
Encoding: UTF-8
Language: en-US
LazyData: true
RoxygenNote: 7.2.1
NeedsCompilation: no
Packaged: 2022-11-11 16:09:38 UTC; frank
Author: Frank Farach ORCID iD [cre, aut, cph], Sam Parmar [ctb], Matthias Grenié ORCID iD [rev], Emily C. Zabor ORCID iD [rev]
Maintainer: Frank Farach <frank.farach@gmail.com>
Repository: CRAN
Date/Publication: 2022-11-14 11:30:02 UTC

npi: Access the U.S. National Provider Identifier Registry API

Description

logo

Access the United States National Provider Identifier Registry API https://npiregistry.cms.hhs.gov/api/. Obtain and transform administrative data linked to a specific individual or organizational healthcare provider, or perform advanced searches based on provider name, location, type of service, credentials, and other attributes exposed by the API.

Details

npi makes it easy to search and work with data from the U.S. National Provider Identifier (NPI) Registry API (v2.1) directly from R. Obtain rich administrative data linked to a specific individual or organizational healthcare provider, or perform advanced searches based on provider name, location, type of service, credentials, and many other attributes. npi provides convenience functions for data extraction so you can spend less time wrangling data and more time putting data to work.

There are three functions you're likely to need from this package. The first is npi_search, which allows you to query the NPI Registry and returns up to 1,200 full NPI records as a data frame (tibble). Next, you can use npi_summarize on these results to obtain a human-readable summary of each record. Finally, npi_flatten extracts and flattens conceptually-related subsets of data into a tibble that are joined by the 'npi' column into an analysis-ready object.

Package options

npi's default user agent is the URL of the package's GitHub repository, https://github.com/ropensci/npi. You can customize it by setting the npi_user_agent option:

options(npi_user_agent = "your_user_agent_here")

Author(s)

Maintainer: Frank Farach frank.farach@gmail.com (ORCID) [copyright holder]

Other contributors:

See Also

Useful links:

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling 'rhs(lhs)'.

Construct an npi_results S3 object

Description

Creates an npi_results S3 object from a tibble. See validate_npi_results for other requirements for this class.

Usage

new_npi_results(x, ...)

Arguments

x

A tibble

Value

A tibble with S3 class npi_results

S3 method to flatten an npi_results object

Description

S3 method to flatten an npi_results object

Usage

npi_flatten(df, cols, key)

Arguments

df

A data frame containing the results of a call to npi_search.

cols

If non-NULL, only the named columns specified here will be be flattened and returned along with npi.

key

A quoted column name from df to use as a matching key. The default value is "npi".

Value

A data frame (tibble) with flattened list columns.

Examples

# Flatten all list columns
data(npis)
npi_flatten(npis)

# Only flatten specified columns
npi_flatten(npis, cols = c("basic", "identifiers"))

Flatten NPI search results

Description

This function takes an npi_results S3 object returned by npi_search and flattens its list columns. It unnests the lists columns and left joins them by npi. You can optionally specify which columns from df to include.

Usage

## S3 method for class 'npi_results'
npi_flatten(df, cols = NULL, key = "npi")

Arguments

df

A data frame containing the results of a call to npi_search.

cols

If non-NULL, only the named columns specified here will be be flattened and returned along with npi.

key

A quoted column name from df to use as a matching key. The default value is "npi".

Details

The names of unnested columns are prefixed by the name of their originating list column to avoid name clashes and show their lineage. List columns containing all NULL data will be absent from the result because there are no columns to unnest.

Value

A data frame (tibble) with flattened list columns.

Examples

# Flatten all list columns
data(npis)
npi_flatten(npis)

# Only flatten specified columns
npi_flatten(npis, cols = c("basic", "identifiers"))

Check if candidate NPI number is valid

Description

Check whether a number is a valid NPI number per the specifications detailed in the Final Rule for the Standard Unique Health Identifier for Health Care Providers (69 FR 3434).

Usage

npi_is_valid(x)

Arguments

x

10-digit candidate NPI number

Value

Boolean indicating whether npi is valid

Examples

npi_is_valid(1234567893) # TRUE
npi_is_valid(1234567898) # FALSE

Description

Search the U.S. National Provider Identifier (NPI) Registry using parameters exposed by the registry's API (Version 2.1). Results are combined and returned as a tibble with an S3 class of npi_results. See Value below for a description of the returned object.

Usage

npi_search(
  number = NULL,
  enumeration_type = NULL,
  taxonomy_description = NULL,
  first_name = NULL,
  last_name = NULL,
  use_first_name_alias = NULL,
  organization_name = NULL,
  address_purpose = NULL,
  city = NULL,
  state = NULL,
  postal_code = NULL,
  country_code = NULL,
  limit = 10L
)

Arguments

number

(Optional) 10-digit NPI number assigned to the provider.

enumeration_type

(Optional) Type of provider associated with the NPI, one of:

"ind"

Individual provider (NPI-1)

"org"

Organizational provider (NPI-2)

taxonomy_description

(Optional) Scalar character vector with a taxonomy description or code from the NUCC Healthcare Provider Taxonomy.

first_name

(Optional) This field only applies to Individual Providers. Trailing wildcard entries are permitted requiring at least two characters to be entered (e.g. "jo*" ). This field allows the following special characters: ampersand, apostrophe, colon, comma, forward slash, hyphen, left and right parentheses, period, pound sign, quotation mark, and semi-colon.

last_name

(Optional) This field only applies to Individual Providers. Trailing wildcard entries are permitted requiring at least two characters to be entered. This field allows the following special characters: ampersand, apostrophe, colon, comma, forward slash, hyphen, left and right parentheses, period, pound sign, quotation mark, and semi-colon.

use_first_name_alias

(Optional) This field only applies to Individual Providers when not doing a wildcard search. When set to "True", the search results will include Providers with similar First Names. E.g., first_name=Robert, will also return Providers with the first name of Rob, Bob, Robbie, Bobby, etc. Valid Values are: TRUE: Will include alias/similar names; FALSE: Will only look for exact matches.

organization_name

(Optional) This field only applies to Organizational Providers. Trailing wildcard entries are permitted requiring at least two characters to be entered. This field allows the following special characters: ampersand, apostrophe, "at" sign, colon, comma, forward slash, hyphen, left and right parentheses, period, pound sign, quotation mark, and semi-colon. Both the Organization Name and Other Organization Name fields associated with an NPI are examined for matching contents, therefore, the results might contain an organization name different from the one entered in the Organization Name criterion.

address_purpose

Refers to whether the address information entered pertains to the provider's Mailing Address or the provider's Practice Location Address. When not specified, the results will contain the providers where either the Mailing Address or any of Practice Location Addresses match the entered address information. Primary will only search against Primary Location Address. While Secondary will only search against Secondary Location Addresses. Valid values are: "location", "mailing", "primary", "secondary".

city

The City associated with the provider's address identified in Address Purpose. To search for a Military Address enter either APO or FPO into the City field. This field allows the following special characters: ampersand, apostrophe, colon, comma, forward slash, hyphen, left and right parentheses, period, pound sign, quotation mark, and semi-colon.

state

The State abbreviation associated with the provider's address identified in Address Purpose. This field cannot be used as the only input criterion. If this field is used, at least one other field, besides the Enumeration Type and Country, must be populated. Valid values for states: https://npiregistry.cms.hhs.gov/registry/API-State-Abbr

postal_code

The Postal Code associated with the provider's address identified in Address Purpose. If you enter a 5 digit postal code, it will match any appropriate 9 digit (zip+4) codes in the data. Trailing wildcard entries are permitted requiring at least two characters to be entered (e.g., "21*").

country_code

The Country associated with the provider's address identified in Address Purpose. This field can be used as the only input criterion as long as the value selected is not US (United States). Valid values for country codes: https://npiregistry.cms.hhs.gov/registry/API-Country-Abbr

limit

Maximum number of records to return, from 1 to 1200 inclusive. The default is 10. Because the API returns up to 200 records per request, values of limit greater than 200 will result in multiple API calls.

Details

By default, the function requests up to 10 records, but the limit argument accepts values from 1 to the API's limit of 1200.

Value

Data frame (tibble) containing the results of the search.

References

https://npiregistry.cms.hhs.gov/registry/help-api Data dictionary for fields returned

NUCC Healthcare Provider Taxonomy

Examples

## Not run: 
# 10 NPI records for New York City
npi_search(city = "New York City")

# 1O NPI records for New York City, organizations only
npi_search(city = "New York City", enumeration_type = "org")

# 1O NPI records for New York City, individuals only
npi_search(city = "New York City", enumeration_type = "ind")

# 1200 NPI records for New York City
npi_search(city = "New York City", limit = 1200)

# Nutritionists in Maine
npi_search(state = "ME", taxonomy_description = "Nutritionist")

# Record associated with NPI 1245251222
npi_search(number = 1245251222)

## End(Not run)

S3 method to summarize an npi_results object

Description

S3 method to summarize an npi_results object

Usage

npi_summarize(object, ...)

Arguments

object

An npi_results S3 object

...

Additional optional arguments

Value

Tibble containing the following columns:

npi

National Provider Identifier (NPI) number

name

Provider's first and last name for individual providers, organization name for organizational providers.

enumeration_type

Type of provider associated with the NPI, either "Individual" or "Organizational"

primary_practice_address

Full address of the provider's primary practice location

phone

Provider's telephone number

primary_taxonomy

Primary taxonomy description

Examples

data(npis)
npi_summarize(npis)

Summary method for npi_results S3 object

Description

Print a human-readable overview of each record return in the results from a call to npi_search. The format of the summary is modeled after the one offered on the NPI registry website.

Usage

## S3 method for class 'npi_results'
npi_summarize(object, ...)

Arguments

object

An npi_results S3 object

...

Additional optional arguments

Value

Tibble containing the following columns:

npi

National Provider Identifier (NPI) number

name

Provider's first and last name for individual providers, organization name for organizational providers.

enumeration_type

Type of provider associated with the NPI, either "Individual" or "Organizational"

primary_practice_address

Full address of the provider's primary practice location

phone

Provider's telephone number

primary_taxonomy

Primary taxonomy description

Examples

data(npis)
npi_summarize(npis)

Sample results from the NPI Registry

Description

A dataset containing 10 records returned from an NPI Registry search for providers with a primary address in New York City.

Usage

npis

Format

A tibble with 10 rows and 11 columns, organized as follows:

npi

[integer] 10-digit National Provider Identifier number

enumeration_type

[character] Type of provider NPI, either "Individual" or "Organizational".

basic

[list of 1 tibble] Basic information about the provider.

other_names

[list of tibbles] Other names the provider goes by.

identifiers

[list of tibbles] Other identifiers linked to the NPI.

taxonomies

[list of tibbles] Healthcare Provider Taxonomy classification.

addresses

[list of tibbles] Addresses for the provider's primary practice location and primary mailing address.

practice_locations

[list of tibbles] Addresses for the provider's other practice locations.

endpoints

[list of tibbles] Details about provider's endpoints for health information exchange.

created_date

[datetime] Date NPI record was first created (UTC).

last_updated_date

[datetime] UTC timestamp of the last time the NPI record was updated.

Details

search_npi(city = "New York City", limit = 10)

Source

https://npiregistry.cms.hhs.gov/registry/help-api

Validate input as S3 npi_results object

Description

Accepts an object, x, and determines whether it meets the criteria to be an S3 npi_results S3 object. The criteria include tests for data types, column names, and class attributes. They are intentionally strict to provide a contract to functions that interact with it.

Usage

validate_npi_results(x, ...)

See Also

new_npi_results