experian_consumer_view 1.0.0

data/lib/experian_consumer_view/transformers/attributes/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ExperianConsumerView
+  module Transformers
+    module Attributes
+      # Base mpdule for Attribute Transformers.
+      # Mixin to Attribute Transformer classes with +extend ExperianConsumerView::Transformers::Attributes::Base+.
+      #
+      # Expects the class to provide two constants:
+      # - +ATTRIBUTE_NAME+ - the name of the attribute, as returned by the ConsumerView API, which the class can
+      #     transform.
+      # - +CODE_MAP+ - a hash whose keys are all the String codes which the ConsumerView API may return for the
+      #     attribute in question, and whose values are the what the attribute should be mapped to when the matching
+      #     code is returned.
+      #
+      # This module will then provide two class-level methods:
+      # - +attribute_name+ - simply returns the value of the +ATTRIBUTE_NAME+ constant.
+      # - +transform_attribute+ - transforms the given +value+ based on the +CODE_MAP+, or raises a
+      #     +AttributeValueUnrecognisedError+ if the value is not foung in the +CODE_MAP+.
+      module Base
+        def attribute_name
+          self::ATTRIBUTE_NAME
+        end
+
+        def transform_attribute(value)
+          return self::CODE_MAP[value] if self::CODE_MAP[value]
+
+          raise ExperianConsumerView::Errors::AttributeValueUnrecognisedError
+        end
+      end
+    end
+  end
+end

data/lib/experian_consumer_view/transformers/attributes/match.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ExperianConsumerView
+  module Transformers
+    module Attributes
+      # An Attribute Transformer to tranform the ConsumerView 'Match' field
+      class Match
+        extend Base
+
+        ATTRIBUTE_NAME = 'Match'
+
+        CODE_MAP = {
+          'PC' => { api_code: 'PC', match_level: 'postcode' },
+          'H' => { api_code: 'H', match_level: 'household' },
+          'P' => { api_code: 'P', match_level: 'person' }
+        }.freeze
+      end
+    end
+  end
+end

data/lib/experian_consumer_view/transformers/attributes/postcode_mosaic_uk_7_group.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Generated by grabbing all values from the table in the Experian docs, and running this search/replace:
+# ([A-Z0-9]+) ([A-Z0-9]+) (.*)$
+# '$1' => { api_code: '$1', group: '$2', description: '$3' },
+
+require_relative 'base'
+
+module ExperianConsumerView
+  module Transformers
+    module Attributes
+      # An Attribute Transformer to tranform the ConsumerView 'pc_mosaic_uk_7_group' field
+      class PostcodeMosaicUk7Group
+        extend Base
+
+        ATTRIBUTE_NAME = 'pc_mosaic_uk_7_group'
+
+        CODE_MAP = {
+          'A' => { api_code: 'A', group: 'A', description: 'City Prosperity' },
+          'B' => { api_code: 'B', group: 'B', description: 'Prestige Positions' },
+          'C' => { api_code: 'C', group: 'C', description: 'Country Living' },
+          'D' => { api_code: 'D', group: 'D', description: 'Rural Reality' },
+          'E' => { api_code: 'E', group: 'E', description: 'Senior Security' },
+          'F' => { api_code: 'F', group: 'F', description: 'Suburban Stability' },
+          'G' => { api_code: 'G', group: 'G', description: 'Domestic Success' },
+          'H' => { api_code: 'H', group: 'H', description: 'Aspiring Homemakers' },
+          'I' => { api_code: 'I', group: 'I', description: 'Family Basics' },
+          'J' => { api_code: 'J', group: 'J', description: 'Transient Renters' },
+          'K' => { api_code: 'K', group: 'K', description: 'Municipal Tenants' },
+          'L' => { api_code: 'L', group: 'L', description: 'Vintage Value' },
+          'M' => { api_code: 'M', group: 'M', description: 'Modest Traditions' },
+          'N' => { api_code: 'N', group: 'N', description: 'Urban Cohesion' },
+          'O' => { api_code: 'O', group: 'O', description: 'Rental Hubs' },
+          'U' => { api_code: 'U', group: 'U', description: 'Unclassified' }
+        }.freeze
+      end
+    end
+  end
+end

