adapi 0.0.7 → 0.0.8

data/README.markdown

@@ -159,10 +159,12 @@ Adapi::Config.set(:sandbox)
 
 ## API Version Support ##
 
-Adapi 0.0.5 and higher supports only the latest version of Google AdWords API: *v201109*
+Adapi does not support several AdWords API versions at the same time, only the
+latest version: *v201109_1* at the moment.
 
-Older versions of adapi supporting older versions of AdWords API will still be
-available (adapi 0.0.4 supports only v201101), marked by AdWords API version tag.
+However, support for the older versions is still available in earlier versions
+of adapi (adapi 0.0.7 for *v201109*). Latest revision for specific AdWords API
+version is marked by a tag.
 
 ## Unsupported AdWords services ##
 
@@ -188,21 +190,235 @@ they will be implemented (this also serves as TODO list):
 
 ## Examples ##
 
-Example are available in [examples directory](./master/examples/). For now, they
+Examples are available in [examples directory](./master/examples/). For now, they
 are mostly just uninspired rewrites of examples from `google-adwords-api` gem,
 but that's going to change when proper UI to AdWords models will be implemented.
 
+### Getting started ###
+
+Here are some examples to get you started with adapi. (All this is also
+available in [examples directory](./master/examples/).)
+
+#### Create complete campaign ###
+
+Creates a campaign with ad_groups and ad_texts from hash - by single method call.
+
+```ruby
+campaign = Adapi::Campaign.create(
+  :name => "Campaign #%d" % (Time.new.to_f * 1000).to_i,
+  :status => 'PAUSED',
+  :bidding_strategy => {
+    :xsi_type => 'BudgetOptimizer',
+    :bid_ceiling => 100
+  },
+  :budget => {
+    :amount => 50,
+    :delivery_method => 'STANDARD'
+  },
+
+  :criteria => {
+    :language => [ :en, :cs ],
+    :location => {
+      # PS: province and country codes are now obsolete in AdWords API,
+      # but they still work in adapi
+      :name => { :city => 'Prague', :region => 'CZ-PR', :country => 'CZ' }
+    }
+  },
+
+  :ad_groups => [
+    {
+      :name => "AdGroup #%d" % (Time.new.to_f * 1000).to_i,
+      :status => 'ENABLED',
+
+      :keywords => [ 'dem codez', '"top coder"', "[-code]" ],
+
+      :ads => [
+        {
+          :headline => "Code like Neo",
+          :description1 => 'Need mad coding skills?',
+          :description2 => 'Check out my new blog!',
+          :url => 'http://www.demcodez.com',
+          :display_url => 'http://www.demcodez.com'
+        }
+      ]
+    }
+  ]
+)
+```
+
+#### Create campaign step by step ###
+
+Creates a campaign with ad_groups and ad_texts step by step.
+
+```ruby
+campaign = Adapi::Campaign.create(
+  :name => "Campaign #%d" % (Time.new.to_f * 1000).to_i,
+  :status => 'PAUSED',
+  :bidding_strategy => { :xsi_type => 'BudgetOptimizer', :bid_ceiling => 100 },
+  :budget => { :amount => 50, :delivery_method => 'STANDARD' }
+)
+
+Adapi::CampaignCriterion.create(
+  :campaign_id => campaign.id,
+  :criteria => { 
+    :language => %w{ en cs },
+    :location => {
+      :name => { :city => 'Prague', :region => 'CZ-PR', :country => 'CZ' }
+    }
+  }
+)
+
+ad_group = Adapi::AdGroup.create(
+  :campaign_id => campaign.id,
+  :name => "AdGroup #%d" % (Time.new.to_f * 1000).to_i,
+  :status => 'ENABLED'
+)
+
+Adapi::Keyword.create(
+  :ad_group_id => ad_group.id,
+  :keywords => [ 'dem codez', '"top coder"', '[-code]' ]
+)
+
+Adapi::Ad::TextAd.create(
+  :ad_group_id => ad_group.id,
+  :headline => "Code like Neo",
+  :description1 => 'Need mad coding skills?',
+  :description2 => 'Check out my new blog!',
+  :url => 'http://www.demcodez.com',
+  :display_url => 'http://www.demcodez.com'
+)
+
+# find complete campaign
+new_campaign = Adapi::Campaign.find_complete(campaign.id)
+
+# display campaign as hash
+puts new_campaign.to_hash.inspect
+```
+
+#### Create campaign criteria ###
+
+Campaign criteria (formerly targets) have been rewritten from the scratch for
+*v201109*. The goal is to provide a simple DSL for criteria so user doesn't have
+to deal with somewhat convoluted AdWords API syntax made for machines, not
+humans. So far, this has been done only for *language* and *location* criterion.
+You can use any other criteria, you just have to enter them in AdWords format.
+
+##### Language #####
+
+```ruby
+Adapi::CampaignCriterion.create(
+  :campaign_id => campaign.id,
+  :criteria => { 
+    :language => %w{ en cs },
+  }
+)
+```
+
+`:language` parameter accepts string or symbols for single language target or
+array of strings/symbols for several language targets.
+
+##### Location #####
+
+```ruby
+Adapi::CampaignCriterion.create(
+  :campaign_id => campaign.id,
+  :criteria => { 
+    :location => { 
+      :name => { :city => 'Prague', :region => 'CZ-PR', :country => 'CZ' }
+    }    
+)
+
+```
+
+This criterion has been heavily customized in adapi to comply with legacy
+interfaces (pre-v201109). In other words, you don't have to enter locations as
+ids (although you can). `:location` accepts following parameters:
+
+* `:id` - this is standard location interface of AdWords `v201109_1`
+
+```ruby
+:location => location_id
+:location => { :id => location_id }
+:location => { :id => [ location_id ] }
+```
+
+* `:proximity`
+  * `:geo_point`: "longitude,lattitude"
+  * `:radius`: "radius_in_units radius_units"
+
+```ruby
+:location => { :proximity => { :geo_point => '50.083333,14.366667', :radius => '50 km' } }
+```
+
+* `:name` - hash with parameters specifying location name:
+  * `:city`
+  * `:region` (also `:province`) - as name (`"New York"`) or code (`"US-NY"`)
+  * `:country` - as name (`"Czech Republic"`) or code (`"CZ"`)
+
+```ruby
+:location => { :name => { :country => 'Czech Republic' } }
+:location => { :name => { :city => 'Prague' } }
+:location => { :name => { :city => 'Prague', :region => 'CZ-PR', :country => 'CZ' } }
+```
+
+Unfortunately, at the moment you can't target more locations in one
+CampaignCriterion request. This is going to be fixed in the next version, but
+for now please use following workaround - call CampaignCriterion several times:
+
+```ruby
+Adapi::CampaignCriterion.create(
+  :campaign_id => campaign.id,
+  :criteria => { 
+    :location => { 
+      :name => { :city => 'Prague', :region => 'CZ-PR', :country => 'CZ' }
+    }    
+)
+
+Adapi::CampaignCriterion.create(
+  :campaign_id => campaign.id,
+  :criteria => { 
+    :location => {
+      :name => { :city => 'Brno', :region => 'CZ-JM', :country => 'CZ' }
+    }
+  }
+)
+```
+
+##### Criterion in AdWords format #####
+
+Convenient shortcuts for other criteria besides *language* and *location* are
+not yet implemented. However, you can use any other criteria, you just have to
+enter them as ids.
+
+```ruby
+Adapi::CampaignCriterion.create(
+  :campaign_id => campaign.id,
+  :criteria => {
+    :platform => [ { :id => 30001} ]
+  }
+)
+```
+
 ## Logging ##
 
-*STILL IN BETA* By default, nothing is logged. If you set `library/log_level` in
-configuration, SOAP messages will be logged to `~/adapi.log` file according to
-give log level.
+By default, communication with AdWords API is not logged. In order to log
+messages of certain log level or above, set `library/log_level` in configuration
+(INFO or DEBUG setting is recommended for local development).
+
+Default log path is "~/adapi.log". You can set custom log path in:
+`library/log_path`.
+
+By default, SOAP messages are logged in ugly format - everything fits on single
+line. It's fast, but quite difficult to read. To log SOAP requests and responses
+in pretty format, set `library/log_pretty_format` in configuration to `true`.
 
 Example of logger configuration:
 
 ```
   :library:
     :log_level: DEBUG
+    :log_path: /home/username/log/adapi.log
+    :log_pretty_format: true
 ```
 
 ## Author ##

data/adapi.gemspec

@@ -27,20 +27,20 @@ Gem::Specification.new do |s|
   # PS: versions are freezed because both of these gems change a lot and
   # automatic updates through '~>' can (and already did) break something
   #
-  s.add_dependency "google-ads-common", "0.6.3"
-  s.add_dependency "google-adwords-api", "0.5.2"
+  s.add_dependency "google-ads-common", "0.7.0"
+  s.add_dependency "google-adwords-api", "0.6.0"
 
   s.add_dependency "activemodel", "~> 3.1"
   s.add_dependency "activesupport", "~> 3.1"
   s.add_dependency "rake", "~> 0.9.2"
-  s.add_dependency "curb", "~> 0.7"
+  s.add_dependency "curb", "~> 0.8.0"
 
   s.add_development_dependency "yard", "~> 0.7"
   s.add_development_dependency "rcov", "~> 0.9"
   s.add_development_dependency "turn", "0.8.2" # PS: 0.8.3 is broken
   s.add_development_dependency "shoulda"
   s.add_development_dependency "fakeweb"
