Client to address verification, postcode lookup, & data quality services from Loqate.
- Installation
- Usage
- Development
- Contributing
- License
Add this line to your application's Gemfile:
gem 'loqate'And then execute:
$ bundle
Or install it yourself as:
$ gem install loqate
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>')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.
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? # => falsebegin
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}"
endIt 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.
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.
addresses = gateway.address.find!(text: 'EC1Y 8AF', country: 'GB', limit: 5)
addresses.first.id # => 'GB|RM|B|8144611'address = gateway.address.retrieve!(id: 'GB|RM|B|8144611')
address.city # 'London'
address.line1 # '148 Warner Road'
address.postal_code # 'E17 7EA'The Geocoding API exposes endpoints to perform geocoding operations.
directions = gateway.geocoding.directions!(
start: [51.5079532, -0.1266053],
finish: [51.5078677, -0.1266825]
)
directions.first.description # => 'Leave from Strand/A4'location = gateway.geocoding.geocode!(country: 'US', location: '90210')
location.name # => 'Beverly Hills, CA 90210'country = gateway.geocoding.position_to_country!(latitude: 52.1321, longitude: -2.1001)
country.country_name # => 'United Kingdom'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'The Phone API consists of a single API request: Validate which starts a new phone number validation request.
phone_validation = gateway.phone.validate!(phone: '+447440029210', country: 'GB')
phone_validation.phone_number # => '+447440029210'
phone_validation.valid? # => trueThe 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.
email_validation = gateway.email.validate!(email: '[email protected]')
email_validation.valid? # => trueemail_validations = gateway.email.batch_validate!(emails: %w[[email protected]])
email_validation = email_validations.first
email_validation.valid? # => trueThe Bank API exposes endpoints to validate bank accounts, cards and finding bank branches by sort code.
bank_branch = gateway.bank.retrieve_by_sortcode!(sort_code: '404131')
bank_branch.bank # => HSBC UK BANK PLCaccount_validation = gateway.bank.validate_account(account_number: '51065718', sort_code: '404131')
account_validation.correct? # => trueaccount_validation = gateway.bank.validate_international_account!(iban: 'GB03 BARC 201147 8397 7692')
account_validation.correct? # => trueaccounts_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? # => falsecard_validation = gateway.bank.validate_card!(card_number: '4024007171239865')
card_validation.card_type # => VISAAfter 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
Bug reports and pull requests are welcome on GitHub at https://github.com/wilsonsilva/loqate.
See LICENSE.