data/lib/experian_consumer_view/transformers/attributes/postcode_mosaic_uk_7_type.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Generated by grabbing all values from the table in the Experian docs, and running this search/replace:
+# ([A-Z0-9]+) ([A-Z0-9]+) (.*)$
+# '$1' => { api_code: '$1', type: '$2', description: '$3' },
+
+require_relative 'base'
+
+module ExperianConsumerView
+  module Transformers
+    module Attributes
+      # An Attribute Transformer to tranform the ConsumerView 'pc_mosaic_uk_7_type' field
+      class PostcodeMosaicUk7Type
+        extend Base
+
+        ATTRIBUTE_NAME = 'pc_mosaic_uk_7_type'
+
+        CODE_MAP = {
+          '01' => { api_code: '01', type: 'A01', description: 'World-Class Wealth' },
+          '02' => { api_code: '02', type: 'A02', description: 'Uptown Elite' },
+          '03' => { api_code: '03', type: 'A03', description: 'Penthouse Chic' },
+          '04' => { api_code: '04', type: 'A04', description: 'Metro High-Flyers' },
+          '05' => { api_code: '05', type: 'B05', description: 'Premium Fortunes' },
+          '06' => { api_code: '06', type: 'B06', description: 'Diamond Days' },
+          '07' => { api_code: '07', type: 'B07', description: 'Alpha Families' },
+          '08' => { api_code: '08', type: 'B08', description: 'Bank of Mum and Dad' },
+          '09' => { api_code: '09', type: 'B09', description: 'Empty-Nest Adventure' },
+          '10' => { api_code: '10', type: 'C10', description: 'Wealthy Landowners' },
+          '11' => { api_code: '11', type: 'C11', description: 'Rural Vogue' },
+          '12' => { api_code: '12', type: 'C12', description: 'Scattered Homesteads' },
+          '13' => { api_code: '13', type: 'C13', description: 'Village Retirement' },
+          '14' => { api_code: '14', type: 'D14', description: 'Satellite Settlers' },
+          '15' => { api_code: '15', type: 'D15', description: 'Local Focus' },
+          '16' => { api_code: '16', type: 'D16', description: 'Outlying Seniors' },
+          '17' => { api_code: '17', type: 'D17', description: 'Far-Flung Outposts' },
+          '18' => { api_code: '18', type: 'E18', description: 'Legacy Elders' },
+          '19' => { api_code: '19', type: 'E19', description: 'Bungalow Haven' },
+          '20' => { api_code: '20', type: 'E20', description: 'Classic Grandparents' },
+          '21' => { api_code: '21', type: 'E21', description: 'Solo Retirees' },
+          '22' => { api_code: '22', type: 'F22', description: 'Boomerang Boarders' },
+          '23' => { api_code: '23', type: 'F23', description: 'Family Ties' },
+          '24' => { api_code: '24', type: 'F24', description: 'Fledgling Free' },
+          '25' => { api_code: '25', type: 'F25', description: 'Dependable Me' },
+          '26' => { api_code: '26', type: 'G26', description: 'Cafés and Catchments' },
+          '27' => { api_code: '27', type: 'G27', description: 'Thriving Independence' },
+          '28' => { api_code: '28', type: 'G28', description: 'Modern Parents' },
+          '29' => { api_code: '29', type: 'G29', description: 'Mid-Career Convention' },
+          '30' => { api_code: '30', type: 'H30', description: 'Primary Ambitions' },
+          '31' => { api_code: '31', type: 'H31', description: 'Affordable Fringe' },
+          '32' => { api_code: '32', type: 'H32', description: 'First-Rung Futures' },
+          '33' => { api_code: '33', type: 'H33', description: 'Contemporary Starts' },
+          '34' => { api_code: '34', type: 'H34', description: 'New Foundations' },
+          '35' => { api_code: '35', type: 'H35', description: 'Flying Solo' },
+          '36' => { api_code: '36', type: 'I36', description: 'Solid Economy' },
+          '37' => { api_code: '37', type: 'I37', description: 'Budget Generations' },
+          '38' => { api_code: '38', type: 'I38', description: 'Economical Families' },
+          '39' => { api_code: '39', type: 'I39', description: 'Families on a Budget' },
+          '40' => { api_code: '40', type: 'J40', description: 'Value Rentals' },
+          '41' => { api_code: '41', type: 'J41', description: 'Youthful Endeavours' },
+          '42' => { api_code: '42', type: 'J42', description: 'Midlife Renters' },
+          '43' => { api_code: '43', type: 'J43', description: 'Renting Rooms' },
+          '44' => { api_code: '44', type: 'K44', description: 'Inner City Stalwarts' },
+          '45' => { api_code: '45', type: 'K45', description: 'City Diversity' },
+          '46' => { api_code: '46', type: 'K46', description: 'High Rise Residents' },
+          '47' => { api_code: '47', type: 'K47', description: 'Single Essentials' },
+          '48' => { api_code: '48', type: 'K48', description: 'Mature Workers' },
+          '49' => { api_code: '49', type: 'L49', description: 'Flatlet Seniors' },
+          '50' => { api_code: '50', type: 'L50', description: 'Pocket Pensions' },
+          '51' => { api_code: '51', type: 'L51', description: 'Retirement Communities' },
+          '52' => { api_code: '52', type: 'L52', description: 'Estate Veterans' },
+          '53' => { api_code: '53', type: 'L53', description: 'Seasoned Survivors' },
+          '54' => { api_code: '54', type: 'M54', description: 'Down-to-Earth Owners' },
+          '55' => { api_code: '55', type: 'M55', description: 'Back with the Folks' },
+          '56' => { api_code: '56', type: 'M56', description: 'Self Supporters' },
+          '57' => { api_code: '57', type: 'N57', description: 'Community Elders' },
+          '58' => { api_code: '58', type: 'N58', description: 'Culture & Comfort' },
+          '59' => { api_code: '59', type: 'N59', description: 'Large Family Living' },
+          '60' => { api_code: '60', type: 'N60', description: 'Ageing Access' },
+          '61' => { api_code: '61', type: 'O61', description: 'Career Builders' },
+          '62' => { api_code: '62', type: 'O62', description: 'Central Pulse' },
+          '63' => { api_code: '63', type: 'O63', description: 'Flexible Workforce' },
+          '64' => { api_code: '64', type: 'O64', description: 'Bus-Route Renters' },
+          '65' => { api_code: '65', type: 'O65', description: 'Learners & Earners' },
+          '66' => { api_code: '66', type: 'O66', description: 'Student Scene' },
+          '99' => { api_code: '99', type: 'U', description: 'Unclassified' }
+        }.freeze
+      end
+    end
+  end
+end