-  s.add_development_dependency "factory_girl"
+  s.add_development_dependency "factory_girl", "~> 3.3.0"
   s.add_development_dependency "minitest"
 
 end

data/lib/adapi.rb

@@ -25,20 +25,23 @@ require 'adapi/ad_param'
 require 'adapi/constant_data'
 require 'adapi/constant_data/language'
 require 'adapi/constant_data/country'
+require 'adapi/constant_data/province'
 require 'adapi/location'
 
-# monkeypatch HTTPI - important, check the file!
-require 'httpi_request_monkeypatch'
+# monkeypatch that hardcodes HTTP timeout to 5 minutes
+require 'httpi_monkeypatch'
 
-# I can haz hack?! This hotfixes OAuth
-# will be removed when new version of ads-common is released
-require 'ads_common_monkeypatch'
+# optional monkeypatch that saves SOAP in Savon log in pretty format
+# doesn't save SOAP in pretty format by default (it's faster)
+if (Adapi::Config.read[:library][:log_pretty_format] rescue false)
+  require 'savon_monkeypatch'
+end
 
 HTTPI.adapter = :curb
 HTTPI.log = false # supress HTTPI output
 
 module Adapi
-  API_VERSION = :v201109  
+  API_VERSION = :v201109_1
 end
 
 if RUBY_VERSION < '1.9'

data/lib/adapi/api.rb

@@ -8,6 +8,8 @@ module Adapi
     include ActiveModel::Conversion
     # TODO include ActiveModel::Dirty
 
+    LOGGER = Config.setup_logger
+
     attr_accessor :adwords, :service, :version, :params,
       :id, :status, :xsi_type
 
@@ -20,22 +22,13 @@ module Adapi
 
       raise "Missing Service Name" unless params[:service_name]
 
-      puts "\n\nEXISTING INSTANCE USED\n\n" if params[:adwords_api_instance]
-
       # if params[:api_login] in nil, default login data are used
       # from ~/adwords_api.yml
       @adwords = params[:adwords_api_instance] || AdwordsApi::Api.new(Adapi::Config.read)
+      @adwords.logger = LOGGER if LOGGER
       @version = API_VERSION
       @service = @adwords.service(params[:service_name].to_sym, @version)
       @params = params
-
-      # TODO add switched for logging (true/false) and log location
-      log_level = Adapi::Config.read[:library][:log_level] rescue nil
-      if log_level
-        logger = Logger.new( File.join(ENV['HOME'], (params[:logfile] || 'adapi.log')) )
-        logger.level = eval("Logger::%s" % Adapi::Config.read[:library][:log_level].to_s.upcase)
-        @adwords.logger = logger
-      end
     end
 
     def to_param

data/lib/adapi/campaign_criterion.rb

@@ -47,7 +47,7 @@ module Adapi
       @criteria.each_pair do |criterion_type, criterion_settings|
         case criterion_type
           when :language
-            criterion_settings.each do |value|
+            Array(criterion_settings).each do |value|
               criteria_array << [criterion_type, value]
             end
 

data/lib/adapi/config.rb

@@ -14,6 +14,8 @@ module Adapi
     self.dir = ENV['HOME']
     self.filename = 'adapi.yml'
 
+    DEFAULT_LOG_PATH = File.join(ENV['HOME'], 'adapi.log')
+
     # display hash of all account settings
     #
     def self.settings(reload = false)
@@ -70,5 +72,26 @@ module Adapi
 
       @settings
     end
+
+    # Returns complete path to log file - both directory and file name.
+    #
+    def self.log_path
+      (Adapi::Config.read[:library][:log_path] rescue nil) || DEFAULT_LOG_PATH 
+    end
+
+    # Returns freshly initialized logger object (or nil, if not available)
+    #
+    def self.setup_logger
+      log_level = self.read[:library][:log_level] rescue nil
+
+      if log_level
+        logger = Logger.new(self.log_path)
+        logger.level = eval("Logger::%s" % log_level.to_s.upcase)
+        logger
+      else
+        nil
+      end
+    end
+    
   end
 end

data/lib/adapi/constant_data/province.rb

