<commit_before># Postcode Anywhere

[ ![Codeship Status for simplemerchant/postcode_anywhere](https://codeship.io/projects/ade82b60-260e-0132-ce11-5220aac52c67/status)](https://codeship.io/projects/37329)

This is the Ruby gem for interacting with the [Postcode Anywhere API](http://www.postcodeanywhere.co.uk/support/webservices/) API

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'postcode_anywhere'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install postcode_anywhere

## Small disclaimer

The general architecture of this Gem is completely ripped off from that of the
[Twitter API Gem](https://github.com/sferik/twitter) so credit to be directed that way.
This has been used mainly because this structure generally works well for us
and it's well tested.

## Usage

This Gem consists of a numer of available clients for each key service available from
Postcode Anywhere

### [Data Cleansing](http://www.postcodeanywhere.co.uk/Support/WebService/CleansePlus/Interactive/Cleanse/1/)

An address can be cleansed by using the CleansePlus client, as follows:

```ruby
  client = PostcodeAnywhere::CleansePlus::Client.new(
    license_key:  'YOUR_API_KEY',
  )

  addresses = client.address_candidates_for 'London, SW1A 1AA'

  addresses.first.company
    # =>"Buckingham Palace"
```

The following fields are available on an address:

**udprn, company, department, line1, line2, line3, line4, line5, post_town, county,
postcode, mailsort, barcode, type, delivery_point_suffix, sub_building, building_name,
building_number, primary_street, secondary_street, double_dependent_locality,
dependent_locality, po_box**

### [Payment Validation](http://www.postcodeanywhere.co.uk/bank-account-validation/api/)

#### [Retrieve by sort code](http://www.postcodeanywhere.co.uk/Support/WebService/BankAccountValidation/Interactive/RetrieveBySortcode/1/)

A bank branch can be retrieved from a sort code:

```ruby
  client = PostcodeAnywhere::BankAccountValidation::Client.new(
    license_key:  'YOUR_API_KEY',
  )

  branch = client.retrieve_by_sortcode '40-17-53'

  branch.contact_postcode
  # => "GL53 7RA"
  branch.bank
  # => "HSBC BANK PLC"
  branch.faster_payments_supported
  # => true
```

The following fields are available on a bank branch:

**bank, bank_bic, branch, branch_bic, contact_address_line1, contact_address_line2,
contact_post_town, contact_postcode, contact_phone, contact_fax,
faster_payments_supported, chaps_supported**

#### [Validate account](http://www.postcodeanywhere.co.uk/support/webservice/bankaccountvalidation/interactive/validate/2/)

A bank account number and sort code can be validated:

```ruby
  client = PostcodeAnywhere::BankAccountValidation::Client.new(
    license_key:  'YOUR_API_KEY',
  )

  validation = a.validate_account('12345678','11-22-33')

  validation.is_correct
  # => true
```

The following fields are available for a validation:

**is_correct, is_direct_debit_capable, status_information, corrected_sort_code,
corrected_account_number, iban, bank, bank_bic, branch, branch_bic,
contact_address_line1, contact_address_line2, contact_post_town, contact_postcode,
contact_phone, contact_fax, faster_payments_supported, chaps_supported**

### [Email Validation](http://www.postcodeanywhere.co.uk/email-validation/api/)

#### [Validate email](http://www.postcodeanywhere.co.uk/Support/WebService/EmailValidation/Interactive/Validate/1.1/)

An email address can be validated:

```ruby
  client = PostcodeAnywhere::EmailValidation::Client.new(
    license_key:  'YOUR_API_KEY',
  )

  validation = a.validate_email_address('<EMAIL>')

  # Options then are

  validation.valid_format
  # => true
  validation.found_dns_record
  # => true
  validation.mail_server
  # => 'aspmx3.googlemail.com'
  validation.email
  # => '<EMAIL>'
```

## Errors

If there is something critically wrong with the service, then the gem will throw a relevant
exception which may be one of:

```ruby
  PostcodeAnywhere::Error::BadRequest,
  PostcodeAnywhere::Error::Unauthorized,
  PostcodeAnywhere::Error::Forbidden,
  PostcodeAnywhere::Error::NotFound,
  PostcodeAnywhere::Error::NotAcceptable,
  PostcodeAnywhere::Error::RequestTimeout,
  PostcodeAnywhere::Error::UnprocessableEntity,
  PostcodeAnywhere::Error::TooManyRequests,
  PostcodeAnywhere::Error::InternalServerError,
  PostcodeAnywhere::Error::BadGateway,<commit_msg>Readme fix<commit_after># Postcode Anywhere

[ ![Codeship Status for simplemerchant/postcode_anywhere](https://codeship.io/projects/ade82b60-260e-0132-ce11-5220aac52c67/status)](https://codeship.io/projects/37329)

This is the Ruby gem for interacting with the [Postcode Anywhere API](http://www.postcodeanywhere.co.uk/support/webservices/) API

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'postcode_anywhere'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install postcode_anywhere

## Small disclaimer

The general architecture of this Gem is completely ripped off from that of the
[Twitter API Gem](https://github.com/sferik/twitter) so credit to be directed that way.
This has been used mainly because this structure generally works well for us
and it's well tested.

## Usage

This Gem consists of a numer of available clients for each key service available from
Postcode Anywhere

### [Data Cleansing](http://www.postcodeanywhere.co.uk/Support/WebService/CleansePlus/Interactive/Cleanse/1/)

An address can be cleansed by using the CleansePlus client, as follows:

```ruby
  client = PostcodeAnywhere::CleansePlus::Client.new(
    license_key:  'YOUR_API_KEY',
  )

  addresses = client.address_candidates_for 'London, SW1A 1AA'

  addresses.first.company
    # =>"Buckingham Palace"
```

The following fields are available on an address:

**udprn, company, department, line1, line2, line3, line4, line5, post_town, county,
postcode, mailsort, barcode, type, delivery_point_suffix, sub_building, building_name,
building_number, primary_street, secondary_street, double_dependent_locality,
dependent_locality, po_box**

### [Payment Validation](http://www.postcodeanywhere.co.uk/bank-account-validation/api/)

#### [Retrieve by sort code](http://www.postcodeanywhere.co.uk/Support/WebService/BankAccountValidation/Interactive/RetrieveBySortcode/1/)

A bank branch can be retrieved from a sort code:

```ruby
  client = PostcodeAnywhere::BankAccountValidation::Client.new(
    license_key:  'YOUR_API_KEY',
  )

  branch = client.retrieve_by_sortcode '40-17-53'

  branch.contact_postcode
  # => "GL53 7RA"
  branch.bank
  # => "HSBC BANK PLC"
  branch.faster_payments_supported
  # => true
```

The following fields are available on a bank branch:

**bank, bank_bic, branch, branch_bic, contact_address_line1, contact_address_line2,
contact_post_town, contact_postcode, contact_phone, contact_fax,
faster_payments_supported, chaps_supported**

#### [Validate account](http://www.postcodeanywhere.co.uk/support/webservice/bankaccountvalidation/interactive/validate/2/)

A bank account number and sort code can be validated:

```ruby
  client = PostcodeAnywhere::BankAccountValidation::Client.new(
    license_key:  'YOUR_API_KEY',
  )

  validation = client.validate_account('12345678','11-22-33')

  validation.is_correct
  # => true
```

The following fields are available for a validation:

**is_correct, is_direct_debit_capable, status_information, corrected_sort_code,
corrected_account_number, iban, bank, bank_bic, branch, branch_bic,
contact_address_line1, contact_address_line2, contact_post_town, contact_postcode,
contact_phone, contact_fax, faster_payments_supported, chaps_supported**

### [Email Validation](http://www.postcodeanywhere.co.uk/email-validation/api/)

#### [Validate email](http://www.postcodeanywhere.co.uk/Support/WebService/EmailValidation/Interactive/Validate/1.1/)

An email address can be validated:

```ruby
  client = PostcodeAnywhere::EmailValidation::Client.new(
    license_key:  'YOUR_API_KEY',
  )

  validation = client.validate_email_address('<EMAIL>')

  # Options then are

  validation.valid_format
  # => true
  validation.found_dns_record
  # => true
  validation.mail_server
  # => 'aspmx3.googlemail.com'
  validation.email
  # => '<EMAIL>'
```

## Errors

If there is something critically wrong with the service, then the gem will throw a relevant
exception which may be one of:

```ruby
  PostcodeAnywhere::Error::BadRequest,
  PostcodeAnywhere::Error::Unauthorized,
  PostcodeAnywhere::Error::Forbidden,
  PostcodeAnywhere::Error::NotFound,
  PostcodeAnywhere::Error::NotAcceptable,
  PostcodeAnywhere::Error::RequestTimeout,
  PostcodeAnywhere::Error::UnprocessableEntity,
  PostcodeAnywhere::Error::TooManyRequests,
  PostcodeAnywhere::Error::InternalServerError,
  PostcodeAnywhere::Error::BadGateway,
{'fraction_non_alphanumeric': 0.10797962648556876, 'fraction_numerical': 0.014940577249575551, 'mean_word_length': 5.765696784073507, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 25, 'https://': 6, 'lorem ipsum': 0, 'www.': 14, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5337309', 'n_tokens_mistral': 2895, 'n_tokens_neox': 2730, 'n_words': 650}