Skip to content

Latest commit

 

History

History
275 lines (210 loc) · 9.22 KB

README.md

File metadata and controls

275 lines (210 loc) · 9.22 KB
Raw

Loqate

Gem Version Build Status Maintainability Test Coverage Security Inline docs

Client to address verification, postcode lookup, & data quality services from Loqate.

Table of contents

Installation

Add this line to your application's Gemfile:

gem 'loqate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install loqate

Usage

Getting started

Loqate provides multiple APIs. And each API provides several services. This gem exposes these APIs through an API gateway.

To get started, initialize an API gateway with your API key:

gateway = Loqate::Gateway.new(api_key: '<YOUR_API_KEY>')

Bang methods

Most methods have a bang and a non-bang version (e.g. gateway.address.find and gateway.address.find!). The non-bang version will either return a Loqate::Success or an Loqate::Failure. The bang version will either return the desired resource, or it will raise an exception.

Example of using non-bang method

result = gateway.address.find(text: 'EC1Y 8AF', country: 'GB', limit: 5)

if result.success?
  addresses = result.value
  addresses.first.id # => 'GB|RM|B|8144611'
else
  error = result.error
  puts "Error retrieving the address: #{error.description}. Resolution: #{error.resolution}"
end

result.failure? # => false

Example of using bang method

begin
  addresses = gateway.address.find!(text: 'EC1Y 8AF', country: 'GB', limit: 5)
  addresses.first.id # => 'GB|RM|B|8144611'
rescue Loqate::Error => e
  puts "Error retrieving the address: #{e.description}. Resolution: #{e.resolution}"
end

It is recommended that you use the bang methods when you assume that the data is valid and do not expect validations to fail. Otherwise, use the non-bang methods.

Address API

The Address API consists of two main API requests: Find request is used to narrow down a possible list of addresses; and a Retrieve request is used to retrieve a fully formatted address.

A typical address search is made up of a series of find requests, followed by a retrieve based on the user selection.

Finding addresses

addresses = gateway.address.find!(text: 'EC1Y 8AF', country: 'GB', limit: 5)
addresses.first.id # => 'GB|RM|B|8144611'

Retrieving the details of an address

address = gateway.address.retrieve!(id: 'GB|RM|B|8144611')

address.city        # 'London' 
address.line1       # '148 Warner Road'
address.postal_code # 'E17 7EA'

Geocoding API

The Geocoding API exposes endpoints to perform geocoding operations.

Finding directions

directions = gateway.geocoding.directions!(
  start: [51.5079532, -0.1266053],
  finish: [51.5078677, -0.1266825]
)
directions.first.description # => 'Leave from Strand/A4'

Geocoding a location

location = gateway.geocoding.geocode!(country: 'US', location: '90210')
location.name # => 'Beverly Hills, CA 90210'

Finding a country based on coordinates

country = gateway.geocoding.position_to_country!(latitude: 52.1321, longitude: -2.1001)
country.country_name # => 'United Kingdom'

Finding nearest places

nearest_places = gateway.geocoding.retrieve_nearest_places!(
  centre_point: [-33.440113067627, 149.578567504883],
  maximum_items: 5,
  maximum_radius: 10,
  filter_options: 'HideVillages'
)
nearest_places.first.location # => 'South Bathurst, NSW, Australia'

Phone API

The Phone API consists of a single API request: Validate which starts a new phone number validation request.

Validating a phone number

phone_validation = gateway.phone.validate!(phone: '+447440029210', country: 'GB')
phone_validation.phone_number # => '+447440029210'
phone_validation.valid?       # => true

Email API

The Email API consists of two main API requests: Validate request to validate a single email adress; and a Batch Validate request to validate multiple emails at once.

Validating an email address

email_validation = gateway.email.validate!(email: '[email protected]')
email_validation.valid? # => true

Validating multiple email addresses

email_validations = gateway.email.batch_validate!(emails: %w[[email protected]])
email_validation  = email_validations.first
email_validation.valid? # => true

Bank API

The Bank API exposes endpoints to validate bank accounts, cards and finding bank branches by sort code.

Retrieving the details of a bank branch

bank_branch = gateway.bank.retrieve_by_sortcode!(sort_code: '404131')
bank_branch.bank # => HSBC UK BANK PLC

Validating a bank account

account_validation = gateway.bank.validate_account(account_number: '51065718', sort_code: '404131')
account_validation.correct? # => true

Validating an international bank account

account_validation = gateway.bank.validate_international_account!(iban: 'GB03 BARC 201147 8397 7692')
account_validation.correct? # => true

Validating multiple bank accounts

accounts_validations = gateway.bank.batch_validate_accounts!(
  account_numbers: %w[51065718 12001020],
  sort_codes: %w[40-41-31 083210]
)
accounts_validations.first.correct?  # => true
accounts_validations.second.correct? # => false

Validating a card

card_validation = gateway.bank.validate_card!(card_number: '4024007171239865')
card_validation.card_type # => VISA

Development

After checking out the repo, run bin/setup to install dependencies, configure git hooks and create support files.

You can also run bin/console for an interactive prompt that will allow you to experiment.

Then add your Loqate API key to .api_key. It will be used by RSpec and VCR, but not stored in the codebase.

The health and maintainability of the codebase is ensured through a set of Rake tasks to test, lint and audit the gem for security vulnerabilities and documentation:

rake bundle:audit          # Checks for vulnerable versions of gems 
rake qa                    # Test, lint and perform security and documentation audits
rake rubocop               # Lint the codebase with RuboCop
rake rubocop:auto_correct  # Auto-correct RuboCop offenses
rake spec                  # Run RSpec code examples
rake verify_measurements   # Verify that yardstick coverage is at least 100%
rake yard                  # Generate YARD Documentation
rake yard:junk             # Check the junk in your YARD Documentation
rake yardstick_measure     # Measure docs in lib/**/*.rb with yardstick

Contributing

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

License

See LICENSE.