usda

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 14, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package usda is the library behind the usda command line: the HTTP client, request shaping, and typed data models for the USDA FoodData Central API (api.nal.usda.gov/fdc).

Use the DEMO_KEY (default) or supply your own API key via Config.APIKey. DEMO_KEY is rate-limited to 30 requests per hour per IP; the default Rate of 3 seconds keeps a typical interactive session well clear of that limit.

Index

Constants

View Source
const DefaultAPIKey = "DEMO_KEY"

DefaultAPIKey is the USDA demo key, rate-limited to 30 req/hour per IP.

View Source
const DefaultBaseURL = "https://api.nal.usda.gov/fdc"

DefaultBaseURL is the root every request is built from.

View Source
const DefaultUserAgent = "usda/dev (+https://github.com/tamnd/usda-cli)"

DefaultUserAgent identifies the client to the USDA FDC API.

View Source
const Host = "api.nal.usda.gov"

Host is the API hostname; the URI driver in domain.go claims it.

Variables

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound is returned when the API returns 404 for a food ID.

Functions

This section is empty.

Types

type Client

type Client struct {
	HTTP      *http.Client
	UserAgent string
	// Rate is the minimum gap between requests. Zero means no pacing.
	Rate    time.Duration
	Retries int
	// contains filtered or unexported fields
}

Client talks to api.nal.usda.gov over HTTP.

func NewClient

func NewClient() *Client

NewClient returns a Client with sensible defaults.

func (*Client) Food

func (c *Client) Food(ctx context.Context, fdcID int) (*Food, error)

Food returns the full detail for a single food by its FDC ID.

func (*Client) Get

func (c *Client) Get(ctx context.Context, rawURL string) ([]byte, error)

Get fetches rawURL and returns the body bytes. It paces and retries.

func (*Client) List

func (c *Client) List(ctx context.Context, dataType string, limit int) ([]*Food, error)

List lists foods of a given data type. dataType filters by data type (e.g. "Foundation"); empty means all. limit 0 uses the API default of 25.

func (*Client) Search

func (c *Client) Search(ctx context.Context, query, dataType string, limit int) ([]*Food, error)

Search searches the FoodData Central for foods matching query. dataType filters by data type (e.g. "Foundation", "SR Legacy", ""); empty means all. limit 0 uses the API default of 25.

type Config

type Config struct {
	BaseURL   string
	APIKey    string
	UserAgent string
	Rate      time.Duration
	Retries   int
	Timeout   time.Duration
}

Config holds constructor parameters.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns sensible defaults.

type Domain

type Domain struct{}

Domain is the usda driver.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns an FDC ID or usda URL into a (type, id) pair.

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Food

type Food struct {
	ID          int        `json:"id"`
	Description string     `json:"description"`
	DataType    string     `json:"data_type,omitempty"`
	BrandOwner  string     `json:"brand_owner,omitempty"`
	Nutrients   []Nutrient `json:"nutrients,omitempty"`
}

Food is the record type emitted by all commands.

type Nutrient

type Nutrient struct {
	Name  string  `json:"name"`
	Unit  string  `json:"unit"`
	Value float64 `json:"value"`
}

Nutrient is a single nutrient entry within a Food.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL