README.md in loqate-0.3.0 vs README.md in loqate-0.4.0
- old
+ new
@@ -7,10 +7,26 @@
[](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)
+ - [Phone API](#phone-api)
+ - [Validating a phone number](#validating-a-phone-number)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -36,11 +52,11 @@
```ruby
gateway = Loqate::Gateway.new(api_key: '<YOUR_API_KEY>')
```
-### Bang Methods
+### 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.
@@ -86,27 +102,48 @@
selection.
#### Finding addresses
```ruby
-result = gateway.address.find(text: 'EC1Y 8AF', country: 'GB', limit: 5)
+addresses = gateway.address.find!(text: 'EC1Y 8AF', country: 'GB', limit: 5)
-addresses = result.value
addresses.first.id # => 'GB|RM|B|8144611'
```
#### Retrieving the details of an address
```ruby
-result = gateway.address.retrieve(id: 'GB|RM|B|8144611')
+address = gateway.address.retrieve!(id: 'GB|RM|B|8144611')
-address = result.value
-address.city # 'London'
-address.line1 # '148 Warner Road'
-address.postal_code # 'E17 7EA'
+address.city # 'London'
+address.line1 # '148 Warner Road'
+address.postal_code # 'E17 7EA'
```
+### 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.request_processed # => true
+phone_validation.is_valid # => 'Yes' -> This is how Loqate defines validity
+phone_validation.valid? # => true
+phone_validation.network_code # => '26'
+phone_validation.network_name # => 'Telefonica UK'
+phone_validation.network_country # => 'GB'
+phone_validation.national_format # => '07440 029210'
+phone_validation.country_prefix # => 44
+phone_validation.number_type # => 'Mobile'
+```
+
## 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.
@@ -129,5 +166,9 @@
```
## 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).