usaspending

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: 8 Imported by: 0

Documentation

Overview

Package usaspending is the library behind the usaspending command line: the HTTP client, request shaping, and the typed data models for the USASpending API (https://api.usaspending.gov/api/v2).

The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public API throws under load.

Index

Constants

View Source
const BaseURL = "https://api.usaspending.gov/api/v2"

BaseURL is the root every request is built from.

View Source
const DefaultUserAgent = "usaspending-cli/0.1 (tamnd87@gmail.com)"

DefaultUserAgent identifies the client to USASpending.gov. An honest User-Agent is both polite and keeps you unblocked.

View Source
const Host = "api.usaspending.gov"

Host is the API hostname this client talks to, and the host the URI driver in domain.go claims.

Variables

This section is empty.

Functions

This section is empty.

Types

type Agency

type Agency struct {
	ID        string  `kit:"id" json:"id"`
	Name      string  `json:"name"`
	Obligated float64 `json:"obligated_amount"`
}

Agency represents a federal agency and its obligated spending.

type Award

type Award struct {
	ID             string  `kit:"id" json:"id"`
	Recipient      string  `json:"recipient"`
	AwardingAgency string  `json:"awarding_agency"`
	StartDate      string  `json:"start_date"`
	Amount         float64 `json:"amount"`
	AwardType      string  `json:"award_type"`
}

Award represents a single federal contract or grant award.

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 the USASpending API over HTTPS.

func NewClient

func NewClient() *Client

NewClient returns a Client with sensible defaults: a 30s timeout, a 300ms minimum gap between requests, and three retries on transient errors.

func (*Client) ListAgencies

func (c *Client) ListAgencies(ctx context.Context, in ListAgenciesInput) ([]*Agency, error)

ListAgencies lists federal agencies and their obligated spending via the /spending/ endpoint.

func (*Client) SearchAwards

func (c *Client) SearchAwards(ctx context.Context, in SearchAwardsInput) ([]*Award, error)

SearchAwards searches federal awards (contracts or grants) via the /search/spending_by_award/ endpoint.

func (*Client) TopRecipients

func (c *Client) TopRecipients(ctx context.Context, in TopRecipientsInput) ([]*Recipient, error)

TopRecipients returns the top spending recipients via the /search/spending_by_category/recipient/ endpoint.

type Domain

type Domain struct{}

Domain is the usaspending driver. It carries no state; the per-run client is built by the factory Register hands kit.

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) Register

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

Register installs the client factory and every operation onto app.

type ListAgenciesInput

type ListAgenciesInput struct {
	FY    string
	Limit int
}

ListAgenciesInput is the input for ListAgencies.

type Recipient

type Recipient struct {
	Name   string  `kit:"id" json:"name"`
	Amount float64 `json:"amount"`
	ID     string  `json:"id"`
}

Recipient represents a top spending recipient.

type SearchAwardsInput

type SearchAwardsInput struct {
	Agency    string
	Keyword   string
	AwardType string // "contract" or "grant"
	Year      string
	Limit     int
}

SearchAwardsInput is the input for SearchAwards.

type TopRecipientsInput

type TopRecipientsInput struct {
	Year      string
	AwardType string // "contract" or "grant"
	Limit     int
}

TopRecipientsInput is the input for TopRecipients.

Jump to

Keyboard shortcuts

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