Skip to content

getto23/hlr-lookup-api-ruby-sdk

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

25 Commits
 
 
 
 
 
 

Repository files navigation

hlr-lookup-api-ruby-sdk

Official HLR Lookup API Ruby SDK by www.hlr-lookups.com

This SDK implements the REST API documented at https://www.hlr-lookups.com/en/api-docs

For SDKs in other programming languages, see https://www.hlr-lookups.com/en/sdks

Requirements

  • rest_client
  • json
  • sinatra

Installation with gem

gem install ruby_hlr_client

Usage Client

require 'ruby_hlr_client/hlr_client'

# Initializes the HLR Lookup Client
# @param username - www.hlr-lookups.com username
# @param password - www.hlr-lookups.com password
# @param ssl - set to false to disable SSL
# @constructor
client = RubyHlrClient::HlrClient.new(
    'username',
    'password'
)

# Submits a synchronous HLR Lookup request. The HLR is queried in real time and results presented in the response body.
# @param msisdn - An MSISDN in international format, e.g. +491788735000
# @param route - An optional route assignment, see: http://www.hlr-lookups.com/en/routing-options
# @param storage - An optional storage assignment, see: http://www.hlr-lookups.com/en/storages
# @returns string (JSON)
#
# Return example: {"success":true,"results":[{"id":"e1fdf26531e4","msisdncountrycode":"DE","msisdn":"+491788735000","statuscode":"HLRSTATUS_DELIVERED","hlrerrorcodeid":null,"subscriberstatus":"SUBSCRIBERSTATUS_CONNECTED","imsi":"262031300000000","mccmnc":"26203","mcc":"262","mnc":"03","msin":"1300000000","servingmsc":"140445","servinghlr":null,"originalnetworkname":"E-Plus","originalcountryname":"Germany","originalcountrycode":"DE","originalcountryprefix":"+49","originalnetworkprefix":"178","roamingnetworkname":"Fixed Line Operators and Other Networks","roamingcountryname":"United States","roamingcountrycode":"US","roamingcountryprefix":"+1","roamingnetworkprefix":"404455","portednetworkname":null,"portedcountryname":null,"portedcountrycode":null,"portedcountryprefix":null,"portednetworkprefix":null,"isvalid":"Yes","isroaming":"Yes","isported":"No","usercharge":"0.0100","inserttime":"2014-12-28 06:22:00.328844+08","storage":"SDK-TEST-SYNC-API","route":"IP1","interface":"Sync API"}]}
print client.submit_sync_lookup_request('+491788735000', 'IP4', 'SDK-TEST')

# Submits a synchronous number type lookup request. Results are presented in the response body.
# @param number - An number in international format, e.g. +4989702626
# @param route - An optional route assignment, see: http://www.hlr-lookups.com/en/routing-options
# @param storage - An optional storage assignment, see: http://www.hlr-lookups.com/en/storages
# @returns string (JSON)
#
# Return example: {"success":true,"results":[{"id":"2ed0788379c6","number":"+4989702626","numbertype":"LANDLINE","state":"COMPLETED","isvalid":"Yes","invalidreason":null,"ispossiblyported":"No","isvanitynumber":"No","qualifiesforhlrlookup":"No","originalcarrier":null,"mccmnc":null,"mcc":null,"mnc":null,"countrycode":"DE","regions":["Munich"],"timezones":["Europe\/Berlin"],"infotext":"This is a landline number.","usercharge":"0.0050","inserttime":"2015-12-04 10:36:41.866283+00","storage":"SYNC-API-NT-2015-12","route":"LC1","interface":"Sync API"}]}
print client.submit_sync_number_type_lookup_request('+4989702626', 'LC1', 'SDK-TEST')

# Sets the callback URL for asynchronous lookups. Read more about the concept of asynchronous HLR lookups @ http://www.hlr-lookups.com/en/asynchronous-hlr-lookup-api
# @param url - callback url on your server
# @returns string (JSON)
#
# Return example: {"success":true,"messages":[],"results":{"url":"http:\/\/user:[email protected]\/path\/file"}}
print client.set_async_callback_url('http://user:[email protected]/path/file')

# Sets the callback URL for asynchronous number type lookups.
# @param url - callback url on your server
# @returns string (JSON)
#
# Return example: {"success":true,"messages":[],"results":{"url":"http:\/\/user:[email protected]\/path\/file"}}
print client.set_nt_async_callback_url('http://user:[email protected]/path/file')

