blsgo

README

bls-go

bls-go is a Go interface for the public API provided by the United States Bureau of Labor Statistics.

Requirements

• Go
• BLS.gov API key (not strictly required, but highly recommended; you can request one here)

Installation

After cloning the repository, build and install the library with go install github.com/clpo13/bls-go. See the Usage section for how to interact with the library.

Alternatively, you can call go get -u github.com/clpo13/bls-go to fetch and install the latest version of the library directly to your GOPATH.

Usage

In your import statement, add "github.com/clpo13/bls-go". Now, you have access to blsgo.GetData, blsgo.Payload, and blsgo.ResultData, as well as a few other helper structs and functions. Run go doc github.com/clpo13/bls-go to get some basic information on the available objects. The generated API docs can also be found at https://godoc.org/github.com/clpo13/bls-go.

More detailed usage notes coming soon.

An example program using this library can be found at https://github.com/clpo13/bls-go-example.

Contributing

Issues and pull requests are always welcome. Please file any bug reports or feature requests using the GitHub issues page.

To do list

• Better error handling, especially when an invalid series is requested
• Online API docs
• Usage notes and example code

License

This program is available under the terms of the Apache 2.0 license, the text of which can be found in LICENSE or at https://www.apache.org/licenses/LICENSE-2.0.

Documentation

Overview

Package blsgo is a Go interface for getting and parsing data from the BLS.gov API.

Index

• type Calculation
• type Catalog
• type Change
• type DataError
  • func (e *DataError) Error() string
• type Footnote
• type Payload
• type Period
  • func Reverse(a []Period) []Period
• type ResultData
  • func GetData(payload Payload) (ResultData, error)
• type Series
• type SeriesData

Types

type Calculation

type Calculation struct {
	NetChange Change `json:"net_changes"`
	PctChange Change `json:"pct_changes"`
}

Calculation represents net and percent change calculations sent with the received data.

type Catalog

type Catalog struct {
	Title    string `json:"series_title"`
	ID       string `json:"series_id"`
	Season   string `json:"seasonality"`
	Name     string `json:"survey_name"`
	Abbr     string `json:"survey_abbreviation"`
	DataType string `json:"measure_data_type"`
	Area     string `json:"area"`
	AreaType string `json:"area_type"`
}

Catalog represents the catalog data of a series.

type Change

type Change struct {
	OneMonth    string `json:"1"`
	ThreeMonth  string `json:"3"`
	SixMonth    string `json:"6"`
	TwelveMonth string `json:"12"`
}

Change represents calculations of change over 1, 3, 6, and 12 months.

type DataError

type DataError struct {
	Msg     string
	Details []string
}

DataError is an error object that contains messages sent by the server.

func (*DataError) Error

func (e *DataError) Error() string

type Footnote

type Footnote struct {
	Code *string `json:"code,omitempty"`
	Text *string `json:"text,omitempty"`
}

Footnote represents a footnote sent with the received data.

type Payload

type Payload struct {
	Start   string   `json:"startyear"`
	End     string   `json:"endyear"`
	Series  []string `json:"seriesid"`
	Catalog bool     `json:"catalog,omitempty"`
	Calc    bool     `json:"calculations,omitempty"`
	Avg     bool     `json:"annualaverage,omitempty"`
	Key     string   `json:"registrationkey,omitempty"`
}

Payload defines the structure of data to be sent to the API endpoint. The start year, end year, and series ID are required, but other fields are optional. Catalog, Calc, and Avg have no effect if an API key is not also sent.

type Period

type Period struct {
	Year         string       `json:"year"`
	Num          string       `json:"period"`
	Name         string       `json:"periodName"`
	Value        string       `json:"value"`
	Footnotes    []Footnote   `json:"footnotes"`
	Calculations *Calculation `json:"calculations,omitempty"`
}

Period represents an individual period (usually a month) of data.

func Reverse

func Reverse(a []Period) []Period

Reverse takes an array of Periods and reverses it. This can be useful as the API returns data in descending order.

type ResultData

type ResultData struct {
	Status       string   `json:"status"`
	ResponseTime int      `json:"responseTime"`
	Message      []string `json:"message"`
	Results      Series   `json:"Results"`
}

ResultData represents the top-level structure of the received data, including the response status and messages sent by the server.

func GetData

func GetData(payload Payload) (ResultData, error)

GetData takes a Payload, converts it to JSON, and sends it to the specified API endpoint. It returns a ResultData object that contains all the received data for the given Payload. TODO: return errors in an object instead of logging

type Series

type Series struct {
	Series []SeriesData `json:"series"`
}

Series represents an array of series.

type SeriesData

type SeriesData struct {
	SeriesID string   `json:"seriesID"`
	Catalog  *Catalog `json:"catalog,omitempty"`
	Data     []Period `json:"data"`
}

SeriesData represents data from a single series.