NPI Registry Go Client

A Go library for querying the NPI Registry (National Plan and Provider Enumeration System). Look up healthcare providers by their NPI (National Provider Identifier) number using the official CMS registry API.

Installation

go get github.com/jjenkins/npi

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/jjenkins/npi"
)

func main() {
    registry := npi.New()
    provider, err := registry.Lookup(1245243567)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Provider: %s %s, %s\n",
        provider.Provider.FirstName,
        provider.Provider.LastName,
        provider.Provider.Credential)
}

Usage Examples

Basic Lookup

registry := npi.New()
result, err := registry.Lookup(1245243567)
if err != nil {
    log.Printf("Lookup failed: %v", err)
    return
}

fmt.Printf("NPI Number: %d\n", result.Number)
fmt.Printf("Enumeration Type: %s\n", result.EnumerationType)

Accessing Provider Information

The Provider field contains details about the healthcare provider:

registry := npi.New()
result, err := registry.Lookup(1245243567)
if err != nil {
    log.Fatal(err)
}

p := result.Provider

// Full name with credentials
fmt.Printf("Name: %s %s %s, %s\n",
    p.NamePrefix,      // e.g., "DR."
    p.FirstName,       // e.g., "CHARLES"
    p.LastName,        // e.g., "HANSON"
    p.Credential)      // e.g., "M.D."

// Additional details
fmt.Printf("Gender: %s\n", p.Gender)              // "M" or "F"
fmt.Printf("Status: %s\n", p.Status)              // "A" for active
fmt.Printf("Sole Proprietor: %s\n", p.SoleProprietor)
fmt.Printf("Enumeration Date: %s\n", p.EnumerationDate)
fmt.Printf("Last Updated: %s\n", p.LastUpdated)

Working with Addresses

Providers may have multiple addresses (location and mailing):

registry := npi.New()
result, err := registry.Lookup(1245243567)
if err != nil {
    log.Fatal(err)
}

for _, addr := range result.Addresses {
    fmt.Printf("\n%s Address:\n", addr.AddressPurpose) // "LOCATION" or "MAILING"
    fmt.Printf("  %s\n", addr.Address1)
    if addr.Address2 != "" {
        fmt.Printf("  %s\n", addr.Address2)
    }
    fmt.Printf("  %s, %s %s\n", addr.City, addr.State, addr.PostalCode)
    fmt.Printf("  %s\n", addr.CountryName)
    fmt.Printf("  Phone: %s\n", addr.TelephoneNumber)
    if addr.FaxNumber != "" {
        fmt.Printf("  Fax: %s\n", addr.FaxNumber)
    }
}

Working with Taxonomies

Taxonomies describe the services a provider offers:

registry := npi.New()
result, err := registry.Lookup(1245243567)
if err != nil {
    log.Fatal(err)
}

for _, tax := range result.Taxonomies {
    primary := ""
    if tax.Primary {
        primary = " (Primary)"
    }
    fmt.Printf("Specialty: %s%s\n", tax.Description, primary)
    fmt.Printf("  Code: %s\n", tax.Code)
    fmt.Printf("  License: %s (%s)\n", tax.License, tax.State)
}

Finding the Primary Taxonomy

func getPrimaryTaxonomy(result *npi.NPI) *npi.Taxonomy {
    for _, tax := range result.Taxonomies {
        if tax.Primary {
            return tax
        }
    }
    return nil
}

registry := npi.New()
result, err := registry.Lookup(1245243567)
if err != nil {
    log.Fatal(err)
}

if primary := getPrimaryTaxonomy(result); primary != nil {
    fmt.Printf("Primary Specialty: %s\n", primary.Description)
}

Finding Location Address

func getLocationAddress(result *npi.NPI) *npi.Address {
    for _, addr := range result.Addresses {
        if addr.AddressPurpose == "LOCATION" {
            return addr
        }
    }
    return nil
}

