uncomtrade 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1bb614f87fe09f30d8b3542b0054672308f0f9ca
+  data.tar.gz: dd3ae6c6a18bb771d2fa2954d5575b7ccd08f9ea
+SHA512:
+  metadata.gz: 2d8ab065950d5cb2403b22a002d789e5e88f61e0ca1aa6875758034bac8af3d933f161c56d656d6ad71082f073766a477f65abad0cc4b65ccc9b3d4bb354cd49
+  data.tar.gz: c30475b1e94dcf3937ff637e8a13b1e3e27bca17663c2414f3a85306e2a9cfe022d549a5a7f84bca92e7792ab655c21c7ad153126937668e78aca1669268cb76

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.DS_STORE
+*.csv

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in uncomtrade.gemspec
+gemspec

data/HISTORY.md

@@ -0,0 +1,3 @@
+### 0.1.0 (2015-11-08)
+
+* Initial release. Majority of methods were released.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Rickard Sunden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,195 @@
+# Uncomtrade
+
+Simple gem for using the [UN Comtrade API][comtrade]. Their docs state the API can be changed at any moment, so use caution using this gem. I will try to keep it up-to-date as possible.
+
+Basic objectives of gem:
+* Keep parameter names and default values consistent with API.
+* Convenience methods to make querying and processing data easier.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'uncomtrade'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install uncomtrade
+
+## Basic Usage
+
+```ruby
+  request = Uncomtrade::Request.new(max: 2)
+  response = request.get_data
+
+  response.dataset
+  #=> [{"pfCode"=>"H4","yr"=>2014, ...}, ... ]
+
+  response.cherry_pick("period" => "period", "TradeValue" => "trade_amount")
+  #=> [{"period"=>2014, "trade_amount"=>5229972238}, ...]
+```
+
+## Detailed Usage
+
+### Request object
+
+CAUTION: Currently the API only supports the `type` parameter to equal `C`. In this gem you cannot change the `pmt` parameter from `json`.
+
+#### Creating the object
+
+In order to make a request to the API you'll need to create a request object. For convenience, all query parameters have defaults based on the [UN Comtrade API docs][comtrade]. View the current parameters for your request by calling `.params`.
+
+```ruby
+  request = Uncomtrade::Request.new
+  request.params
+  #=>  {:max=>500, :fmt=>"json", :r=>"all", :freq=>"A", :ps=>"now",
+  #     :px=>"HS", :p=>0, :rg=>"all", :cc=>"TOTAL", :type=>"C"}
+```
+
+When you create a request object you can specify what parameters you want to set values for, ones that are not set will retain their default value.
+
+```ruby
+  request = Uncomtrade::Request.new(max: 200, freq: "M", p: 528 )
+  request.params
+  #=> {:max=>200, :freq=>"M", :fmt=>"json", :r=>"all", :ps=>"now",
+  #    :px=>"HS", :p=>528, :rg=>"all", :cc=>"TOTAL", :type=>"C"}
+```
+
+#### Retrieving the data
+
+Call `.get_data` on the request object to return the data. See the [response object](#response-object) documentation on how to interact with data.
+
+```ruby
+  request = Uncomtrade::Request.new(max: 200, freq: "M", p: 528 )
+  response = request.get_data
+```
+
+#### Error handling
+
+The [UN Comtrade API][comtrade] hands back a status for every request. Any status other than `"Ok"` is treated as an error by the API. If you want to rescue the error:
+
+```ruby
+  begin
+    request = Uncomtrade::Request.new(max: 200, freq: "M", p: 528 )
+    response = request.get_data
+  rescue Uncomtrade::ResponseError => error
+    puts error.status
+    puts error.description
+    puts error.message
+  end
+```
+
+`error.message` will probably be the most helpful in debugging your query.
+
+
+#### Updating and resetting the request object
+
+You can update a single parameter or multiple parameters after you've created the request object. You can also reset all of the parameters to their default values by calling `.reset`.
+
+```ruby
+  request = Uncomtrade::Request.new
+  request.update(max: 200)
+  request.update(max: 300, freq: "M")
+  request.reset
+```
+
+#### Country finder helper
+
+WARNING: TO BE SAFE, use the numbers listed in their docs. The API uses the wrong ISO number for France, 251, it should be 250. Not sure how many other errors there are. Also, API includes former countries like USSR, regions and some city states that do not exist in the countries gem. Will work on a better solution.
+
+The [UN Comtrade API][comtrade] uses ISO numbers for identifying countries/regions. This gem uses the [countries gem][countries] to help you use two/three letter country codes, as well as country names to find the number for you. For a list of available countries/regions check the [UN Comtrade API][comtrade] docs. You can also just use the ISO number.
+
+```ruby
+  # Netherlands
+  request = Uncomtrade::Request.new
+  request.update(p: "NLD")
+  request.update(r: "NL")
+  request.update(p: "netherlands")
+  request.update(p: 528)
+```
+
+If you're not specific enough or you write a bad country code, you will get the following exception.
+
+```ruby
+  request = Uncomtrade::Request.new(p: "u")
+  #=> Uncomtrade::CountryError: Could not find specified country/code: u
+
+  request = Uncomtrade::Request.new(p: "united")
+  #=> Uncomtrade::CountryError: Could not find specified country/code: united
+```
+
+### Response object
+
+#### Data methods
+
+Calling `.result` will hand back the entire JSON response.
+Calling `.dataset` will hand back the value of the dataset key from the JSON response. (array of results)
+
+```ruby
+
+  request = Uncomtrade::Request.new(max: 2)
+  response = request.get_data
+
+  response.result
+  response.dataset
+  
+```
+
+#### Convenience methods
+
+To iterate over the dataset to only get the information you want, call `.cherry_pick`. The method allows you to rename keys if you want. See below.
+
+```ruby
+
+  request = Uncomtrade::Request.new(max: 2)
+  response = request.get_data
+  
+  response.cherry_pick(:period => "Year", :TradeValue => "Value")
+  #=> [{"Year"=>2014, "Value"=>5229972238}, ...]
+
+  response.cherry_pick(period: :year, TradeValue: :trade_amount)
+  #=> [{:year=>2014, :trade_amount=>5229972238}, ...]
+
+  response.cherry_pick("period" => "period", "TradeValue" => "TradeValue")
+  #=> [{"period"=>2014, "TradeValue"=>5229972238}, ...]
+
+```
+
+Use `.to_csv` to save a csv file with data that you want. If you don't specify any selectors all data will be returned.
+
+```ruby
+
+  request = Uncomtrade::Request.new(max: 2)
+  response = request.get_data
+  
+  selectors = { period: :period, 
+                TradeValue: :trade_amount, 
+                rtTitle: :reporter_country }
+
+  # ONLY DATA FROM SELECTORS
+  response.to_csv(file: "filepath.csv", selectors: selectors)
+
+  # ALL DATA
+  response.to_csv(file: "filepath.csv")
+
+```
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sunrick/uncomtrade. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+
+[comtrade]: http://comtrade.un.org/data/doc/api/
+[countries]: https://github.com/hexorx/countries

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "uncomtrade"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/uncomtrade.rb

@@ -0,0 +1,12 @@
+require 'httparty'
+require 'countries'
+
+require "uncomtrade/version"
+require "uncomtrade/query"
+require "uncomtrade/options"
+require "uncomtrade/request"
+require "uncomtrade/response"
+
+
+module Uncomtrade
+end

data/lib/uncomtrade/errors.rb

@@ -0,0 +1,19 @@
+module Uncomtrade
+
+  class CountryError < StandardError
+    def initialize(nation)
+      message = "Could not find specified country/code: #{nation}"
+      super(message)
+    end
+  end
+
+  class ResponseError < StandardError
+    attr_reader :status, :description
+    def initialize(status, description, msg)
+      @status = status
+      @description = description
+      super(msg)
+    end
+  end
+
+end

data/lib/uncomtrade/helpers/country.rb

@@ -0,0 +1,37 @@
+require_relative '../errors'
+
+module Uncomtrade
+
+  module Helpers
+
+    class Country
+
+      def self.iso_code(nation)
+        if nation == 0
+          0 # countries gem has no number called 0, it is comtrade api number.
+        elsif nation == "all"
+          "all"
+        else
+          find_country(nation)
+        end
+      end
+
+      private
+
+      def self.find_country(nation)
+        if nation.is_a?(Integer)
+          nation
+        else
+          country = ISO3166::Country.find_country_by_name(nation)   || 
+                    ISO3166::Country.find_country_by_alpha3(nation) || 
+                    ISO3166::Country.find_country_by_alpha2(nation)
+          raise CountryError, nation if country.nil?
+          country.number.to_i
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/uncomtrade/helpers/iterator.rb

@@ -0,0 +1,50 @@
+module Uncomtrade
+  module Helpers
+
+    class Iterator
+
+      def initialize(array)
+        @array = array
+      end
+
+      def cherry_pick(selectors)
+        if !selectors.empty?
+          selectors = syms_to_strings(selectors)
+          array.map do |data|
+            hash = create_hash(data, selectors)
+          end
+        else
+          array
+        end
+      end
+
+      def to_csv(csv_path, selectors)
+        CSV.open(csv_path, "wb") do |csv|
+          picked_array = cherry_pick(selectors)
+          csv << picked_array.first.keys
+          picked_array.each do |hash|
+            csv << hash.values
+          end
+        end
+      end
+
+      private
+
+      attr_reader :array
+
+      def syms_to_strings(selectors)
+        selectors.map do |key, value|
+          [key.to_s, value]
+        end.to_h
+      end
+
+      def create_hash(data, selectors)
+        selectors.inject({}) do |memo, selector|
+          memo.merge({selector.last => data[selector.first]})
+        end
+      end
+
+    end
+
+  end
+end

data/lib/uncomtrade/options.rb

@@ -0,0 +1,53 @@
+require_relative 'helpers/country'
+
+module Uncomtrade
+
+  class Options
+
+    attr_reader :options
+
+    def initialize(opts={})
+      set_options(opts)
+    end
+
+    def update(opts={})
+      opts.each do |key, value|
+        if [:p,:r].include?(key)
+          self.options[key] = iso_code(value)
+        else
+          self.options[key] = value if key != :fmt # don't let user update :fmt
+        end
+      end
+    end
+
+    def reset
+      set_options
+    end
+
+    def list_options
+      options
+    end
+
+    private
+
+    def set_options(options={})
+      options[:max] ||= 500
+      options[:fmt] = 'json' # only support json
+      options[:r] = options[:r].nil? ? 'all': iso_code(options[:r])
+      options[:freq] ||= 'A'
+      options[:ps] ||= 'now'
+      options[:px] ||= 'HS'
+      options[:p] = options[:p].nil? ? 0 : iso_code(options[:p])
+      options[:rg] ||= 'all'
+      options[:cc] ||= 'TOTAL'
+      options[:type] ||= 'C'
+      @options = options
+    end
+
+    def iso_code(country)
+      Helpers::Country.iso_code(country)
+    end
+
+  end
+
+end

data/lib/uncomtrade/query.rb

@@ -0,0 +1,13 @@
+module Uncomtrade
+
+  class Query
+    include HTTParty
+    base_uri 'http://comtrade.un.org/api/get'
+
+    def get_data(options)
+      self.class.get('', query: options)
+    end
+
+  end
+
+end

data/lib/uncomtrade/request.rb

@@ -0,0 +1,34 @@
+module Uncomtrade
+
+  class Request
+
+    def initialize(opts={})
+      @options = Options.new(opts)
+      @query = Query.new
+    end
+
+    def get_data
+      http_response = query.get_data(options.list_options)
+      Response.new(http_response)
+    end
+
+    def reset
+      options.reset
+      self
+    end
+
+    def update(opts={})
+      options.update(opts)
+      self
+    end
+
+    def params
+      options.list_options
+    end
+
+    private
+    attr_reader :options, :query
+
+  end
+
+end

data/lib/uncomtrade/response.rb

@@ -0,0 +1,45 @@
+require_relative 'helpers/iterator'
+require_relative 'errors'
+
+module Uncomtrade
+
+  class Response
+
+    def initialize(response)
+      @response = JSON.parse(response.body)
+      check_status!
+      @iterator = Helpers::Iterator.new(dataset)
+    end
+
+    def result
+      response
+    end
+
+    def dataset
+      response["dataset"]
+    end
+
+    def cherry_pick(options={})
+      iterator.cherry_pick(selectors)
+    end
+
+    def to_csv(file:, selectors: {})
+      iterator.to_csv(file, selectors)
+    end
+
+    private
+
+    attr_reader :response, :iterator
+
+    def check_status!
+      message = "Server error: #{response["Message"]}"
+      raise ResponseError.new(nil, nil, message) if response["Message"]
+      status = response["validation"]["status"]["name"]
+      description = response["validation"]["status"]["description"]
+      message = response["validation"]["message"]
+      raise ResponseError.new(status, description, message) if status != "Ok"
+    end
+
+  end
+
+end

data/lib/uncomtrade/version.rb

@@ -0,0 +1,3 @@
+module Uncomtrade
+  VERSION = "0.1.0"
+end

data/uncomtrade.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'uncomtrade/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "uncomtrade"
+  spec.version       = Uncomtrade::VERSION
+  spec.authors       = ["Rickard Sunden"]
+  spec.email         = ["rickard.sunden@outlook.com"]
+
+  spec.summary       = %q{Simple ruby API wrapper for the UN COMTRADE Database.}
+  spec.description   = %q{Simple ruby API wrapper for the UN COMTRADE Database.}
+  spec.homepage      = "https://github.com/sunrick/uncomtrade"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "httparty", "~> 0.13.7"
+  spec.add_runtime_dependency "countries", "~> 1.1.0"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", '~> 3.3'
+  spec.add_development_dependency "pry", '~> 0.10.1'
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: uncomtrade
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rickard Sunden
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-11-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.7
+- !ruby/object:Gem::Dependency
+  name: countries
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+description: Simple ruby API wrapper for the UN COMTRADE Database.
+email:
+- rickard.sunden@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- HISTORY.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/uncomtrade.rb
+- lib/uncomtrade/errors.rb
+- lib/uncomtrade/helpers/country.rb
+- lib/uncomtrade/helpers/iterator.rb
+- lib/uncomtrade/options.rb
+- lib/uncomtrade/query.rb
+- lib/uncomtrade/request.rb
+- lib/uncomtrade/response.rb
+- lib/uncomtrade/version.rb
+- uncomtrade.gemspec
+homepage: https://github.com/sunrick/uncomtrade
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Simple ruby API wrapper for the UN COMTRADE Database.
+test_files: []