gtfs-data_exchange 0.0.1 → 0.0.2

data/README.md

@@ -1,6 +1,6 @@
 # GTFS::DataExchange
 
-A ruby wrapper for the [gtfs-data-exchange.com api](http://www.gtfs-data-exchange.com/api). Exposes `agency` and `agencies` endpoints.
+A ruby wrapper for the [gtfs-data-exchange.com api](http://www.gtfs-data-exchange.com/api). List all agencies, or find a specific agency by its `dataexchange_id`.
 
 ## Installation
 
@@ -28,7 +28,7 @@ List all agencies.
 agencies = GTFS::DataExchange::API.agencies
 ````
 
-Response data is returned in JSON format by default. To return data in CSV format instead, pass the `:format` option ...
+By default, this will return an `Array` of Ruby `Hash` objects. Pass the 'csv' format option to return a CSV `String` instead.
 
 ```` rb
 agencies = GTFS::DataExchange::API.agencies(:format => "csv")
@@ -42,6 +42,8 @@ Find an agency by its `dataexchange_id`.
 agency = GTFS::DataExchange::API.agency(:dataexchange_id => "shore-line-east")
 ````
 
+By default, this will return a Ruby `Hash` object.
+
 ## Contributing
 
 1. Fork it ( https://github.com/databyday/gtfs-data_exchange/fork )

data/gtfs-data_exchange.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["MJ Rossetti (@s2t2)"]
   spec.email         = ["s2t2mail@gmail.com"]
   spec.summary       = %q{A ruby wrapper for the [gtfs-data-exchange.com api](http://www.gtfs-data-exchange.com/api).}
-  spec.description   = %q{Exposes the `agencies` and `agency` endpoints.}
-  spec.homepage      = "https://github.com/databyday/gtfs-data_exchange"
+  spec.description   = %q{A ruby wrapper for the [gtfs-data-exchange.com api](http://www.gtfs-data-exchange.com/api). List all agencies, or find a specific agency by its `dataexchange_id`.}
+  spec.homepage      = "https://github.com/databyday/gtfs-data-exchange-api-ruby"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/lib/gtfs/data_exchange/api.rb

@@ -1,14 +1,32 @@
+require "httparty"
+
+# Top-level namespace referencing the [General Transit Feed Specification](https://developers.google.com/transit/gtfs/).
 module GTFS
+
+  # Namespace referencing the [data exchange](http://www.gtfs-data-exchange.com/), 
+  #   a third-party site "designed to help developers and transit agencies efficiently share and retrieve GTFS data."
   module DataExchange
+
+    # Contains all data exchange api methods and exceptions.
     class API
-      URL = "http://www.gtfs-data-exchange.com/api"
 
+      # The base url for api endpoints.
+      #   This page also acts as the primary source for api reference documentation.
+      BASE_URL = "http://www.gtfs-data-exchange.com/api"
+
+      # List all agencies.
+      # @param [Hash] options the request options.
+      # @option options [String] :format ('json') the requested data format.
+      # @raise [UnsupportedRequestFormat] if the request format is not supported by the service.
+      # @raise [ResponseCodeError, ResponseDataError] for unexpected responses.
+      # @return [Array, String] the agencies data in the requested format.
       def self.agencies(options = {})
         format = options[:format] || "json"
-        raise RequestFormatError(format) unless ["json","csv"].include?(format)
+        raise UnsupportedRequestFormat, "The requested data format, '#{format}', is not supported by the service. Try 'csv' or 'json' instead." unless ["json","csv"].include?(format)
 
-        request_url = "#{URL}/agencies?format=#{format}"
+        request_url = "#{BASE_URL}/agencies?format=#{format}"
         response = HTTParty.get(request_url)
+
         case format
         when "json"
           raise ResponseCodeError unless response["status_code"] == 200
@@ -21,25 +39,39 @@ module GTFS
         end
       end
 
+      # Find an agency by its `dataexchange_id`.
+      # @param [Hash] options the request options.
+      # @option options [String] :dataexchange_id ('shore-line-east') the requested data format.
+      # @raise [UnrecognizedDataExchangeId] if the requested agency identifier is unrecognized by the service.
+      # @raise [ResponseCodeError, ResponseDataError, ResponseAgencyError] for unexpected responses.
+      # @return [Hash] the agency data.
       def self.agency(options = {})
         dataexchange_id = options[:dataexchange_id] || options[:data_exchange_id] || "shore-line-east"
 
-        request_url = "#{URL}/agency?agency=#{dataexchange_id}"
+        request_url = "#{BASE_URL}/agency?agency=#{dataexchange_id}"
         response = HTTParty.get(request_url)
-        raise RequestDataExchangeIdError(dataexchange_id) if response["status_code"] == 404 && response["status_txt"] == "AGENCY_NOT_FOUND"
+
+        raise UnrecognizedDataExchangeId, "The requested dataexchange_id, '#{dataexchange_id}', was not recognized by the service." if response["status_code"] == 404 && response["status_txt"] == "AGENCY_NOT_FOUND"
         raise ResponseCodeError unless response["status_code"] == 200
         raise ResponseDataError unless response["data"]
         raise ResponseAgencyError unless response["data"]["agency"]
-
         return response["data"]["agency"]
       end
 
-      class RequestDataExchangeIdError < ArgumentError ; end
-      class RequestFormatError < ArgumentError ; end
+      # Exception raised if the service does not recognize the requested *dataexchange_id*.
+      class UnrecognizedDataExchangeId < ArgumentError ; end
 
-      class ResponseAgencyError < StandardError ; end
+      # Exception raised if the service does not support the requested data format.
+      class UnsupportedRequestFormat < ArgumentError ; end
+
+      # Exception raised if the service returns an unexpected response code.
       class ResponseCodeError < StandardError ; end
+
+      # Exception raised if the service returns unexpected or missing response data.
       class ResponseDataError < StandardError ; end
+
+      # Exception raised if the service returns unexpected or missing agency data.
+      class ResponseAgencyError < StandardError ; end
     end
   end
 end

data/lib/gtfs/data_exchange/version.rb

@@ -1,5 +1,7 @@
 module GTFS
   module DataExchange
-    VERSION = "0.0.1"
+
+    # The current gem version. Reference the [releases list](https://github.com/databyday/gtfs-data-exchange-api-ruby/releases) for previous releases. 
+    VERSION = "0.0.2"
   end
 end

data/lib/gtfs/data_exchange.rb

@@ -1,5 +1,3 @@
-require 'httparty'
-
 module GTFS
   module DataExchange
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gtfs-data_exchange
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-27 00:00:00.000000000 Z
+date: 2014-11-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,7 +75,8 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '0.13'
-description: Exposes the `agencies` and `agency` endpoints.
+description: A ruby wrapper for the [gtfs-data-exchange.com api](http://www.gtfs-data-exchange.com/api).
+  List all agencies, or find a specific agency by its `dataexchange_id`.
 email:
 - s2t2mail@gmail.com
 executables: []
@@ -92,7 +93,7 @@ files:
 - lib/gtfs/data_exchange.rb
 - lib/gtfs/data_exchange/api.rb
 - lib/gtfs/data_exchange/version.rb
-homepage: https://github.com/databyday/gtfs-data_exchange
+homepage: https://github.com/databyday/gtfs-data-exchange-api-ruby
 licenses:
 - MIT
 post_install_message: 
@@ -118,3 +119,4 @@ signing_key:
 specification_version: 3
 summary: A ruby wrapper for the [gtfs-data-exchange.com api](http://www.gtfs-data-exchange.com/api).
 test_files: []
+has_rdoc: