https://github.com/wilsonsilva/loqate
API client for https://www.loqate.com/
https://github.com/wilsonsilva/loqate
Last synced: 6 months ago
JSON representation
API client for https://www.loqate.com/
- Host: GitHub
- URL: https://github.com/wilsonsilva/loqate
- Owner: wilsonsilva
- License: mit
- Created: 2018-09-29T08:59:19.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2025-04-09T17:36:50.000Z (6 months ago)
- Last Synced: 2025-04-09T18:44:06.677Z (6 months ago)
- Language: Ruby
- Size: 212 KB
- Stars: 5
- Watchers: 0
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Loqate
[](https://badge.fury.io/rb/loqate)
[](https://travis-ci.org/wilsonsilva/loqate)
[](https://codeclimate.com/github/wilsonsilva/loqate/maintainability)
[](https://codeclimate.com/github/wilsonsilva/loqate/test_coverage)
[](https://hakiri.io/github/wilsonsilva/loqate/master)
[](http://inch-ci.org/github/wilsonsilva/loqate)
Client to address verification, postcode lookup, & data quality services from Loqate.
## Table of contents
- [Installation](#installation)
- [Usage](#usage)
- [Getting started](#getting-started)
- [Bang methods](#bang-methods)
- [Example of using non-bang method](#example-of-using-non-bang-method)
- [Example of using bang method](#example-of-using-bang-method)
- [Address API](#address-api)
- [Finding addresses](#finding-addresses)
- [Retrieving the details of an address](#retrieving-the-details-of-an-address)
- [Geocoding API](#geocoding-api)
- [Finding directions](#finding-directions)
- [Geocoding a location](#geocoding-a-location)
- [Finding a country based on coordinates](#finding-a-country-based-on-coordinates)
- [Finding nearest places](#finding-nearest-places)
- [Phone API](#phone-api)
- [Validating a phone number](#validating-a-phone-number)
- [Email API](#phone-api)
- [Validating an email address](#validating-an-email-address)
- [Validating multiple email addresses](#validating-multiple-email-addresses)
- [Bank API](#bank-api)
- [Retrieving the details of a bank branch](#retrieving-the-details-of-a-bank-branch)
- [Validating a bank account](#validating-a-bank-account)
- [Validating an international bank account](#validating-an-international-bank-account)
- [Validating multiple bank accounts](#validating-multiple-bank-accounts)
- [Validating a card](#validating-a-card)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
## Installation
Add this line to your application's Gemfile:
```ruby
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](https://account.loqate.com/account#/):
```ruby
gateway = Loqate::Gateway.new(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
```ruby
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
```ruby
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](https://www.loqate.com/resources/support/apis/Capture/Interactive/Find/1/) request is used to narrow down a
possible list of addresses;
and a [Retrieve](https://www.loqate.com/resources/support/apis/Capture/Interactive/Retrieve/1/) 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
```ruby
addresses = gateway.address.find!(text: 'EC1Y 8AF', country: 'GB', limit: 5)
addresses.first.id # => 'GB|RM|B|8144611'
```
#### Retrieving the details of an address
```ruby
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
```ruby
directions = gateway.geocoding.directions!(
start: [51.5079532, -0.1266053],
finish: [51.5078677, -0.1266825]
)
directions.first.description # => 'Leave from Strand/A4'
```
#### Geocoding a location
```ruby
location = gateway.geocoding.geocode!(country: 'US', location: '90210')
location.name # => 'Beverly Hills, CA 90210'
```
#### Finding a country based on coordinates
```ruby
country = gateway.geocoding.position_to_country!(latitude: 52.1321, longitude: -2.1001)
country.country_name # => 'United Kingdom'
```
#### Finding nearest places
```ruby
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](https://www.loqate.com/resources/support/apis/PhoneNumberValidation/Interactive/Validate/2.2/) which starts
a new phone number validation request.
#### Validating a phone number
```ruby
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](https://www.loqate.com/resources/support/apis/EmailValidation/Interactive/Validate/2/) request to validate
a single email adress; and a
[Batch Validate](https://www.loqate.com/resources/support/apis/EmailValidation/Batch/Validate/1.2/) request to
validate multiple emails at once.
#### Validating an email address
```ruby
email_validation = gateway.email.validate!(email: 'person@gmail.com')
email_validation.valid? # => true
```
#### Validating multiple email addresses
```ruby
email_validations = gateway.email.batch_validate!(emails: %w[person@gmail.com])
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
```ruby
bank_branch = gateway.bank.retrieve_by_sortcode!(sort_code: '404131')
bank_branch.bank # => HSBC UK BANK PLC
```
#### Validating a bank account
```ruby
account_validation = gateway.bank.validate_account(account_number: '51065718', sort_code: '404131')
account_validation.correct? # => true
```
#### Validating an international bank account
```ruby
account_validation = gateway.bank.validate_international_account!(iban: 'GB03 BARC 201147 8397 7692')
account_validation.correct? # => true
```
#### Validating multiple bank accounts
```ruby
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
```ruby
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](https://github.com/wilsonsilva/loqate/blob/master/LICENSE).