@@ -0,0 +1,1128 @@
+# encoding: utf-8
+
+# this is hack for backward compatibility with old province names
+# should be temporary, until I figure out better solution
+
+module Adapi
+  class ConstantData::Location < ConstantData
+    class Province
+
+      PROVINCES = [
+        ["Buenos Aires","AR-B","20009"],
+        ["Capital Federal","AR-C","20010"],
+        ["Catamarca","AR-K","20015"],
+        ["Chaco","AR-H","20013"],
+        ["Chubut","AR-U","20023"],
+        ["Cordoba","AR-X","20026"],
+        ["Corrientes","AR-W","20025"],
+        ["Entre Rios","AR-E","20011"],
+        ["Formosa","AR-P","21299"],
+        ["Jujuy","AR-Y","20027"],
+        ["La Pampa","AR-L","20016"],
+        ["La Rioja","AR-F","20012"],
+        ["Mendoza","AR-M","20017"],
+        ["Misiones","AR-N","20018"],
+        ["Neuquen","AR-Q","20019"],
+        ["Rio Negro","AR-R","20020"],
+        ["Salta","AR-A","20008"],
+        ["San Juan","AR-J","20014"],
+        ["San Luis","AR-D","21297"],
+        ["Santa Cruz","AR-Z","20028"],
+        ["Santa Fe","AR-S","20021"],
+        ["Santiago del Estero","AR-G","21298"],
+        ["Tierra del Fuego","AR-V","20024"],
+        ["Tucuman","AR-T","20022"],
+        ["Australian Capital Territory","AU-ACT","20034"],
+        ["New South Wales","AU-NSW","20035"],
+        ["Northern Territory","AU-NT","20036"],
+        ["Queensland","AU-QLD","20037"],
+        ["South Australia","AU-SA","20038"],
+        ["Tasmania","AU-TAS","20039"],
+        ["Victoria","AU-VIC","20040"],
+        ["Western Australia","AU-WA","20041"],
+        ["Burgenland","AT-1","20042"],
+        ["Carinthia","AT-2","20043"],
+        ["Lower Austria","AT-3","20044"],
+        ["Salzburg","AT-5","20046"],
+        ["Styria","AT-6","20047"],
+        ["Tyrol","AT-7","20048"],
+        ["Upper Austria","AT-4","20045"],
+        ["Vienna","AT-9","20050"],
+        ["Vorarlberg","AT-8","20049"],
+        ["Antwerp","BE-VAN","20053"],
+        ["Brussels","BE-BRX","20052"],
+        ["East Flanders","BE-VOV","20056"],
+        ["Flemish Brabant","BE-VBR","20054"],
+        ["Hainaut","BE-WHT","20059"],
+        ["Liege","BE-WLG","20060"],
+        ["Limburg","BE-VLI","20055"],
+        ["Luxembourg","BE-WLX","20061"],
+        ["Namur","BE-WNA","20062"],
+        ["Walloon Brabant","BE-WBR","20058"],
+        ["West Flanders","BE-VWV","20057"],
+        ["Acre","BR-AC","21232"],
+        ["Alagoas","BR-AL","20086"],
+        ["Amapa","BR-AP","21226"],
+        ["Amazonas","BR-AM","20087"],
+        ["Bahia","BR-BA","20088"],
+        ["Ceara","BR-CE","20089"],
+        ["Espirito Santo","BR-ES","20091"],
+        ["Federal District","BR-DF","20090"],
+        ["Goias","BR-GO","20092"],
+        ["Maranhao","BR-MA","20093"],
+        ["Mato Grosso","BR-MT","20096"],
+        ["Mato Grosso do Sul","BR-MS","20095"],
+        ["Minas Gerais","BR-MG","20094"],
+        ["Para","BR-PA","20097"],
+        ["Paraiba","BR-PB","20098"],
+        ["Parana","BR-PR","20101"],
+        ["Pernambuco","BR-PE","20099"],
+        ["Piaui","BR-PI","20100"],
+        ["Rio de Janeiro","BR-RJ","20102"],
+        ["Rio Grande do Norte","BR-RN","20103"],
+        ["Rio Grande do Sul","BR-RS","20104"],
+        ["Rondonia","BR-RO","21227"],
+        ["Roraima","BR-RR","21228"],
+        ["Santa Catarina","BR-SC","20105"],
+        ["Sao Paulo","BR-SP","20106"],
+        ["Sergipe","BR-SE","21229"],
+        ["Tocantins","BR-TO","21230"],
+        ["Alberta","CA-AB","20113"],
+        ["British Columbia","CA-BC","20114"],
+        ["Manitoba","CA-MB","20115"],
+        ["New Brunswick","CA-NB","20116"],
+        ["Newfoundland","CA-NF","20117"],
+        ["Northwest Territories","CA-NT","20119"],
+        ["Nova Scotia","CA-NS","20118"],
+        ["Nunavut","CA-NU","20120"],
+        ["Ontario","CA-ON","20121"],
+        ["Prince Edward Island","CA-PE","20122"],
+        ["Quebec","CA-QC","20123"],
+        ["Saskatchewan","CA-SK","20124"],
+        ["Yukon Territory","CA-YT","20125"],
+        ["Antofagasta","CL-AN","20152"],
+        ["Araucanía","CL-AR","20153"],
+        ["Bío-Bío","CL-BI","20154"],
+        ["Coquimbo","CL-CO","20155"],
+        ["Libertador General Bernardo O'Higgins","CL-LI","20156"],
+        ["Los Lagos","CL-LL","20157"],
+        ["Magallanes","CL-MA","20158"],
+        ["Maule","CL-ML","20159"],
+        ["Region Metropolitana de Santiago","CL-RM","20160"],
+        ["Tarapacá","CL-TA","20161"],
+        ["Valparaíso","CL-VS","20162"],
+        ["Anhui","CN-34","20174"],
+        ["Beijing","CN-11","20163"],
+        ["Chongqing","CN-50","20184"],
+        ["Fujian","CN-35","20175"],
+        ["Gansu","CN-62","20190"],
+        ["Guangdong","CN-44","20181"],
+        ["Guangxi","CN-45","20182"],
+        ["Guizhou","CN-52","20186"],
+        ["Hainan","CN-46","20183"],
+        ["Hebei","CN-13","20165"],
+        ["Heilongjiang","CN-23","20170"],
+        ["Henan","CN-41","20178"],
+        ["Hubei","CN-42","20179"],
+        ["Hunan","CN-43","20180"],
+        ["Jiangsu","CN-32","20172"],
+        ["Jiangxi","CN-36","20176"],
+        ["Jilin","CN-22","20169"],
+        ["Liaoning","CN-21","20168"],
+        ["Nei Monggol","CN-15","20167"],
+        ["Ningxia","CN-64","20192"],
+        ["Qinghai","CN-63","20191"],
+        ["Shaanxi","CN-61","20189"],
+        ["Shandong","CN-37","20177"],
+        ["Shanghai","CN-31","20171"],
+        ["Shanxi","CN-14","20166"],
+        ["Sichuan","CN-51","20185"],
+        ["Tianjin","CN-12","20164"],
+        ["Xinjiang","CN-65","20193"],
+        ["Xizang","CN-54","20188"],
+        ["Yunnan","CN-53","20187"],
+        ["Zhejiang","CN-33","20173"],
+        ["Amazonas","CO-AMA","21506"],
+        ["Antioquia","CO-ANT","20198"],
+        ["Arauca","CO-ARA","21507"],
+        ["Atlantico","CO-ATL","20199"],
+        ["Bogota","CO-DC","20203"],
+        ["Bolivar","CO-BOL","20200"],
+        ["Boyaca","CO-BOY","21508"],
+        ["Caldas","CO-CAL","20201"],
+        ["Caqueta","CO-CAQ","21509"],
+        ["Casanare","CO-CAS","21510"],
+        ["Cauca","CO-CAU","21511"],
+        ["Cesar","CO-CES","21512"],
+        ["Choco","CO-CHO","21513"],
+        ["Cordoba","CO-COR","21514"],
+        ["Cundinamarca","CO-CUN","20202"],
+        ["Guainia","CO-GUA","21515"],
+        ["Guaviare","CO-GUV","21516"],
+        ["Huila","CO-HUI","20204"],
+        ["La Guajira","CO-LAG","21517"],
+        ["Magdalena","CO-MAG","21290"],
+        ["Meta","CO-MET","20205"],
+        ["Narino","CO-NAR","20206"],
+        ["Norte de Santander","CO-NSA","21518"],
+        ["Putumayo","CO-PUT","20207"],
+        ["Quindio","CO-QUI","21519"],
+        ["Risaralda","CO-RIS","20208"],
+        ["San Andres y Providencia","CO-SAP","21520"],
+        ["Santander","CO-SAN","20209"],
+        ["Sucre","CO-SUC","21521"],
+        ["Tolima","CO-TOL","20210"],
+        ["Valle del Cauca","CO-VAC","20211"],
+        ["Vaupes","CO-VAU","21522"],
+        ["Vichada","CO-VID","21523"],
+        ["Bjelovar and Bilogora","HR-07","21440"],
+        ["Dubrovnik and Neretva","HR-19","20413"],
+        ["Grad Zagreb","HR-21","21493"],
+        ["Istria","HR-18","21443"],
+        ["Karlovac","HR-04","21441"],
+        ["Koprivnica and Krizevaci","HR-06","21274"],
+        ["Krapina and Zagorje","HR-02","21489"],
+        ["Lika and Senj","HR-09","21490"],
+        ["Medjimurje","HR-20","21492"],
+        ["Osijek and Baranja","HR-14","20410"],
+        ["Pozega and Slavonia","HR-11","21442"],
+        ["Sibenik and Knin","HR-15","21444"],
+        ["Sisak and Moslavina","HR-03","21445"],
+        ["Slavonski Brod and Posavina","HR-12","21446"],
+        ["Split and Dalmatia","HR-17","20412"],
+        ["The Coast and Gorski Kotar","HR-08","20408"],
+        ["Varazdin","HR-05","21447"],
+        ["Virovitica and Podravina","HR-10","21491"],
+        ["Vukovar and Srijem","HR-16","20411"],
+        ["Zadar","HR-13","20409"],
+        ["Zagreb","HR-01","20407"],
+        ["Central Bohemia","CZ-ST","21494"],
+        ["Hradec Kralove","CZ-KR","21495"],
+        ["Karlovy Vary","CZ-KA","21496"],
+        ["Liberec","CZ-LI","21497"],
+        ["Moravian-Silesia","CZ-MO","21498"],
+        ["Olomouc","CZ-OL","21499"],
+        ["Pardubice","CZ-PA","21500"],
+        ["Pilsen","CZ-PL","21501"],
+        ["Prague","CZ-PR","21502"],
+        ["South Bohemia","CZ-JC","20218"],
+        ["South Moravia","CZ-JM","20219"],
+        ["Usti nad Labem","CZ-US","21503"],
+        ["Vysocina","CZ-VY","21504"],
+        ["Zlinsky","CZ-ZL","21505"],
+        ["Aarhus","DK-070","20254"],
+        ["Bornholm","DK-040","20248"],
+        ["Copenhagen","DK-015","20243"],
+        ["Frederiksberg","DK-147","20257"],
+        ["Frederiksborg","DK-020","20244"],
+        ["Fyn","DK-042","20249"],
+        ["Nordjylland","DK-080","20256"],
+        ["Ribe","DK-055","20251"],
+        ["Ringkoebing","DK-065","20253"],
+        ["Roskilde","DK-025","20245"],
+        ["Soenderjylland","DK-050","20250"],
+        ["Storstroem","DK-035","20247"],
+        ["Vejle","DK-060","20252"],
+        ["Vestsjaelland","DK-030","20246"],
+        ["Viborg","DK-076","20255"],
+        ["Ad Daqahliyah","EG-DK","21458"],
+        ["Al Bahr al Ahmar","EG-BA","21459"],
+        ["Al Buhayrah","EG-BH","21460"],
+        ["Al Fayyum","EG-FYM","21461"],
+        ["Al Gharbiyah","EG-GH","21462"],
+        ["Al Iskandariyah","EG-ALX","21463"],
+        ["Al Ismailiyah","EG-IS","21464"],
+        ["Al Jizah","EG-GZ","21465"],
+        ["Al Minufiyah","EG-MNF","21466"],
+        ["Al Minya","EG-MN","21467"],
+        ["Al Qahirah","EG-C","21468"],
+        ["Al Qalyubiyah","EG-KB","21469"],
+        ["Al Uqsur","EG-LX","21470"],
+        ["Al Wadi al Jadid","EG-WAD","21472"],
+        ["As Suways","EG-SUZ","21473"],
+        ["Ash Sharqiyah","EG-SHR","21474"],
+        ["Aswan","EG-ASN","21475"],
+        ["Asyut","EG-AST","21476"],
+        ["Bani Suwayf","EG-BNS","21477"],
+        ["Bur Said","EG-PTS","21478"],
+        ["Dumyat","EG-DT","21479"],
+        ["Janub Sina","EG-JS","21480"],
+        ["Kafr ash Shaykh","EG-KFS","21481"],
+        ["Matruh","EG-MT","21482"],
+        ["Qina","EG-KN","21483"],
+        ["Shamal Sina","EG-SIN","21484"],
+        ["Suhaj","EG-SHG","21485"],
+        ["The Province of Åland","FI-AL","20304"],
+        ["The Province of Eastern Finland","FI-IS","20306"],
+        ["The Province of Lapland","FI-LL","20307"],
+        ["The Province of Oulu","FI-OL","20309"],
+        ["The Province of Southern Finland","FI-ES","20305"],
+        ["The Province of Western Finland","FI-LS","20308"],
+        ["Alsace","FR-A","20311"],
+        ["Aquitaine","FR-B","20313"],
+        ["Auvergne","FR-C","20314"],
+        ["Brittany","FR-E","20316"],
+        ["Burgundy","FR-D","20315"],
+        ["Centre","FR-F","20317"],
+        ["Champagne-Ardenne","FR-G","20318"],
+        ["Corsica","FR-H","20319"],
+        ["Franche-Comte","FR-I","20320"],
+        ["Ile-de-France","FR-J","20321"],
+        ["Languedoc-Roussillon","FR-K","20322"],
+        ["Limousin","FR-L","20323"],
+        ["Lorraine","FR-M","20324"],
+        ["Midi-Pyrenees","FR-N","20325"],
+        ["Nord-Pas-de-Calais","FR-O","20326"],
+        ["Normandy - Lower","FR-P","20327"],
+        ["Normandy - Upper","FR-Q","20328"],
+        ["Pays de la Loire","FR-R","20329"],
+        ["Picardie","FR-S","20330"],
+        ["Poitou-Charentes","FR-T","20331"],
+        ["Provence-Alpes-Cote d'Azur","FR-U","20332"],
+        ["Rhône-Alpes","FR-V","20333"],
+        ["Baden-Württemberg","DE-BW","20228"],
+        ["Bayern","DE-BY","20229"],
+        ["Berlin","DE-BE","20226"],
+        ["Brandenburg","DE-BR","20227"],
+        ["Bremen","DE-HB","20230"],
+        ["Hamburg","DE-HH","20232"],
+        ["Hessen","DE-HE","20231"],
+        ["Mecklenburg-Vorpommern","DE-MV","20233"],
+        ["Niedersachsen","DE-NI","20234"],
+        ["Nordrhein-Westfalen","DE-NW","20235"],
+        ["Rheinland-Pfalz","DE-RP","20236"],
+        ["Saarland","DE-SL","20238"],
+        ["Sachsen","DE-SN","20239"],
+        ["Sachsen-Anhalt","DE-ST","20240"],
+        ["Schleswig-Holstein","DE-SH","20237"],
+        ["Thüringen","DE-TH","20241"],
+        ["Bacs-Kiskun","HU-BK","20417"],
+        ["Baranya","HU-BA","20415"],
+        ["Bekes","HU-BE","20416"],
+        ["Borsod-Abauj-Zemplen","HU-BZ","20419"],
+        ["Budapest","HU-BU","20418"],
+        ["Csongrad","HU-CS","20420"],
+        ["Fejer","HU-FE","20421"],
+        ["Gyor-Moson-Sopron","HU-GS","20422"],
+        ["Hajdu-Bihar","HU-HB","20424"],
+        ["Heves","HU-HE","20425"],
+        ["Jasz-Nagykun-Szolnok","HU-JN","20426"],
+        ["Komarom-Esztergom","HU-KE","20427"],
+        ["Nograd","HU-NO","20428"],
+        ["Pest","HU-PE","20429"],
+        ["Somogy","HU-SO","20430"],
+        ["Szabolcs-Szatmar-Bereg","HU-SZ","20431"],
+        ["Tolna","HU-TO","20432"],
+        ["Vas","HU-VA","20433"],
+        ["Veszprem","HU-VE","20434"],
+        ["Zala","HU-ZA","20435"],
+        ["Andaman and Nicobar Islands","IN-AN","20452"],
+        ["Andhra Pradesh","IN-AP","20453"],
+        ["Arunachal Pradesh","IN-AR","21289"],
+        ["Assam","IN-AS","20454"],
+        ["Bihar","IN-BR","20455"],
+        ["Chandigarh","IN-CH","21342"],
+        ["Chhattisgarh","IN-CT","21334"],
+        ["Dadar and Nagar Haveli","IN-DN","21343"],
+        ["Daman and Diu","IN-DD","21344"],
+        ["Delhi","IN-DL","20456"],
+        ["Goa","IN-GA","21268"],
+        ["Gujarat","IN-GJ","20457"],
+        ["Haryana","IN-HR","20458"],
+        ["Himachal Pradesh","IN-HP","21335"],
+        ["Jammu and Kashmir","IN-JK","20459"],
+        ["Jharkhand","IN-JH","21336"],
+        ["Karnataka","IN-KA","20460"],
+        ["Kerala","IN-KL","20461"],
+        ["Lakshadweep","IN-LD","21345"],
+        ["Madhya Pradesh","IN-MP","20464"],
+        ["Maharashtra","IN-MH","20462"],
+        ["Manipur","IN-MN","21337"],
+        ["Meghalaya","IN-ML","20463"],
+        ["Mizoram","IN-MZ","21338"],
+        ["Nagaland","IN-NL","21339"],
+        ["Orissa","IN-OR","20465"],
+        ["Pondicherry","IN-PY","20467"],
+        ["Punjab","IN-PB","20466"],
+        ["Rajasthan","IN-RJ","20468"],
+        ["Sikkim","IN-SK","21340"],
+        ["Tamil Nadu","IN-TN","20469"],
+        ["Tripura","IN-TR","20470"],
+        ["Uttar Pradesh","IN-UP","20471"],
+        ["Uttaranchal","IN-UL","21341"],
+        ["West Bengal","IN-WB","20472"],
+        ["Carlow","IE-CW","20477"],
+        ["Cavan","IE-CN","20476"],
+        ["Clare","IE-CE","20475"],
+        ["Cork","IE-C","20474"],
+        ["Donegal","IE-DL","20479"],
+        ["Dublin","IE-D","20478"],
+        ["Galway","IE-G","20480"],
+        ["Kerry","IE-KY","20483"],
+        ["Kildare","IE-KE","20481"],
+        ["Kilkenny","IE-KK","20482"],
+        ["Laois","IE-LS","20486"],
+        ["Leitrim","IE-LM","21317"],
+        ["Limerick","IE-LK","20485"],
+        ["Longford","IE-LD","21316"],
+        ["Louth","IE-LH","20484"],
+        ["Mayo","IE-MO","20489"],
+        ["Meath","IE-MH","20487"],
+        ["Monaghan","IE-MN","20488"],
+        ["Offaly","IE-OY","20490"],
+        ["Roscommon","IE-RN","20491"],
+        ["Sligo","IE-SO","20492"],
+        ["Tipperary","IE-TA","20493"],
+        ["Waterford","IE-WD","20494"],
+        ["Westmeath","IE-WH","20495"],
+        ["Wexford","IE-WX","20497"],
+        ["Wicklow","IE-WW","20496"],
+        ["HaDarom","IL-D","20514"],
+        ["HaMerkaz","IL-M","20517"],
+        ["HaZafon","IL-Z","20519"],
+        ["Hefa","IL-HA","20515"],
+        ["Tel-Aviv","IL-TA","20518"],
+        ["Yerushalayim Al Quds","IL-JM","20516"],
+        ["Agrigento","IT-AG","20520"],
+        ["Alessandria","IT-AL","20521"],
+        ["Ancona","IT-AN","20522"],
+        ["Aosta","IT-AO","20523"],
+        ["Arezzo","IT-AR","20526"],
+        ["Ascoli Piceno","IT-AP","20524"],
+        ["Asti","IT-AT","20527"],
+        ["Avellino","IT-AV","20528"],
+        ["Bari","IT-BA","20529"],
+        ["Belluno","IT-BL","20532"],
+        ["Benevento","IT-BN","20533"],
+        ["Bergamo","IT-BG","20530"],
+        ["Biella","IT-BI","20531"],
+        ["Bologna","IT-BO","20534"],
+        ["Bolzano","IT-BZ","20537"],
+        ["Brescia","IT-BS","20536"],
+        ["Brindisi","IT-BR","20535"],
+        ["Cagliari","IT-CA","20538"],
+        ["Caltanissetta","IT-CL","20542"],
+        ["Campobasso","IT-CB","20539"],
+        ["Caserta","IT-CE","20540"],
+        ["Catania","IT-CT","20547"],
+        ["Catanzaro","IT-CZ","20548"],
+        ["Chieti","IT-CH","20541"],
+        ["Como","IT-CO","20544"],
+        ["Cosenza","IT-CS","20546"],
+        ["Cremona","IT-CR","20545"],
+        ["Crotone","IT-KR","20560"],
+        ["Cuneo","IT-CN","20543"],
+        ["Enna","IT-EN","20549"],
+        ["Ferrara","IT-FE","20550"],
+        ["Florence","IT-FI","20552"],
+        ["Foggia","IT-FG","20551"],
+        ["Forlì-Cesena","IT-FO","20553"],
+        ["Frosinone","IT-FR","20554"],
+        ["Genoa","IT-GE","20555"],
+        ["Gorizia","IT-GO","20556"],
+        ["Grosseto","IT-GR","20557"],
+        ["Imperia","IT-IM","20558"],
+        ["Isernia","IT-IS","20559"],
+        ["L'Aquila","IT-AQ","20525"],
+        ["La Spezia","IT-SP","20602"],
+        ["Latina","IT-LT","20565"],
+        ["Lecce","IT-LE","20562"],
+        ["Lecco","IT-LC","20561"],
+        ["Livorno","IT-LI","20563"],
+        ["Lodi","IT-LO","20564"],
+        ["Lucca","IT-LU","20566"],
+        ["Macerata","IT-MC","20567"],
+        ["Mantua","IT-MN","20570"],
+        ["Massa","IT-MS","20572"],
+        ["Matera","IT-MT","20573"],
+        ["Messina","IT-ME","20568"],
+        ["Milan","IT-MI","20569"],
+        ["Modena","IT-MO","20571"],
+        ["Naples","IT-NA","20574"],
+        ["Novara","IT-NO","20575"],
+        ["Nuoro","IT-NU","20576"],
+        ["Oristano","IT-OR","20577"],
+        ["Padua","IT-PD","20580"],
+        ["Palermo","IT-PA","20578"],
+        ["Parma","IT-PR","20586"],
+        ["Pavia","IT-PV","20589"],
+        ["Perugia","IT-PG","20582"],
+        ["Pesaro","IT-PS","20587"],
+        ["Pescara","IT-PE","20581"],
+        ["Piacenza","IT-PC","20579"],
+        ["Pisa","IT-PI","20583"],
+        ["Pistoia","IT-PT","20588"],
+        ["Pordenone","IT-PN","20584"],
+        ["Potenza","IT-PZ","20590"],
+        ["Prato","IT-PO","20585"],
+        ["Ragusa","IT-RG","20594"],
+        ["Ravenna","IT-RA","20591"],
+        ["Reggio Calabria","IT-RC","20592"],
+        ["Reggio Emilia","IT-RE","20593"],
+        ["Rieti","IT-RI","20595"],
+        ["Rimini","IT-RN","20597"],
+        ["Rome","IT-RM","20596"],
+        ["Rovigo","IT-RO","20598"],
+        ["Salerno","IT-SA","20599"],
+        ["Sassari","IT-SS","20604"],
+        ["Savona","IT-SV","20605"],
+        ["Siena","IT-SI","20600"],
+        ["Siracusa","IT-SR","20603"],
+        ["Sondrio","IT-SO","20601"],
+        ["Taranto","IT-TA","20606"],
+        ["Teramo","IT-TE","20607"],
+        ["Terni","IT-TR","20611"],
+        ["Torino","IT-TO","20609"],
+        ["Trapani","IT-TP","20610"],
+        ["Trento","IT-TN","20608"],
+        ["Treviso","IT-TV","20613"],
+        ["Trieste","IT-TS","20612"],
+        ["Udine","IT-UD","20614"],
+        ["Varese","IT-VA","20615"],
+        ["Venice","IT-VE","20618"],
+        ["Verbano-Cusio-Ossola","IT-VB","20616"],
+        ["Vercelli","IT-VC","20617"],
+        ["Verona","IT-VR","20620"],
+        ["Vibo Valentia","IT-VV","21233"],
+        ["Vicenza","IT-VI","20619"],
+        ["Viterbo","IT-VT","20621"],
+        ["Aichi","JP-23","20646"],
+        ["Akita","JP-05","20628"],
+        ["Aomori","JP-02","20625"],
+        ["Chiba","JP-12","20635"],
+        ["Ehime","JP-38","20661"],
+        ["Fukui","JP-18","20641"],
+        ["Fukuoka","JP-40","20663"],
+        ["Fukushima","JP-07","20630"],
+        ["Gifu","JP-21","20644"],
+        ["Gunma","JP-10","20633"],
+        ["Hiroshima","JP-34","20657"],
+        ["Hokkaido","JP-01","20624"],
+        ["Hyogo","JP-28","20651"],
+        ["Ibaraki","JP-08","20631"],
+        ["Ishikawa","JP-17","20640"],
+        ["Iwate","JP-03","20626"],
+        ["Kagawa","JP-37","20660"],
+        ["Kagoshima","JP-46","20669"],
+        ["Kanagawa","JP-14","20637"],
+        ["Kochi","JP-39","20662"],
+        ["Kumamoto","JP-43","20666"],
+        ["Kyoto","JP-26","20649"],
+        ["Mie","JP-24","20647"],
+        ["Miyagi","JP-04","20627"],
+        ["Miyazaki","JP-45","20668"],
+        ["Nagano","JP-20","20643"],
+        ["Nagasaki","JP-42","20665"],
+        ["Nara","JP-29","20652"],
+        ["Niigata","JP-15","20638"],
+        ["Oita","JP-44","20667"],
+        ["Okayama","JP-33","20656"],
+        ["Okinawa","JP-47","20670"],
+        ["Osaka","JP-27","20650"],
+        ["Saga","JP-41","20664"],
+        ["Saitama","JP-11","20634"],
+        ["Shiga","JP-25","20648"],
+        ["Shimane","JP-32","20655"],
+        ["Shizuoka","JP-22","20645"],
+        ["Tochigi","JP-09","20632"],
+        ["Tokushima","JP-36","20659"],
+        ["Tokyo","JP-13","20636"],
+        ["Tottori","JP-31","20654"],
+        ["Toyama","JP-16","20639"],
+        ["Wakayama","JP-30","20653"],
+        ["Yamagata","JP-06","20629"],
+        ["Yamaguchi","JP-35","20658"],
+        ["Yamanashi","JP-19","20642"],
+        ["Federal Territory of Kuala Lumpur","MY-14","20751"],
+        ["Federal Territory of Putrajaya","MY-16","21539"],
+        ["Johor","MY-01","20741"],
+        ["Kedah","MY-02","20742"],
+        ["Kelantan","MY-03","20740"],
+        ["Melaka","MY-04","20744"],
+        ["Negeri Sembilan","MY-05","20745"],
+        ["Pahang","MY-06","20739"],
+        ["Perak","MY-08","20737"],
+        ["Perlis","MY-09","20747"],
+        ["Pulau Pinang","MY-07","20746"],
+        ["Sabah","MY-12","20748"],
+        ["Sarawak","MY-13","20749"],
+        ["Selangor","MY-10","20738"],
+        ["Terengganu","MY-11","20750"],
+        ["Wilayah Persekutuan Labuan","MY-15","20743"],
+        ["Aguascalientes","MX-AGU","20694"],
+        ["Baja California","MX-BCN","20696"],
+        ["Baja California Sur","MX-BCS","20697"],
+        ["Campeche","MX-CAM","20698"],
+        ["Chiapas","MX-CHP","20700"],
+        ["Chihuahua","MX-CHH","20699"],
+        ["Coahuila","MX-COA","20701"],
+        ["Colima","MX-COL","20702"],
+        ["Distrito Federal","MX-DF","20703"],
+        ["Durango","MX-DUR","20704"],
+        ["Estado de México","MX-MEX","20709"],
+        ["Guanajuato","MX-GUA","20706"],
+        ["Guerrero","MX-GRO","20705"],
+        ["Hidalgo","MX-HID","20707"],
+        ["Jalisco","MX-JAL","20708"],
+        ["Michoacán","MX-MIC","20710"],
+        ["Morelos  ","MX-MOR","20711"],
+        ["Nayarit","MX-NAY","20712"],
+        ["Nuevo León","MX-NLE","20713"],
+        ["Oaxaca","MX-OAX","20714"],
+        ["Puebla","MX-PUE","20715"],
+        ["Querétaro ","MX-QUE","20716"],
+        ["Quintana Roo","MX-ROO","20717"],
+        ["San Luis Potosí","MX-SLP","20719"],
+        ["Sinaloa","MX-SIN","20718"],
+        ["Sonora","MX-SON","20720"],
+        ["Tabasco","MX-TAB","20721"],
+        ["Tamaulipas","MX-TAM","20722"],
+        ["Tlaxcala","MX-TLA","20723"],
+        ["Veracruz","MX-VER","20724"],
+        ["Yucatán","MX-YUC","20725"],
+        ["Zacatecas","MX-ZAC","20726"],
+        ["Chaouia-Ouardigha","MA-09","21524"],
+        ["Doukkala-Abda","MA-10","21525"],
+        ["Fes-Boulemane","MA-05","21526"],
+        ["Gharb-Chrarda-Beni Hssen","MA-02","21527"],
+        ["Grand Casablanca","MA-08","21528"],
+        ["Guelmim-Es Semara","MA-14","21529"],
+        ["Laayoune-Boujdour-Sakia El Hamra","MA-15","21530"],
+        ["Marrakech-Tensift-El Haouz","MA-11","21531"],
+        ["Meknes-Tafilalet","MA-06","21532"],
+        ["Oriental","MA-04","21533"],
+        ["Rabat-Sale-Zemmour-Zaer","MA-07","21534"],
+        ["Souss-Massa-Draa","MA-13","21535"],
+        ["Tadla-Azilal","MA-12","21536"],
+        ["Tanger-Tetouan","MA-01","21537"],
+        ["Taza-Al Hoceima-Taounate","MA-03","21538"],
+        ["Drenthe","NL-DR","20759"],
+        ["Flevopolder","NL-FL","20760"],
+        ["Friesland","NL-FR","20761"],
+        ["Gelderland","NL-GE","20762"],
+        ["Groningen","NL-GR","20763"],
+        ["Limburg","NL-LI","20764"],
+        ["Noord-Brabant","NL-NB","20765"],
+        ["Noord-Holland","NL-NH","20766"],
+        ["Overijssel","NL-OV","20767"],
+        ["Utrecht","NL-UT","20768"],
+        ["Zeeland","NL-ZE","20769"],
+        ["Zuid-Holland","NL-ZH","20770"],
+        ["Auckland","NZ-AUK","20791"],
+        ["Bay of Plenty","NZ-BOP","20792"],
+        ["Canterbury","NZ-CAN","21302"],
+        ["Gisborne","NZ-GIS","21303"],
+        ["Hawke's Bay","NZ-HKB","21304"],
+        ["Manawatu-Wanganui","NZ-MWT","21305"],
+        ["Marlborough","NZ-MBH","21306"],
+        ["Nelson","NZ-NSN","21307"],
+        ["Northland","NZ-NTL","21308"],
+        ["Otago","NZ-OTA","21309"],
+        ["Southland","NZ-STL","21310"],
+        ["Taranaki","NZ-TKI","21311"],
+        ["Tasman","NZ-TAS","21312"],
+        ["Waikato","NZ-WKO","21313"],
+        ["Wellington","NZ-WGN","21314"],
+        ["West Coast","NZ-WTC","21315"],
+        ["Abia","NG-AB","21540"],
+        ["Abuja Capital Territory","NG-FC","21541"],
+        ["Adamawa","NG-AD","21542"],
+        ["Akwa Ibom","NG-AK","21543"],
+        ["Anambra","NG-AN","21544"],
+        ["Bauchi","NG-BA","21545"],
+        ["Bayelsa","NG-BY","21546"],
+        ["Benue","NG-BE","21547"],
+        ["Borno","NG-BO","21548"],
+        ["Cross River","NG-CR","21549"],
+        ["Delta","NG-DE","21550"],
+        ["Ebonyi","NG-EB","21551"],
+        ["Edo","NG-ED","21552"],
+        ["Ekiti","NG-EK","21553"],
+        ["Enugu","NG-EN","21554"],
+        ["Gombe","NG-GO","21555"],
+        ["Imo","NG-IM","21556"],
+        ["Jigawa","NG-JI","21557"],
+        ["Kaduna","NG-KD","21558"],
+        ["Kano","NG-KN","21559"],
+        ["Katsina","NG-KT","21560"],
+        ["Kebbi","NG-KB","21561"],
+        ["Kogi","NG-KO","21562"],
+        ["Kwara","NG-KW","21563"],
+        ["Lagos","NG-LA","21564"],
+        ["Nasarawa","NG-NA","21565"],
+        ["Niger","NG-NI","21566"],
+        ["Ogun","NG-OG","21567"],
+        ["Ondo","NG-ON","21568"],
+        ["Osun","NG-OS","21569"],
+        ["Oyo","NG-OY","21570"],
+        ["Plateau","NG-PL","21571"],
+        ["Rivers","NG-RI","21572"],
+        ["Sokoto","NG-SO","21573"],
+        ["Taraba","NG-TA","21574"],
+        ["Yobe","NG-YO","21575"],
+        ["Zamfara","NG-ZA","21576"],
+        ["Akershus","NO-02","20772"],
+        ["Aust-Agder","NO-09","20779"],
+        ["Buskerud","NO-06","20776"],
+        ["Finnmark","NO-20","20789"],
+        ["Hedmark","NO-04","20774"],
+        ["Hordaland","NO-12","20782"],
+        ["Moere og Romsdal","NO-15","20784"],
+        ["Nord-Troendelag","NO-17","20786"],
+        ["Nordland","NO-18","20787"],
+        ["Oestfold","NO-01","20771"],
+        ["Oppland","NO-05","20775"],
+        ["Oslo","NO-03","20773"],
+        ["Rogaland","NO-11","20781"],
+        ["Soer-Troendelag","NO-16","20785"],
+        ["Sogn og Fjordane","NO-14","20783"],
+        ["Telemark","NO-08","20778"],
+        ["Troms","NO-19","20788"],
+        ["Vest-Agder","NO-10","20780"],
+        ["Vestfold","NO-07","20777"],
+        ["Dolnoslaskie","PL-DS","20847"],
+        ["Kujawsko-Pomorskie","PL-KP","20848"],
+        ["Lodzkie","PL-LD","20850"],
+        ["Lubelskie","PL-LU","20851"],
+        ["Lubuskie","PL-LB","20849"],
+        ["Malopolskie","PL-MA","20852"],
+        ["Mazowieckie","PL-MZ","20853"],
+        ["Opolskie","PL-OP","20854"],
+        ["Podkarpackie","PL-PK","20856"],
+        ["Podlaskie","PL-PD","20855"],
+        ["Pomorskie","PL-PM","20857"],
+        ["Slaskie","PL-SL","20859"],
+        ["Swietokrzyskie","PL-SK","20858"],
+        ["Warminsko-Mazurskie","PL-WN","20860"],
+        ["Wielkopolskie","PL-WP","20861"],
+        ["Zachodnio-Pomorskie","PL-ZP","20862"],
+        ["Aveiro","PT-01","20865"],
+        ["Évora","PT-07","20870"],
+        ["Beja","PT-02","21255"],
+        ["Braga","PT-03","20866"],
+        ["Bragança","PT-04","20867"],
+        ["Castelo Branco","PT-05","20868"],
+        ["Colmbra","PT-06","20869"],
+        ["Faro","PT-08","20871"],
+        ["Guarda","PT-09","20872"],
+        ["Leiria","PT-10","20873"],
+        ["Lisboa","PT-11","20874"],
+        ["Portalegre","PT-12","20875"],
+        ["Porto","PT-13","20876"],
+        ["Regiao AutOnoma da Madeira","PT-30","20882"],
+        ["Regiao Autonoma dos Açores","PT-20","20881"],
+        ["Santarém","PT-14","20877"],
+        ["Setúbal","PT-15","20878"],
+        ["Viana do Castelo","PT-16","20879"],
+        ["Viseu","PT-18","20880"],
+        ["Adygeya, Republic","RU-AD","21250"],
+        ["Aginskiy Buryatskiy avtonomnyy okrug","RU-AGB","21349"],
+        ["Altay, Republic","RU-AL","20914"],
+        ["Altayskiy kray","RU-ALT","21385"],
+        ["Amurskaya oblast","RU-AMU","20915"],
+        ["Arkhangel'skaya oblast","RU-ARK","20916"],
+        ["Astrakhanskaya oblast","RU-AST","20917"],
+        ["Bashkortostan, Republic","RU-BA","20918"],
+        ["Belgorodskaya oblast","RU-BEL","20919"],
+        ["Bryanskaya oblast","RU-BRY","20920"],
+        ["Buryatiya, Republic","RU-BU","20921"],
+        ["Chechnya, Republic","RU-CE","21347"],
+        ["Chelyabinskaya oblast","RU-CHE","20922"],
+        ["Chitinskaya oblast","RU-CHI","20923"],
+        ["Chukotskiy avtonomnyy okrug","RU-CHU","20924"],
+        ["Chuvashiya, Republic","RU-CU","21348"],
+        ["Dagestan, Republic","RU-DA","20925"],
+        ["Evenkiyskiy avtonomniy okrug","RU-EVE","21353"],
+        ["Ingushetiya, Republic","RU-IN","21251"],
+        ["Irkutskaya oblast","RU-IRK","20926"],
+        ["Ivanovskaya oblast","RU-IVA","20927"],
+        ["Kabardino-Balkariya, Republic","RU-KB","20929"],
+        ["Kaliningradskaya oblast","RU-KGD","20933"],
+        ["Kalmykiya, Republic","RU-KL","21243"],
+        ["Kaluzhskaya oblast","RU-KLU","20939"],
+        ["Kamchatskaya oblast","RU-KAM","20928"],
+        ["Karachayevo-Cherkessiya, Republic","RU-KC","20930"],
+        ["Kareliya, Republic","RU-KR","20942"],
+        ["Kemerovskaya oblast","RU-KEM","20932"],
+        ["Khabarovskiy kray","RU-KHA","20935"],
+        ["Khakasiya, Republic","RU-KK","20938"],
+        ["Khanty-Mansiyskiy avtonomnyy okrug","RU-KHM","20936"],
+        ["Kirovskaya oblast","RU-KIR","20937"],
+        ["Komi, Republic","RU-KO","20940"],
+        ["Koryakskiy avtonomniy okrug","RU-KOR","21350"],
+        ["Kostromskaya oblast","RU-KOS","20941"],
+        ["Krasnodarskiy kray","RU-KDA","20931"],
+        ["Krasnoyarskiy kray","RU-KYA","20944"],
+        ["Kurganskaya oblast","RU-KGN","20934"],
+        ["Kurskaya oblast","RU-KRS","20943"],
+        ["Leningradskaya oblast","RU-LEN","20945"],
+        ["Lipetskaya oblast","RU-LIP","20946"],
+        ["Magadanskaya oblast","RU-MAG","20947"],
+        ["Mariy El, Republic","RU-ME","21234"],
+        ["Mordoviya, Republic","RU-MO","20948"],
+        ["Moscow","RU-MOW","20950"],
+        ["Moskovskaya oblast","RU-MOS","20949"],
+        ["Murmanskaya oblast","RU-MUR","20951"],
+        ["Nenetskiy avtonomniy okrug","RU-NEN","21351"],
+        ["Nizhegorodskaya oblast","RU-NIZ","20953"],
+        ["Novgorodskaya oblast","RU-NGR","20952"],
+        ["Novosibirskaya oblast","RU-NVS","20954"],
+        ["Omskaya oblast","RU-OMS","20955"],
+        ["Orenburgskaya oblast","RU-ORE","20956"],
+        ["Orlovskaya oblast","RU-ORL","21256"],
+        ["Penzenskaya oblast","RU-PNZ","20958"],
+        ["Permskaya oblast","RU-PER","20957"],
+        ["Primorskiy kray","RU-PRI","20959"],
+        ["Pskovskaya oblast","RU-PSK","20960"],
+        ["Rostovskaya oblast","RU-ROS","20961"],
+        ["Ryazanskaya oblast","RU-RYA","20962"],
+        ["Sakha, Republic","RU-SA","20963"],
+        ["Sakhalinskaya oblast","RU-SAK","20964"],
+        ["Samarskaya oblast","RU-SAM","20965"],
+        ["Sankt-Petersburg","RU-SPE","20968"],
+        ["Saratovskaya oblast","RU-SAR","20966"],
+        ["Severnaya Osetiya, Republic","RU-SE","21252"],
+        ["Smolenskaya oblast","RU-SMO","20967"],
+        ["Stavropol'skiy kray","RU-STA","20969"],
+        ["Sverdlovskaya oblast","RU-SVE","20970"],
+        ["Tambovskaya oblast","RU-TAM","20972"],
+        ["Tatarstan, Republic","RU-TA","20971"],
+        ["Taymyrskiy (Dolgano-Nenetskiy) avtonomnyy okrug","RU-TAY","20973"],
+        ["Tomskaya oblast","RU-TOM","20974"],
+        ["Tul'skaya oblast","RU-TUL","20975"],
+        ["Tverskaya oblast","RU-TVE","20976"],
+        ["Tyumenskaya oblast","RU-TYU","20977"],
+        ["Tyva, Republic","RU-TY","21346"],
+        ["Udmurtiya, Republic","RU-UD","20978"],
+        ["Ulyanovskaya oblast","RU-ULY","20979"],
+        ["Ust'-Ordyniskiy Buryatskiy avtonomnyy okrug","RU-UOB","21352"],
+        ["Vladimirskaya oblast","RU-VLA","20981"],
+        ["Volgogradskaya oblast","RU-VGG","20980"],
+        ["Vologodskaya oblast","RU-VLG","20982"],
+        ["Voronezhskaya oblast","RU-VOR","20983"],
+        ["Yamalo-Nenetskiy avtonomnyy okrug","RU-YAN","20984"],
+        ["Yaroslavskaya oblast","RU-YAR","20985"],
+        ["Yevreyskaya avtonomnaya oblast","RU-YEV","21277"],
+        ["Al Bahah","SA-11","21455"],
+        ["Al Hudud ash Shamaliyah","SA-08","21452"],
+        ["Al Jawf","SA-12","21456"],
+        ["Al Madinah","SA-03","21448"],
+        ["Al Qasim","SA-05","21449"],
+        ["Ar Riyad","SA-01","20987"],
+        ["Ash Sharqiyah","SA-04","20989"],
+        ["Asir","SA-14","21457"],
+        ["Hail","SA-06","21450"],
+        ["Jizan","SA-09","21453"],
+        ["Makkah","SA-02","20988"],
+        ["Najran","SA-10","21454"],
+        ["Tabuk","SA-07","21451"],
+        ["Eastern Cape","ZA-EC","21214"],
+        ["Free State","ZA-FS","21215"],
+        ["Gauteng","ZA-GT","21216"],
+        ["Kwazulu-Natal","ZA-NL","21219"],
+        ["Mpumalanga","ZA-MP","21217"],
+        ["North-West","ZA-NW","21221"],
+        ["Northern Cape","ZA-NC","21218"],
+        ["Northern Province","ZA-NP","21220"],
+        ["Western Cape","ZA-WC","21222"],
+        ["Busan Metropolitan City","KR-26","21319"],
+        ["Chungcheongbuk-do","KR-43","21327"],
+        ["Chungcheongnam-do","KR-44","21328"],
+        ["Daegu Metropolitan City","KR-27","21320"],
+        ["Daejeon Metropolitan City","KR-30","21323"],
+        ["Gangwon-do","KR-42","21326"],
+        ["Gwangju Metropolitan City","KR-29","21322"],
+        ["Gyeonggi-do","KR-41","21325"],
+        ["Gyeongsangbuk-do","KR-47","21331"],
+        ["Gyeongsangnam-do","KR-48","21332"],
+        ["Incheon Metropolitan City","KR-28","21321"],
+        ["Jeju-do","KR-49","21333"],
+        ["Jeollabuk-do","KR-45","21329"],
+        ["Jeollanam-do","KR-46","21330"],
+        ["Seoul City","KR-11","21318"],
+        ["Ulsan Metropolitan City","KR-31","21324"],
+        ["Alava","ES-VI","20299"],
+        ["Alicante","ES-A","20267"],
+        ["Almería","ES-AL","20268"],
+        ["Andalucía","ES-AN","20269"],
+        ["Aragón","ES-AR","21386"],
+        ["Asturias","ES-O","20286"],
+        ["Balearic Islands","ES-PM","20287"],
+        ["Barcelona","ES-B","20270"],
+        ["Cadiz","ES-CA","20273"],
+        ["Canary Islands","ES-CN","20277"],
+        ["Cantabria","ES-S","20290"],
+        ["Castilla y León","ES-CL","20275"],
+        ["Castilla-La Mancha","ES-CM","20276"],
+        ["Cataluña","ES-CT","20278"],
+        ["Ceuta","ES-CE","20274"],
+        ["Extremadura","ES-EX","20279"],
+        ["Galicia","ES-GA","20280"],
+        ["Guipuzcoa","ES-SS","20293"],
+        ["Illes Balears","ES-IB","21387"],
+        ["La Coruna","ES-C","20272"],
+        ["La Rioja","ES-LO","20281"],
+        ["Madrid","ES-M","20282"],
+        ["Melilla","ES-ML","20283"],
+        ["Murcia","ES-MU","20284"],
+        ["Navarra","ES-NA","20285"],
+        ["País Vasco (Basque Country)","ES-PV","20289"],
+        ["Pontevedra","ES-PO","20288"],
+        ["Salamanca","ES-SA","20291"],
+        ["Santa Cruz De Tenerife","ES-TF","20295"],
+        ["Segovia","ES-SG","20292"],
+        ["Tarragona","ES-T","20294"],
+        ["Toledo","ES-TO","20296"],
+        ["Valencia","ES-V","20297"],
+        ["Valenciana, Comunidad","ES-VC","21388"],
+        ["Valladolid","ES-VA","20298"],
+        ["Vizcaya","ES-BI","20271"],
+        ["Zaragoza","ES-Z","20300"],
+        ["Blekinge lan","SE-K","21010"],
+        ["Dalarnas lan","SE-W","21017"],
+        ["Gavleborgs lan","SE-X","21018"],
+        ["Gotlands lan","SE-I","21009"],
+        ["Hallands lan","SE-N","21012"],
+        ["Jamtlands lan","SE-Z","21020"],
+        ["Jonkopings lan","SE-F","21006"],
+        ["Kalmar lan","SE-H","21008"],
+        ["Kronobergs lan","SE-G","21007"],
+        ["Norrbottens lan","SE-BD","21002"],
+        ["Orebro lan","SE-T","21015"],
+        ["Ostergotlands lan","SE-E","21005"],
+        ["Skane lan","SE-M","21011"],
+        ["Sodermanlands lan","SE-D","21004"],
+        ["Stockholms lan","SE-AB","21000"],
+        ["Uppsala lan","SE-C","21003"],
+        ["Varmlands lan","SE-S","21014"],
+        ["Vasterbottens lan","SE-AC","21001"],
+        ["Vasternorrlands lan","SE-Y","21019"],
+        ["Vastmanlands lan","SE-U","21016"],
+        ["Vastra Gotalands lan","SE-O","21013"],
+        ["Aargau","CH-AG","20126"],
+        ["Appenzell Inner Rhodes","CH-AI","20127"],
+        ["Appenzell Outer Rhodes","CH-AR","20128"],
+        ["Basel-City","CH-BS","20131"],
+        ["Basel-Country","CH-BL","20130"],
+        ["Bern","CH-BE","20129"],
+        ["Fribourg","CH-FR","20132"],
+        ["Geneva","CH-GE","20133"],
+        ["Glarus","CH-GL","20134"],
+        ["Grisons","CH-GR","20135"],
+        ["Jura","CH-JU","20136"],
+        ["Lucerne","CH-LU","20137"],
+        ["Neuchatel","CH-NE","20138"],
+        ["Nidwalden","CH-NW","20139"],
+        ["Obwalden","CH-OW","20140"],
+        ["Schaffhausen","CH-SH","20142"],
+        ["Schwyz","CH-SZ","20144"],
+        ["Solothurn","CH-SO","20143"],
+        ["St. Gallen","CH-SG","20141"],
+        ["Thurgau","CH-TG","20145"],
+        ["Ticino","CH-TI","20146"],
+        ["Uri","CH-UR","20147"],
+        ["Valais","CH-VS","20149"],
+        ["Vaud","CH-VD","20148"],
+        ["Zug","CH-ZG","20150"],
+        ["Zurich","CH-ZH","20151"],
+        ["Chachoengsao","TH-24","21031"],
+        ["Chiang Mai","TH-50","21036"],
+        ["Chiang Rai","TH-57","21039"],
+        ["Chon Buri","TH-20","21030"],
+        ["Khon Kaen","TH-40","21035"],
+        ["Krung Thep Maha Nakhon Bangkok","TH-10","21025"],
+        ["Lampang","TH-52","21037"],
+        ["Nakhon Pathom","TH-73","21488"],
+        ["Nakhon Ratchasima","TH-30","21032"],
+        ["Nakhon Si Thammarat","TH-80","21041"],
+        ["Nonthaburi","TH-12","21026"],
+        ["Pathum Thani","TH-13","21027"],
+        ["Pattani","TH-94","21046"],
+        ["Phaket","TH-83","21042"],
+        ["Phitsanulok","TH-65","21040"],
+        ["Phra Nakhon Si Ayutthaya","TH-14","21028"],
+        ["Phrae","TH-54","21038"],
+        ["Prachuap Khiri Khan","TH-77","21486"],
+        ["Ranong","TH-85","21043"],
+        ["Samut Sakhon","TH-74","21487"],
+        ["Saraburi","TH-19","21029"],
+        ["Songkhla","TH-90","21044"],
+        ["Trang","TH-92","21045"],
+        ["Ubon Ratchathani","TH-34","21033"],
+        ["Yala","TH-95","21047"],
+        ["Yasothon","TH-35","21034"],
+        ["Adana","TR-01","21052"],
+        ["Adıyaman","TR-02","21354"],
+        ["Afyon","TR-03","21053"],
+        ["Aksaray","TR-68","21377"],
+        ["Amasya","TR-05","21355"],
+        ["Ankara","TR-06","21055"],
+        ["Antalya","TR-07","21056"],
+        ["Ardahan","TR-75","21382"],
+        ["Artvin","TR-08","21356"],
+        ["Aydın","TR-09","21057"],
+        ["Ağrı","TR-04","21054"],
+        ["Çanakkale","TR-17","21061"],
+        ["Çankırı","TR-18","21361"],
+        ["Çorum","TR-19","21362"],
+        ["Balıkesir","TR-10","21058"],
+        ["Bartın","TR-74","21381"],
+        ["Batman","TR-72","21379"],
+        ["Bayburt","TR-69","21378"],
+        ["Bilecik","TR-11","21357"],
+        ["Bingöl","TR-12","21358"],
+        ["Bitlis","TR-13","21359"],
+        ["Bolu","TR-14","21059"],
+        ["Burdur","TR-15","21360"],
+        ["Bursa","TR-16","21060"],
+        ["Denizli","TR-20","21363"],
+        ["Diyarbakır","TR-21","21062"],
+        ["Duzce","TR-81","21577"],
+        ["Edirne","TR-22","21364"],
+        ["Elazığ","TR-23","21063"],
+        ["Erzincan","TR-24","21287"],
+        ["Erzurum","TR-25","21064"],
+        ["Eskişehir","TR-26","21065"],
+        ["Gaziantep","TR-27","21066"],
+        ["Gümüşhane","TR-29","21366"],
+        ["Giresun","TR-28","21365"],
+        ["Hakkari","TR-30","21367"],
+        ["Hatay","TR-31","21067"],
+        ["Içel","TR-33","21068"],
+        ["Isparta","TR-32","21248"],
+        ["Istanbul","TR-34","21069"],
+        ["Izmir","TR-35","21070"],
+        ["Iğdır","TR-76","21383"],
+        ["Kahramanmaraş","TR-46","21079"],
+        ["Karabuk","TR-78","21578"],
+        ["Karaman","TR-70","21092"],
+        ["Kars","TR-36","21071"],
+        ["Kastamonu","TR-37","21072"],
+        ["Kayseri","TR-38","21073"],
+        ["Kütahya","TR-43","21076"],
+        ["Kilis","TR-79","21579"],
+        ["Kocaeli","TR-41","21074"],
+        ["Konya","TR-42","21075"],
+        ["Kırklareli","TR-39","21368"],
+        ["Kırşehir","TR-40","21369"],
+        ["Kırıkkale","TR-71","21093"],
+        ["Malatya","TR-44","21077"],
+        ["Manisa","TR-45","21078"],
+        ["Mardin","TR-47","21370"],
+        ["Muş","TR-49","21081"],
+        ["Muğla","TR-48","21080"],
+        ["Nevşehir","TR-50","21082"],
+        ["Niğde","TR-51","21083"],
+        ["Ordu","TR-52","21371"],
+        ["Osmaniye","TR-80","21384"],
+        ["Rize","TR-53","21372"],
+        ["Sakarya","TR-54","21084"],
+        ["Samsun","TR-55","21085"],
+        ["Sinop","TR-57","21374"],
+        ["Sivas","TR-58","21086"],
+        ["Tekirdağ","TR-59","21087"],
+        ["Tokat","TR-60","21249"],
+        ["Trabzon","TR-61","21088"],
+        ["Tunceli","TR-62","21375"],
+        ["Uşak","TR-64","21376"],
+        ["Van","TR-65","21090"],
+        ["Yalova","TR-77","21094"],
+        ["Yozgat","TR-66","21257"],
+        ["Zonguldak","TR-67","21091"],
+        ["Şanlıurfa","TR-63","21089"],
+        ["Şiirt","TR-56","21373"],
+        ["Şırnak","TR-73","21380"],
+        ["Cherkas'ka Oblast'","UA-71","21128"],
+        ["Chernihivs'ka Oblast'","UA-74","21129"],
+        ["Chernivets'ka Oblast'","UA-77","21130"],
+        ["Dnipropetrovs'ka Oblast'","UA-12","21112"],
+        ["Donets'ka Oblast'","UA-14","21113"],
+        ["Ivano-Frankivs'ka Oblast'","UA-26","21117"],
+        ["Kharkivs'ka Oblast'","UA-63","21125"],
+        ["Khersons'ka Oblast'","UA-65","21126"],
+        ["Khmel'nyts'ka Oblast'","UA-68","21127"],
+        ["Kievs'ka oblast","UA-32","21580"],
+        ["Kirovohrads'ka Oblast'","UA-35","21119"],
+        ["Kyiv","UA-30","21118"],
+        ["L'vivs'ka Oblast'","UA-46","21121"],
+        ["Luhans'ka Oblast'","UA-09","21111"],
+        ["Mykolaivs'ka oblast","UA-48","21581"],
+        ["Odes 'ka Oblast'","UA-51","21122"],
+        ["Poltavs'ka Oblast'","UA-53","21123"],
+        ["Respublika Krym","UA-43","21120"],
+        ["Rivnens'ka","UA-56","21582"],
+        ["Sevastopol","UA-40","21583"],
+        ["Sums 'ka Oblast'","UA-59","21124"],
+        ["Ternopil's'ka Oblast'","UA-61","21292"],
+        ["Vinnyts'ka Oblast'","UA-05","21109"],
+        ["Volyos'ka Oblast'","UA-07","21110"],
+        ["Zakarpats'ka Oblast'","UA-21","21115"],
+        ["Zaporiz'ka Oblast'","UA-23","21116"],
+        ["Zhytomyrs'ka Oblast'","UA-18","21114"],
+        ["Channel Islands","GB-CHA","20338"],
+        ["England","GB-ENG","20339"],
+        ["Isle Of Man","GB-IOM","20340"],
+        ["Northern Ireland","GB-NIR","20341"],
+        ["Scotland","GB-SCT","20342"],
+        ["Wales","GB-WLS","20343"],
+        ["Alabama","US-AL","21133"],
+        ["Alaska","US-AK","21132"],
+        ["Arizona","US-AZ","21136"],
+        ["Arkansas","US-AR","21135"],
+        ["California","US-CA","21137"],
+        ["Colorado","US-CO","21138"],
+        ["Connecticut","US-CT","21139"],
+        ["Delaware","US-DE","21141"],
+        ["District of Columbia","US-DC","21140"],
+        ["Florida","US-FL","21142"],
+        ["Georgia","US-GA","21143"],
+        ["Hawaii","US-HI","21144"],
+        ["Idaho","US-ID","21146"],
+        ["Illinois","US-IL","21147"],
+        ["Indiana","US-IN","21148"],
+        ["Iowa","US-IA","21145"],
+        ["Kansas","US-KS","21149"],
+        ["Kentucky","US-KY","21150"],
+        ["Louisiana","US-LA","21151"],
+        ["Maine","US-ME","21154"],
+        ["Maryland","US-MD","21153"],
+        ["Massachusetts","US-MA","21152"],
+        ["Michigan","US-MI","21155"],
+        ["Minnesota","US-MN","21156"],
+        ["Mississippi","US-MS","21158"],
+        ["Missouri","US-MO","21157"],
+        ["Montana","US-MT","21159"],
+        ["Nebraska","US-NE","21162"],
+        ["Nevada","US-NV","21166"],
+        ["New Hampshire","US-NH","21163"],
+        ["New Jersey","US-NJ","21164"],
+        ["New Mexico","US-NM","21165"],
+        ["New York","US-NY","21167"],
+        ["North Carolina","US-NC","21160"],
+        ["North Dakota","US-ND","21161"],
+        ["Ohio","US-OH","21168"],
+        ["Oklahoma","US-OK","21169"],
+        ["Oregon","US-OR","21170"],
+        ["Pennsylvania","US-PA","21171"],
+        ["Rhode Island","US-RI","21172"],
+        ["South Carolina","US-SC","21173"],
+        ["South Dakota","US-SD","21174"],
+        ["Tennessee","US-TN","21175"],
+        ["Texas","US-TX","21176"],
+        ["Utah","US-UT","21177"],
+        ["Vermont","US-VT","21179"],
+        ["Virginia","US-VA","21178"],
+        ["Washington","US-WA","21180"],
+        ["West Virginia","US-WV","21183"],
+        ["Wisconsin","US-WI","21182"],
+        ["Wyoming","US-WY","21184"]
+      ]
+    
+      def self.find_name_by_province_code(province_code)
+        province_code = province_code.upcase
+        PROVINCES.find { |name,code,id| province_code == code }.first rescue nil
+      end
+
+    end
+  end  
+end