BlsData

A third-party Julia library to pull data from the Bureau of Labor Statistics (BLS).

	Does this thing work?
Documentation	<this page, for now>
Package Evaluator
Build Status

Setup

julia> Pkg.add("BlsData")

BlsData uses BLS's Public Data API. This API limits the number of requests that unauthenticated users can make each day. To increase these limits, register a Public Data API account on the BLS website here to receive an API key.

Make the BLS Public Data API key that you just registered accessible to BlsData by storing it in a file. Then, your API key will be automatically detected by the package.

julia> open(joinpath(homedir(), ".blsdatarc"), "w") do f
           write(f, "0123456789abcdef0123456789abcdef")
       end

Usage

Download civilian labor force level data:

using BlsData
b = Bls()
result = get_data(b, "LNS11000000")

Then, access the DataFrame using result.data.

Functionality

The Bls type

The Bls type represents a connection to the BLS API.

Looks for a registration key in the file ~/.blsdatarc, or omits the registration key otherwise.

b = Bls()

Specify a registration key directly.

b = Bls(key="0123456789abcdef0123456789abcdef")

Get and set fields.

get_api_url(b::Bls)                       # Get the base URL used to connect to the server
set_api_url!(b::Bls, url::AbstractString) # Set the base URL used to connect to the server
get_api_key(b::Bls)                       # Get the API key
get_api_version(b::Bls)                   # Get the API version (v1 or v2) used
requests_made(b::Bls)                     # Get the number of requests made today
requests_remaining(b::Bls)                # Get the number of requests remaining today

Note that the requests made/remaining are calculated based on the lifetime of this object only and would not include those made in a distinct Julia session.

The BlsSeries type

The BlsSeries type contains the data in a query response.

For a series s, access fields with

s.id                                     # series ID
s.data                                   # DataFrame of data
s.catalog                                # catalog metadata

Query data

Request one or multiple series from the BLS API.

get_data(b, series [; startyear, endyear, catalog])

• b: A Bls connection
• series: A string, or array of strings, identifying the time series
• startyear: A four-digit year identifying the start of the data request. Defaults to 9 or 19 years before endyear, depending on the API version used.
• endyear: A four-digit year identifying the end of the data request. Defaults to 9 or 19 years after endyear, depending on the API version used; or, this year, if neither startyear nor endyear is provided.
• catalog: Whether to return any available metadata about the series. Defaults to false.

A BlsSeries, or an array of BlsSeries.

Finding data series

The BLS mnemonics are somewhat obscure. You can attempt to build them programmatically by consulting this page.

Notes

The BLS API provides the following limits on requests:

BlsData.jl addresses these limits as follows:

• track daily query limit for reference
• make multiple requests under the hood, and concatenate results, for date ranges longer than limit
• [NOT IMPLEMENTED] make multiple requests under the hood, and concatenate results, for lists of series longer than limit