data/lib/experian_consumer_view/transformers/no_op_transformer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ExperianConsumerView
+  module Transformers
+    # Trivial implementation of a result transformer for when the calling code just wants the raw results as returned
+    # by the API.
+    class NoOpTransformer
+      def transform(result_hash)
+        result_hash
+      end
+    end
+  end
+end

data/lib/experian_consumer_view/transformers/result_transformer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# For convinience, ensure all attribute transformers are included, ready to be used as defaults
+Dir[File.join(File.dirname(__FILE__), 'attributes', '*.rb')].sort.each { |file| require file }
+
+module ExperianConsumerView
+  module Transformers
+    # Default implementation of a class to transform the raw result returned by the ConsumerView API into a richer
+    # format. It does this by registering one or more attribute transformers, and iterating over the key/value pairs in
+    # the result hash, applying the attribute transformers to the appropriate values.
+    #
+    # You may provide your own custom implementations which transform the result hash in any way you wish. The only
+    # requirement is implementing the +transform+ method.
+    class ResultTransformer
+      def initialize
+        @attribute_transformers = {}
+      end
+
+      # Registers an attribute transformer on this +ResultTransformer+.
+      #
+      # An attribute transformer must implement:
+      # - +attribute_name+ - returns the name of an attribute, as returned by the ConsumerView API, which it can
+      #     transform.
+      # - +transform_attribute+ - accepts a value for the given attribute as returned by the ConsumerView API, and
+      #     transforms it in some way - usually into a richer data format.
+      #
+      # @param transformer
+      def register_attribute_transformer(transformer)
+        @attribute_transformers[transformer.attribute_name] = transformer
+      end
+
+      # Transforms all values in the given +result_hash+ using the registered attribute transformers. If there is no
+      # attribute transformer for a particular key in the +result_hash+ then the associated value will not be
+      # transformed.
+      #
+      # @param result_hash [Hash] the raw result hash from the ConsumerView API for a single item which was looked up -
+      #   eg. a single individual, household, or postcode.
+      #
+      # @returns [Hash] the transformed hash of result data
+      def transform(result_hash)
+        result_hash.each do |k, v|
+          result_hash[k] = @attribute_transformers[k].transform_attribute(v) if @attribute_transformers[k]
+        end
+      end
+
+      ################################################
+      ### Helper code to get a default Transformer ###
+      ################################################
+      DEFAULT_ATTRIBUTE_TRANSFORMERS = [
+        ExperianConsumerView::Transformers::Attributes::Match,
+        ExperianConsumerView::Transformers::Attributes::PostcodeMosaicUk7Group,
+        ExperianConsumerView::Transformers::Attributes::PostcodeMosaicUk7Type
+      ].freeze
+
+      # Class instance variable
+      @default_transformer = nil
+
+      def self.default
+        unless @default_transformer
+          @default_transformer = ResultTransformer.new
+
+          DEFAULT_ATTRIBUTE_TRANSFORMERS.each { |t| @default_transformer.register_attribute_transformer(t) }
+        end
+
+        @default_transformer
+      end
+    end
+  end
+end