# Submits asynchronous HLR Lookups containing up to 1,000 MSISDNs per request. Results are sent back asynchronously to a callback URL on your server.
# @param msisdns - A list of MSISDNs in international format, e.g. +491788735000
# @param route - An optional route assignment, see: http://www.hlr-lookups.com/en/routing-options
# @param storage - An optional storage assignment, see: http://www.hlr-lookups.com/en/storages
# @returns string (JSON)
#
# Return example: {"success":true,"messages":[],"results":{"acceptedMsisdns":[{"id":"e489a092eba7","msisdn":"+491788735000"},{"id":"23ad48bf0c26","msisdn":"+491788735001"}],"rejectedMsisdns":[],"acceptedMsisdnCount":2,"rejectedMsisdnCount":0,"totalCount":2,"charge":0.02,"storage":"SDK-TEST-ASYNC-API","route":"IP4"}}
print client.submit_async_lookup_request(['+491788735000', '+491788735001'])

# Submits asynchronous number type lookups containing up to 1,000 numbers per request. Results are sent back asynchronously to a callback URL on your server.
# @param numbers - A list of numbers in international format, e.g. +4989702626,+491788735000
# @param route - An optional route assignment, see: http://www.hlr-lookups.com/en/routing-options
# @param storage - An optional storage assignment, see: http://www.hlr-lookups.com/en/storages
# @returns string (JSON)
#
# Return example: { "success":true, "messages":[], "results":{ "acceptedNumbers":[ { "id":"f09b30014d5e", "number":"+4989702626" }, { "id":"364c0ad33c02", "number":"+491788735000" } ], "rejectedNumbers":[ { "id":null, "number":"asdf" } ], "acceptedNumberCount":2, "rejectedNumberCount":1, "totalCount":3, "charge":0.01, "storage":"ASYNC-API-NT-2015-12", "route":"LC1" } }
print client.submit_async_number_type_lookup_request(['+4989702626','+491788735000'])

# Returns the remaining balance (EUR) in your account.
# @returns string (JSON)
#
# Return example: {"success":true,"messages":[],"results":{"balance":"5878.24600"}}
print client.get_balance

# Performs a health check on the system status, the user account and availability of each route.
# @returns string (JSON)
#
# Return example: { "success":true, "results":{ "system":{ "state":"up" }, "routes":{ "states":{ "IP1":"up", "ST2":"up", "SV3":"up", "IP4":"up", "XT5":"up", "XT6":"up", "NT7":"up", "LC1":"up" } }, "account":{ "lookupsPermitted":true, "balance":"295.23000" } } }
print client.do_health_check    

Usage Callback Handler

require 'sinatra'
require 'ruby_hlr_client/hlr_callback_handler'

set :run, true

get '/' do

  client = RubyHlrClient::HlrCallbackHandler.new

  # Parses an asynchronous HLR Lookup callback and returns a JSON string with the results.
  # @param params
  # @returns string (JSON)
  #
  # Return example: {"success":true,"results":[{"id":"40ebb8d9e7cc","msisdncountrycode":"DE","msisdn":"+491788735001","statuscode":"HLRSTATUS_DELIVERED","hlrerrorcodeid":null,"subscriberstatus":"SUBSCRIBERSTATUS_CONNECTED","imsi":"262032000000000","mccmnc":"26203","mcc":"262","mnc":"03","msin":"2000000000","servingmsc":"491770","servinghlr":null,"originalnetworkname":"178","originalcountryname":"Germany","originalcountrycode":"DE","originalcountryprefix":"+49","originalnetworkprefix":"178","roamingnetworkname":null,"roamingcountryname":null,"roamingcountrycode":null,"roamingcountryprefix":null,"roamingnetworkprefix":null,"portednetworkname":null,"portedcountryname":null,"portedcountrycode":null,"portedcountryprefix":null,"portednetworkprefix":null,"isvalid":"Yes","isroaming":"No","isported":"No","usercharge":"0.0100","inserttime":"2014-12-28 05:53:03.765798+08","storage":"ASYNC-API","route":"IP4"}]}
  print client.parse_callback(params)

  # send HTTP response body (OK)
  content_type :text
  return client.send_response

end

With that you should be ready to go!

Tests

The code contains annotations and you can find usage examples as tests in tests/:

  • bin/test_client.rb
  • bin/test_callback_handler.rb

Please refer to https://www.hlr-lookups.com/en/sdk-ruby for further documentation or send us an email to [email protected].

Support and Feedback

Your feedback is appreciated! If you have specific problems or bugs with this SDK, please file an issue on Github. For general feedback and support requests, send an email to [email protected].

Contributing

  1. Fork it ( https://github.com/vmgltd/hlr-lookup-api-ruby-sdk/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

About

Official HLR Lookup API Ruby SDK by www.hlr-lookups.com

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Ruby 100.0%