registry := npi.New()
result, err := registry.Lookup(1245243567)
if err != nil {
    log.Fatal(err)
}

if loc := getLocationAddress(result); loc != nil {
    fmt.Printf("Practice Location: %s, %s\n", loc.City, loc.State)
}

Complete Example

package main

import (
    "fmt"
    "log"

    "github.com/jjenkins/npi"
)

func main() {
    registry := npi.New()
    result, err := registry.Lookup(1245243567)
    if err != nil {
        log.Fatalf("Failed to lookup NPI: %v", err)
    }

    // Provider info
    p := result.Provider
    fmt.Println("=== Provider Information ===")
    fmt.Printf("NPI: %d\n", result.Number)
    fmt.Printf("Name: %s %s %s, %s\n",
        p.NamePrefix, p.FirstName, p.LastName, p.Credential)
    fmt.Printf("Status: %s\n", p.Status)
    fmt.Printf("Type: %s\n", result.EnumerationType)

    // Primary specialty
    fmt.Println("\n=== Specialties ===")
    for _, tax := range result.Taxonomies {
        marker := "  "
        if tax.Primary {
            marker = "* "
        }
        fmt.Printf("%s%s (Code: %s)\n", marker, tax.Description, tax.Code)
    }

    // Addresses
    fmt.Println("\n=== Addresses ===")
    for _, addr := range result.Addresses {
        fmt.Printf("[%s]\n", addr.AddressPurpose)
        fmt.Printf("  %s\n", addr.Address1)
        if addr.Address2 != "" {
            fmt.Printf("  %s\n", addr.Address2)
        }
        fmt.Printf("  %s, %s %s\n", addr.City, addr.State, addr.PostalCode)
        fmt.Printf("  Tel: %s\n", addr.TelephoneNumber)
    }
}

API Reference

Types

Registry

The client for making NPI lookups.

registry := npi.New()

NPI

Represents a National Provider Identifier record.

Field	Type	Description
Number	int	The 10-digit NPI number
EnumerationType	string	"NPI-1" (individual) or "NPI-2" (organization)
Provider	*Provider	Basic provider information
Addresses	[]*Address	Location and mailing addresses
Taxonomies	[]*Taxonomy	Service categories
CreatedEpoch	int	Unix timestamp when record was created
LastUpdatedEpoch	int	Unix timestamp when record was last updated

Provider

Healthcare provider details.

Field	Type	Description
FirstName	string	Provider's first name
LastName	string	Provider's last name
MiddleName	string	Provider's middle name
NamePrefix	string	Title (e.g., "DR.")
NameSuffix	string	Suffix (e.g., "JR.")
Credential	string	Professional credential (e.g., "M.D.")
Gender	string	"M" or "F"
Status	string	"A" for active
SoleProprietor	string	"YES" or "NO"
EnumerationDate	string	Date NPI was assigned
LastUpdated	string	Date of last update

Address

Provider address information.

Field	Type	Description
AddressPurpose	string	"LOCATION" or "MAILING"
AddressType	string	Address type code
Address1	string	Street address line 1
Address2	string	Street address line 2
City	string	City name
State	string	State abbreviation
PostalCode	string	ZIP code
CountryCode	string	Country code (e.g., "US")
CountryName	string	Country name
TelephoneNumber	string	Phone number
FaxNumber	string	Fax number

Taxonomy

Service category information.

Field	Type	Description
Code	string	Taxonomy code
Description	string	Human-readable specialty name
Primary	bool	Whether this is the primary taxonomy
License	string	State license number
State	string	State of licensure

Error Handling

The Lookup method returns an error in these cases:

• NPI number not found in the registry
• Non-200 HTTP response from the API

registry := npi.New()
result, err := registry.Lookup(0000000000)
if err != nil {
    // err.Error() == "Couldn't find NPI recording with 0000000000"
    log.Printf("Lookup failed: %v", err)
}

Testing

# Run all tests
go test -v ./...

# Run tests with coverage
go test -cover ./...

License

MIT License