usaspending-rb 0.1.2

data/lib/usaspending/error.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module USAspending
+  # Base error class. All gem errors inherit from this.
+  class Error < StandardError; end
+
+  # Base class for all HTTP errors (4xx and 5xx).
+  # Carries the status code and response body for programmatic handling.
+  #
+  # @example
+  #   begin
+  #     USAspending.awards.find("INVALID")
+  #   rescue USAspending::HttpError => e
+  #     puts e.status # => 404
+  #     puts e.body   # => { "detail" => "..." }
+  #   end
+  class HttpError < Error
+    # @return [Integer, nil] the HTTP status code
+    attr_reader :status
+
+    # @return [Hash, String, nil] the response body
+    attr_reader :body
+
+    # @param message [String, nil] error message
+    # @param status [Integer, nil] HTTP status code
+    # @param body [Hash, String, nil] response body
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body   = body
+      super(message || default_message)
+    end
+
+    private
+
+    def default_message
+      "HTTP #{status}: #{body}"
+    end
+  end
+
+  # Raised when the API returns a 4xx response.
+  class ClientError < HttpError; end
+
+  # Raised when the API returns a 400 (bad request / malformed params).
+  class BadRequestError < ClientError; end
+
+  # Raised when the API returns a 404.
+  class NotFoundError < ClientError; end
+
+  # Raised when the API returns a 422 (invalid filter params).
+  class UnprocessableEntityError < ClientError; end
+
+  # Raised when the API returns a 429 and retries are exhausted.
+  class RateLimitError < ClientError; end
+
+  # Raised when the API returns a 5xx response after retries are exhausted.
+  class ServerError < HttpError
+    private
+
+    def default_message
+      "Server error HTTP #{status}"
+    end
+  end
+
+  # Raised on network-level failures (timeout, connection refused, DNS, etc.).
+  class ConnectionError < Error; end
+end