data/lib/experian_consumer_view/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ExperianConsumerView
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,211 @@
+--- !ruby/object:Gem::Specification
+name: experian_consumer_view
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Andrew Sibley
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-12-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.91.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.91.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.25
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.25
+description: "\n    Experian's ConsumerView API is a commercially licensed API which
+  allows you\n    to obtain various demographic data on UK consumers at the postcode,
+  household,\n    and individual level. This gem provides a simple Ruby wrapper to
+  use the API.\n  "
+email:
+- andrew.s@38degrees.org.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- experian_consumer_view.gemspec
+- lib/experian_consumer_view.rb
+- lib/experian_consumer_view/api.rb
+- lib/experian_consumer_view/client.rb
+- lib/experian_consumer_view/constants.rb
+- lib/experian_consumer_view/errors.rb
+- lib/experian_consumer_view/transformers/attributes/base.rb
+- lib/experian_consumer_view/transformers/attributes/match.rb
+- lib/experian_consumer_view/transformers/attributes/postcode_mosaic_uk_7_group.rb
+- lib/experian_consumer_view/transformers/attributes/postcode_mosaic_uk_7_type.rb
+- lib/experian_consumer_view/transformers/no_op_transformer.rb
+- lib/experian_consumer_view/transformers/result_transformer.rb
+- lib/experian_consumer_view/version.rb
+homepage: https://github.com/38degrees/experian_consumer_view
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.6
+signing_key: 
+specification_version: 4
+summary: Ruby wrapper for Experian's ConsumerView API.
+test_files: []