Class: ExperianConsumerView::Api

Inherits:
Object
  • Object
show all
Includes:
Errors
Defined in:
lib/experian_consumer_view/api.rb

Overview

Low-level class for accessing the Experian ConsumerView API. It is not recommended to use this class directly. The ExperianConsumerView::Client class is designed to be directly used by applications.

This class provides low-level access to make specific HTTP calls to the ConsumerView API, such as logging in to get an authorisation token, and performing lookups of an individual / household / postcode.

Constant Summary collapse

PRODUCTION_URL = 
'https://neartime.experian.co.uk'
STAGING_URL = 
'https://stg.neartime.experian.co.uk'
LOGIN_PATH = 
'/overture/login'
SINGLE_LOOKUP_PATH = 
'/overture/lookup'
BATCH_LOOKUP_PATH = 
'/overture/batch'

Instance Method Summary collapse

Constructor Details

#initialize(url: nil) ⇒ Api

Returns a new instance of Api.

Parameters:

  • url (String) (defaults to: nil) —

    optional base URL for the API wrapper to connect to. Defaults to the Experian ConsumerView production server.



26
27
28
29
30
31
 
# File 'lib/experian_consumer_view/api.rb', line 26

def initialize(url: nil)
  @httpclient = Faraday.new(
    url: url || PRODUCTION_URL,
    headers: { 'Content-Type' => 'application/json', 'Accept' => 'application/json' }
  )
end

Instance Method Details

#batch_lookup(user_id:, token:, client_id:, asset_id:, batched_search_keys:) ⇒ Array<Hash>

Looks up demographic data for a batch of individuals / households / postcodes.

Note that the demographic / propensity keys returned will only be those which the given client & asset have access to. Refer to the Experian ConsumerView API Documentation for exact details of the keys & possible values.

Parameters:

  • user_id (String) —

    the username / email used to authorize use of the ConsumerView API

  • token (String) —

    the time-limited authorization token provided when logging into the API

  • client_id (String) —

    your 5-digit Experian client ID

  • asset_id (String) —

    your 6-character Experian asset ID

  • search_keys (Array<Hash>) —

    an array of hashes, each hash containing the keys required to look up an individual / household / postcode. Refer to the Experian ConsumerView API Documentation for exact details on the required keys.

Returns:

  • (Array<Hash>) —

    an array of hashes, each hash containing a key/value pair for each demographic / propensity for the individual / household / postcode which was successfully looked up. Returns an empty hash for any items in the batch where no matches were found. The order of the results array is the same as the order of the supplied search array - ie. element 0 of the results array contains the hash of demographic data for the individual / household / postcode supplied in position 0 of the batch of search keys.

Raises:



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/experian_consumer_view/api.rb', line 95

def batch_lookup(user_id:, token:, client_id:, asset_id:, batched_search_keys:)
  raise ApiBatchTooBigError if batched_search_keys.length > ExperianConsumerView::MAX_LOOKUP_BATCH_SIZE

  query_params = {
    'ssoId' => user_id,
    'token' => token,
    'clientId' => client_id,
    'assetId' => asset_id,
    'batch' => batched_search_keys
  }

  result = @httpclient.post(BATCH_LOOKUP_PATH, query_params.to_json)
  check_http_result_status(result)

  JSON.parse(result.body)
end

#get_auth_token(user_id:, password:) ⇒ Object

Logs in to the Experian ConsumerView API, and gets an authorization token.

Parameters:

  • user_id (String) —

    the username / email used to authorize use of the ConsumerView API

  • password (String) —

    the password used to authorize use of the ConsumerView API



37
38
39
40
41
42
43
44
 
# File 'lib/experian_consumer_view/api.rb', line 37

def get_auth_token(user_id:, password:)
  query_params = { 'userid' => user_id, 'password' => password }

  result = @httpclient.post(LOGIN_PATH, query_params.to_json)
  check_http_result_status(result)

  JSON.parse(result.body)['token']
end

#single_lookup(user_id:, token:, client_id:, asset_id:, search_keys:) ⇒ Hash

Looks up demographic data for a single individual / household / postcode.

Note that the demographic / propensity keys returned will only be those which the given client & asset have access to. Refer to the Experian ConsumerView API Documentation for exact details of the keys & possible values.

Parameters:

  • user_id (String) —

    the username / email used to authorize use of the ConsumerView API

  • token (String) —

    the time-limited authorization token provided when logging into the API

  • client_id (String) —

    your 5-digit Experian client ID

  • asset_id (String) —

    your 6-character Experian asset ID

  • search_keys (Hash) —

    hash containing the keys required to look up an individual / household / postcode. Refer to the Experian ConsumerView API Documentation for exact details on the required keys.

Returns:

  • (Hash) —

    a hash containing a key/value pair for each demographic / propensity for the individual / household / postcode which was successfully looked up. Returns an empty hash if the lookup does not find any matches.



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/experian_consumer_view/api.rb', line 60

def single_lookup(user_id:, token:, client_id:, asset_id:, search_keys:)
  # TODO: Delete this if looking up a single item via the batch method isn't any slower - no point supporting both!

  query_params = {
    'ssoId' => user_id,
    'token' => token,
    'clientId' => client_id,
    'assetId' => asset_id
  }
  query_params.merge!(search_keys)

  result = @httpclient.post(SINGLE_LOOKUP_PATH, query_params.to_json)
  check_http_result_status(result)

  JSON.parse(result.body)
end