data/lib/usaspending/resources/agency.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module USAspending
+  module Resources
+    class Agency < Base
+      # ------------------------------------------------------------------
+      # 1. Agency overview including budget, obligations, outlay totals.
+      #    `GET /api/v2/agency/{toptier_code}/`
+      #
+      # @param toptier_code [String] e.g. "020" for Treasury, "097" for DoD
+      # @param fiscal_year  [Integer] defaults to most recent available
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      #
+      # @example Fetch Treasury Department overview
+      #   client = USAspending::Client.new
+      #   response = client.agency.overview("020", fiscal_year: 2024)
+      #   response.data["agency_name"] #=> "Department of the Treasury"
+      def overview(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 2. Awards summary for an agency.
+      #    `GET /api/v2/agency/{toptier_code}/awards/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def awards(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/awards/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 3. Count of new awards for an agency.
+      #    `GET /api/v2/agency/{toptier_code}/awards/new/count/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def new_awards_count(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/awards/new/count/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 4. Award type counts (not scoped to a single agency).
+      #    GET /api/v2/agency/awards/count/
+      #
+      # @param fiscal_year [Integer]
+      # @return [USAspending::Response]
+      def awards_count(fiscal_year: nil)
+        get('agency/awards/count/', fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 5. Budget functions list for an agency.
+      #    `GET /api/v2/agency/{toptier_code}/budget_function/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @param limit        [Integer]
+      # @param page         [Integer]
+      # @return [USAspending::Response]
+      def budget_function(toptier_code, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/#{toptier_code}/budget_function/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # 6. Count of budget functions for an agency.
+      #    `GET /api/v2/agency/{toptier_code}/budget_function/count/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def budget_function_count(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/budget_function/count/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 7. Budgetary resources for an agency across fiscal years.
+      #    `GET /api/v2/agency/{toptier_code}/budgetary_resources/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def budgetary_resources(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/budgetary_resources/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 8. Federal account breakdown for an agency.
+      #    `GET /api/v2/agency/{toptier_code}/federal_account/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @param limit        [Integer]
+      # @param page         [Integer]
+      # @return [USAspending::Response]
+      def federal_accounts(toptier_code, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/#{toptier_code}/federal_account/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # 9. Count of federal accounts for an agency.
+      #    `GET /api/v2/agency/{toptier_code}/federal_account/count/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def federal_account_count(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/federal_account/count/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 10. Object classes for an agency.
+      #     `GET /api/v2/agency/{toptier_code}/object_class/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @param limit        [Integer]
+      # @param page         [Integer]
+      # @return [USAspending::Response]
+      def object_class(toptier_code, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/#{toptier_code}/object_class/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # 11. Count of object classes for an agency.
+      #     `GET /api/v2/agency/{toptier_code}/object_class/count/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def object_class_count(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/object_class/count/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 12. Obligations breakdown by award category.
+      #     `GET /api/v2/agency/{toptier_code}/obligations_by_award_category/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def obligations_by_award_category(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/obligations_by_award_category/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 13. Program activities for an agency.
+      #     `GET /api/v2/agency/{toptier_code}/program_activity/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @param limit        [Integer]
+      # @param page         [Integer]
+      # @return [USAspending::Response]
+      def program_activity(toptier_code, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/#{toptier_code}/program_activity/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # 14. Count of program activities for an agency.
+      #     `GET /api/v2/agency/{toptier_code}/program_activity/count/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def program_activity_count(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/program_activity/count/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 15. Sub-agencies for a given top-tier agency.
+      #     `GET /api/v2/agency/{toptier_code}/sub_agency/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @param limit        [Integer]
+      # @param page         [Integer]
+      # @return [USAspending::Response]
+      def sub_agencies(toptier_code, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/#{toptier_code}/sub_agency/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # 16. Count of sub-agencies for an agency.
+      #     `GET /api/v2/agency/{toptier_code}/sub_agency/count/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @return [USAspending::Response]
+      def sub_agency_count(toptier_code, fiscal_year: nil)
+        get("agency/#{toptier_code}/sub_agency/count/", fy_params(fiscal_year))
+      end
+
+      # ------------------------------------------------------------------
+      # 17. Bureaus (sub-components) for an agency.
+      #     `GET /api/v2/agency/{toptier_code}/sub_components/`
+      #
+      # @param toptier_code [String]
+      # @param fiscal_year  [Integer]
+      # @param limit        [Integer]
+      # @param page         [Integer]
+      # @return [USAspending::Response]
+      def sub_components(toptier_code, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/#{toptier_code}/sub_components/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # 18. Federal accounts for a specific bureau within an agency.
+      #     `GET /api/v2/agency/{toptier_code}/sub_components/{bureau_slug}/`
+      #
+      # @param toptier_code [String]
+      # @param bureau_slug  [String]
+      # @param fiscal_year  [Integer]
+      # @param limit        [Integer]
+      # @param page         [Integer]
+      # @return [USAspending::Response]
+      def sub_component_federal_accounts(toptier_code, bureau_slug, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/#{toptier_code}/sub_components/#{bureau_slug}/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # 19. Object classes for a Treasury Account Symbol (TAS).
+      #     `GET /api/v2/agency/treasury_account/{tas}/object_class/`
+      #
+      # @param tas         [String] Treasury Account Symbol
+      # @param fiscal_year [Integer]
+      # @param limit       [Integer]
+      # @param page        [Integer]
+      # @return [USAspending::Response]
+      def treasury_account_object_class(tas, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/treasury_account/#{tas}/object_class/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # 20. Program activities for a Treasury Account Symbol (TAS).
+      #     `GET /api/v2/agency/treasury_account/{tas}/program_activity/`
+      #
+      # @param tas         [String] Treasury Account Symbol
+      # @param fiscal_year [Integer]
+      # @param limit       [Integer]
+      # @param page        [Integer]
+      # @return [USAspending::Response]
+      def treasury_account_program_activity(tas, fiscal_year: nil, limit: 10, page: 1)
+        get("agency/treasury_account/#{tas}/program_activity/", fy_params(fiscal_year, limit: limit, page: page))
+      end
+
+      # ------------------------------------------------------------------
+      # List all top-tier agencies with their toptier_codes.
+      # GET /api/v2/references/toptier_agencies/
+      #
+      # @return [USAspending::Response]
+      def list
+        get('references/toptier_agencies/')
+      end
+
+      private
+
+      # Builds query params hash with optional fiscal_year and any extras.
+      # @param fiscal_year [Integer, nil]
+      # @param extras [Hash] additional params (limit, page, etc.)
+      # @return [Hash]
+      def fy_params(fiscal_year, **extras)
+        params = extras.dup
+        params[:fiscal_year] = fiscal_year if fiscal_year
+        params
+      end
+    end
+  end
+end

data/lib/usaspending/resources/autocomplete.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+module USAspending
+  module Resources
+    class Autocomplete < Base
+      # Awarding agency autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def awarding_agency(search_text, limit: 10)
+        post('autocomplete/awarding_agency/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # Funding agency autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def funding_agency(search_text, limit: 10)
+        post('autocomplete/funding_agency/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # Awarding agency + office autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def awarding_agency_office(search_text, limit: 10)
+        post('autocomplete/awarding_agency_office/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # Funding agency + office autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def funding_agency_office(search_text, limit: 10)
+        post('autocomplete/funding_agency_office/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # CFDA program autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def cfda(search_text, limit: 10)
+        post('autocomplete/cfda/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # NAICS code and title autocomplete.
+      #
+      # @param search_text [String] code fragment or industry description
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def naics(search_text, limit: 10)
+        post('autocomplete/naics/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # PSC (Product Service Code) autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def psc(search_text, limit: 10)
+        post('autocomplete/psc/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # Program activity autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def program_activity(search_text, limit: 10)
+        post('autocomplete/program_activity/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # Recipient name/UEI autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def recipient(search_text, limit: 10)
+        post('autocomplete/recipient/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # Glossary term autocomplete.
+      #
+      # @param search_text [String]
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def glossary(search_text, limit: 10)
+        post('autocomplete/glossary/', {
+               search_text: search_text,
+               limit: limit
+             })
+      end
+
+      # City name autocomplete.
+      #
+      # @param search_text  [String]
+      # @param scope        [String] "recipient_location" or "primary_place_of_performance"
+      #                              (default: "recipient_location")
+      # @param country_code [String] ISO 3166-1 alpha-3 country code (default: "USA")
+      # @param state_code   [String, nil] optional two-letter state abbreviation
+      # @param limit        [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def city(search_text, scope: 'recipient_location', country_code: 'USA', state_code: nil, limit: 10)
+        filter = { country_code: country_code, scope: scope }
+        filter[:state_code] = state_code if state_code
+        post('autocomplete/city/', {
+               search_text: search_text,
+               limit: limit,
+               filter: filter
+             })
+      end
+
+      # Location autocomplete. Used to resolve zip codes to districts.
+      #
+      # @param search_text [String] zip code, city name, state, etc.
+      # @param geo_layer   [String] "state", "county", "city",
+      #                             "congressional_district", "zip_code", "country"
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def location(search_text, geo_layer: nil, limit: 10)
+        body = { search_text: search_text, limit: limit }
+        body[:geo_layer] = geo_layer if geo_layer
+        post('autocomplete/location/', body)
+      end
+
+      # ------------------------------------------------------------------
+      # TAS (Treasury Account Symbol) component autocomplete endpoints
+      #
+      # Each accounts/* endpoint accepts search_text, limit, and an
+      # optional filters hash whose keys are other TAS component values
+      # (e.g. ata, aid, bpoa, epoa, a, main, sub).
+      # ------------------------------------------------------------------
+
+      # TAS ATA (Allocation Transfer Agency) autocomplete.
+      #
+      # @param search_text [String]
+      # @param filters     [Hash] TAS component filters
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def accounts_ata(search_text, filters: {}, limit: 10)
+        accounts_autocomplete('ata', search_text, filters, limit)
+      end
+
+      # TAS AID (Agency Identifier) autocomplete.
+      #
+      # @param search_text [String]
+      # @param filters     [Hash] TAS component filters
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def accounts_aid(search_text, filters: {}, limit: 10)
+        accounts_autocomplete('aid', search_text, filters, limit)
+      end
+
+      # TAS BPOA (Beginning Period of Availability) autocomplete.
+      #
+      # @param search_text [String]
+      # @param filters     [Hash] TAS component filters
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def accounts_bpoa(search_text, filters: {}, limit: 10)
+        accounts_autocomplete('bpoa', search_text, filters, limit)
+      end
+
+      # TAS EPOA (Ending Period of Availability) autocomplete.
+      #
+      # @param search_text [String]
+      # @param filters     [Hash] TAS component filters
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def accounts_epoa(search_text, filters: {}, limit: 10)
+        accounts_autocomplete('epoa', search_text, filters, limit)
+      end
+
+      # TAS Availability Type Code autocomplete.
+      #
+      # @param search_text [String]
+      # @param filters     [Hash] TAS component filters
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def accounts_a(search_text, filters: {}, limit: 10)
+        accounts_autocomplete('a', search_text, filters, limit)
+      end
+
+      # TAS Main Account Code autocomplete.
+      #
+      # @param search_text [String]
+      # @param filters     [Hash] TAS component filters
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def accounts_main(search_text, filters: {}, limit: 10)
+        accounts_autocomplete('main', search_text, filters, limit)
+      end
+
+      # TAS Sub-Account Code autocomplete.
+      #
+      # @param search_text [String]
+      # @param filters     [Hash] TAS component filters
+      # @param limit       [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def accounts_sub(search_text, filters: {}, limit: 10)
+        accounts_autocomplete('sub', search_text, filters, limit)
+      end
+
+      private
+
+      def accounts_autocomplete(component, search_text, filters, limit)
+        body = { search_text: search_text, limit: limit }
+        body[:filters] = filters unless filters.nil? || filters.empty?
+        post("autocomplete/accounts/#{component}/", body)
+      end
+    end
+  end
+end

data/lib/usaspending/resources/award_spending.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module USAspending
+  module Resources
+    class AwardSpending < Base
+      # Returns all award spending by recipient for a given fiscal year and agency.
+      #
+      # @param fiscal_year [Integer]
+      # @param awarding_agency_id [Integer]
+      # @param limit [Integer]
+      # @param page [Integer]
+      # @return [USAspending::Response]
+      # @raise [USAspending::ClientError] on 4xx responses
+      # @raise [USAspending::ServerError] on 5xx responses
+      # @raise [USAspending::ConnectionError] on network failures
+      def by_recipient(fiscal_year:, awarding_agency_id:, limit: 10, page: 1)
+        get('award_spending/recipient/', {
+              fiscal_year: fiscal_year, awarding_agency_id: awarding_agency_id,
+              limit: limit, page: page
+            })
+      end
+    end
+  end
+end