Ruby wrapper to the NOAA NCEI Weather API at ncdc.noaa.gov

Uses Rest-Client to query information from the National Oceanic and Atmospheric Administration Climate Data Web Services API. This provides free access to global historical weather information from around the globe. Many types of weather measurements can be pulled in time frames from the first records to near current (a few days ago).

Use of the API requires the use of a free token. Register for your token on the request page. You'll need a token to use this gem.

Add this line to your application's Gemfile:

gem 'noaa_ncei_weather'

And then execute:

$ bundle

Or install it yourself as:

$ gem install noaa_ncei_weather

Start by setting the token

NoaaNceiWeather::Connection.token = 'TOKEN'

Use the NOAA page as a reference for the data available and the paramaters that can be used. This gem provides a class for the data returned by each of the available endpoints.

All of the endpoints (except Data) are what I'll call 'organizational' information used to filter down a query to the Data class. All of these have class methods for querying against the database.

NoaaNceiWeather::LocationCategory.all # Returns a collection of LocationCategory objects
NoaaNceiWeather::LocationCategory.where({limit: 42}) # Returns a collection of LocationCategory objects filtered by the parameters given
NoaaNceiWeather::LocationCategory.first # Returns a single LocationCategory object
NoaaNceiWeather::LocationCategory.find("CITY") # Returns a single LocationCategory with the given ID

Many of these endpoints also have relationships with one another. For example, each location category has many locations. This is shown as an optional parameter on the NOAA page for the location endpoint. To reflect this relationship, LocationCategory has an instance method .locations to retrieve the related records. The same is true for the other classes where available via parameters shown on the NOAA documentation

lc = NoaaNceiWeather::LocationCategory.first # returns a single instance of LocationCategory
lc.locations # returns a collection of Location objects related to lc

Parameters passed to the class methods are parsed before being sent to the NOAA API for convenience.

1. Relationship parameters to another endpoint can be passed an object instance. For example:

```ruby
lc = NoaaNceiWeather::LocationCategory.find('CITY') # an instance of LocationCategory
NoaaNceiWeather::Location.where(locationcategoryid: lc.id) # Parameter shown on the NOAA API Docs
NoaaNceiWeather::Location.where(locationcategory: lc) # alternative
```

2. Date parameters shown in the NOAA parameters can be given as Ruby Date, DateTime, or Time instances rather than an ISO formatted string

Limit is a parameter available to all the NOAA endpoints. Limit is being handled in the query so you can exceed the documented NOAA limit of a maximum 1000 per query. The .all method will return all of the available records, even if there are more than 1000. You may also set a limit of something over 1000 and that number will be returned to you. For example:

data = NoaaNceiWeather::DataType.all
data.count # => 1461 - the current count as of this writing
data = NoaaNceiWeather::DataType.where(limit: 1200)
data.count # => 1200 - passing a 1200 limit to the noaa api directly would raise a bad request error

The /data endpoint and corresponding Data class is where most of the real data is stored. The NOAA API required parameters are required in the class method, while the rest are passed with a hash as with the other classes. This returns a collection of Data objects.

ds = NoaaNceiWeather::Dataset.first
date = Date.today - 14
data = NoaaNceiWeather::Data.where(ds, date, date, {offset: 0})

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

Create an env.rb file and add a line ENV['NOAA_TOKEN'] = 'TOKEN'. The token will be loaded in when using bin/console so you don't have to set the token each time. It is also used in the test setup. The file is already included in .gitignore.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com//JasonBThelen/noaa_ncei_weather.

The gem is available as open source under the terms of the MIT License.