[![Code Climate](https://codeclimate.com/github/ContinuityControl/fdic/badges/gpa.svg)](https://codeclimate.com/github/ContinuityControl/fdic)
[![Test Coverage](https://codeclimate.com/github/ContinuityControl/fdic/badges/coverage.svg)](https://codeclimate.com/github/ContinuityControl/fdic/coverage)
[![Build Status](https://travis-ci.org/ContinuityControl/fdic.svg?branch=master)](https://travis-ci.org/ContinuityControl/fdic)
[![Gem Version](https://badge.fury.io/rb/fdic.svg)](https://badge.fury.io/rb/fdic)

# FDIC
### Current API Status
[![API Status](http://cc-api-schema-validator.herokuapp.com/fdic/badge)](http://cc-api-schema-validator.herokuapp.com/fdic/status)

The FDIC [lets you find information on FDIC-insured banking
institutions](https://research.fdic.gov/bankfind/index.html). Their site uses
[a JSON
API](http://www.programmableweb.com/news/fdic-bank-data-api-available-official-announcement-pending/2015/02/06)
to look up financial information, branch information, etc.

This gem is a ruby client to that API. It's totally unaffiliated with the FDIC.
It's open source, so anyone can use it, and anyone can help maintain it. At
this point, it's maintained by [the
developers](http://engineering.continuity.net/) at
[Continuity](http://continuity.net).

If you need help understanding the data returned by that API, and this gem, it
can help to look at [the FDIC's BankFind glossary of
terms](https://research.fdic.gov/bankfind/glossary.html).

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'fdic'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install fdic

## Usage

Currently all of our features are namespaced under the `FDIC::BankFind` module

The FDIC API lets you find an Institution if you have its FDIC Certificate Number:

```ruby
institution = FDIC::BankFind.find_institution(26588)  #=> FDIC::BankFind::Institution
```

If your certificate number is incorrect, this will raise an exception:

```ruby
institution = FDIC::BankFind.find_institution(26588)  #=> FDIC::BankFind::Institution
# raises FDIC::Exceptions::RecordNotFound
```

Note, sometimes seemingly "valid" parameters will cause the FDIC to return a 500 error code.
```ruby
institution = FDIC::BankFIND.find_institution("DOG") # Not a number
institution = FDIC::BankFIND.find_institution(1234567898798) # a number with more than 10 digits
# the FDIC returns 500
```

When this happens, the gem will catch the error and raise an exception:
```ruby
institution = FDIC::BankFIND.find_institution(1234567898798) # a number with more than 10 digits
# raises FDIC::Exceptions::ServerError
```

If you don't have the certificate number, you can search for a Bank by name, and get back all matching Banks:

```ruby
banks = FDIC::BankFind.find_bank('Dedicated Community Bank')  #=> [FDIC::BankFind::Bank, FDIC::BankFind::Bank, ...]
```

Once you have a Bank, you can get its Institution, which has much more data available:

```ruby
institution = banks.first.find_institution!  # Bang, because it's another network request
```

The API also exposes information about an Institution's branches, and its history. You can query both of these on the FDIC::BankFind module directly, or on the Institution:

```ruby
institution.find_branches!  #=> [FDIC::BankFind::Branch, FDIC::BankFind::Branch, ...]
FDIC::BankFind.find_branches(25688)   #=> [FDIC::BankFind::Branch, FDIC::BankFind::Branch, ...]

institution.find_history_events!                              #=> [FDIC::BankFind::HistoryEvent, ...]
FDIC::BankFind.find_history_events('Dedicated Community Bank', 26588)   #=> [FDIC::BankFind::HistoryEvent, ...]
```

Since a `Bank` knows its certificate number, it can look up its branch and history information, too.

```ruby
# These work just like they do on Institutions:
bank.find_branches!
bank.find_history_events!
```

There are more fields exposed in the Institution API than what we've exposed. Where the field names are obscure or acronym-y, we'd like to clarify them; since we're pre-1.0, if we haven't looked up a field's meaning quite yet, we're holding off. (You can still get all the fields via `#attributes`.)

## Schema Validation

This gem heavily depends on the schema of an unpublished government API. As such, it's liable to break. To help prevent against this we've provided a top level `FDIC::BankFind.validate_schema?` method, returning `true` if the schema of the FDIC's unpublished API has changed. We also expose a similar method `FDIC::BankFind.validate_schema!` which will raise a meaningful exception if the schema is invalid.

The gem provides an internal rake task, `rake fdic:validate_schema!` which calls `FDIC::BankFind.validate_schema!`. For the convenience of Rails users, we have used a Railtie to automatically provide this rake task in your application.

Because the schema may change more suddenly than developers can check for, we've created a [very small application](https://github.com/ContinuityControl/api_schema_validator) that validates the schema of this gem and its sister gem, [ncua](https://github.com/ContinuityControl/ncua).

The api_schema_validator application checks daily to see if the schema is invalid. It exposes a few handy endpoints, notably `/fdic/status`, which returns the follwing JSON:
```json
  {
    "schema_good" : true
  }
  // OR
  {
    "schema_good" : false
  }
```

and `/fdic/badge` which returns an svg status badge. In fact, you saw that badge at the top of this readme!

## Contributing

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

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).