phoebe 0.1.0.pre.alpha.1

data/lib/phoebe/resources/data/observations/recent/notable.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Recent
+          class Notable
+            # Get the list of recent, notable observations (up to 30 days ago) of birds seen
+            # in a country, region or location. Notable observations can be for locally or
+            # nationally rare species or are otherwise unusual, e.g. over-wintering birds in a
+            # species which is normally only a summer visitor.
+            #
+            # @overload list(region_code, back: nil, detail: nil, hotspot: nil, max_results: nil, r: nil, spp_locale: nil, request_options: {})
+            #
+            # @param region_code [String] The country, subnational1, subnational2 or location code.
+            #
+            # @param back [Integer] The number of days back to fetch observations.
+            #
+            # @param detail [Symbol, Phoebe::Models::Data::Observations::Recent::NotableListParams::Detail] Include a subset (simple), or all (full), of the fields available.
+            #
+            # @param hotspot [Boolean] Only fetch observations from hotspots
+            #
+            # @param max_results [Integer] Only fetch this number of observations
+            #
+            # @param r [Array<String>] Fetch observations from up to 10 locations
+            #
+            # @param spp_locale [String] Use this language for species common names
+            #
+            # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [Array<Phoebe::Models::Data::Observation>]
+            #
+            # @see Phoebe::Models::Data::Observations::Recent::NotableListParams
+            def list(region_code, params = {})
+              parsed, options = Phoebe::Data::Observations::Recent::NotableListParams.dump_request(params)
+              @client.request(
+                method: :get,
+                path: ["data/obs/%1$s/recent/notable", region_code],
+                query: parsed.transform_keys(max_results: "maxResults", spp_locale: "sppLocale"),
+                model: Phoebe::Internal::Type::ArrayOf[Phoebe::Data::Observation],
+                options: options
+              )
+            end
+
+            # @api private
+            #
+            # @param client [Phoebe::Client]
+            def initialize(client:)
+              @client = client
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/recent/species.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Recent
+          class Species
+            # Get the recent observations, up to 30 days ago, of a particular species in a
+            # country, region or location. Results include only the most recent observation
+            # from each location in the region specified.
+            #
+            # #### Notes
+            #
+            # The species code is typically a 6-letter code, e.g. cangoo for Canada Goose. You
+            # can get complete set of species code from the GET eBird Taxonomy end-point.
+            #
+            # When using the _r_ query parameter set the _regionCode_ URL parameter to an
+            # empty string.
+            #
+            # @overload retrieve(species_code, region_code:, back: nil, hotspot: nil, include_provisional: nil, max_results: nil, r: nil, spp_locale: nil, request_options: {})
+            #
+            # @param species_code [String] Path param: The eBird species code.
+            #
+            # @param region_code [String] Path param: The country, subnational1, subnational2 or location code.
+            #
+            # @param back [Integer] Query param: The number of days back to fetch observations.
+            #
+            # @param hotspot [Boolean] Query param: Only fetch observations from hotspots
+            #
+            # @param include_provisional [Boolean] Query param: Include observations which have not yet been reviewed.
+            #
+            # @param max_results [Integer] Query param: Only fetch this number of observations
+            #
+            # @param r [Array<String>] Query param: Fetch observations from up to 10 locations
+            #
+            # @param spp_locale [String] Query param: Use this language for species common names
+            #
+            # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [Array<Phoebe::Models::Data::Observation>]
+            #
+            # @see Phoebe::Models::Data::Observations::Recent::SpecieRetrieveParams
+            def retrieve(species_code, params)
+              parsed, options = Phoebe::Data::Observations::Recent::SpecieRetrieveParams.dump_request(params)
+              region_code =
+                parsed.delete(:region_code) do
+                  raise ArgumentError.new("missing required path argument #{_1}")
+                end
+              @client.request(
+                method: :get,
+                path: ["data/obs/%1$s/recent/%2$s", region_code, species_code],
+                query: parsed.transform_keys(
+                  include_provisional: "includeProvisional",
+                  max_results: "maxResults",
+                  spp_locale: "sppLocale"
+                ),
+                model: Phoebe::Internal::Type::ArrayOf[Phoebe::Data::Observation],
+                options: options
+              )
+            end
+
+            # @api private
+            #
+            # @param client [Phoebe::Client]
+            def initialize(client:)
+              @client = client
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/recent.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Recent
+          # @return [Phoebe::Resources::Data::Observations::Recent::Notable]
+          attr_reader :notable
+
+          # @return [Phoebe::Resources::Data::Observations::Recent::Species]
+          attr_reader :species
+
+          # @return [Phoebe::Resources::Data::Observations::Recent::Historic]
+          attr_reader :historic
+
+          # Get the list of recent observations (up to 30 days ago) of birds seen in a
+          # country, state, county, or location. Results include only the most recent
+          # observation for each species in the region specified.
+          #
+          # @overload list(region_code, back: nil, cat: nil, hotspot: nil, include_provisional: nil, max_results: nil, r: nil, spp_locale: nil, request_options: {})
+          #
+          # @param region_code [String] The country, subnational1, subnational2 or location code.
+          #
+          # @param back [Integer] The number of days back to fetch observations.
+          #
+          # @param cat [Symbol, Phoebe::Models::Data::Observations::RecentListParams::Cat] Only fetch observations from these taxonomic categories
+          #
+          # @param hotspot [Boolean] Only fetch observations from hotspots
+          #
+          # @param include_provisional [Boolean] Include observations which have not yet been reviewed
+          #
+          # @param max_results [Integer] Only fetch this number of observations
+          #
+          # @param r [Array<String>] Fetch observations from up to 10 locations
+          #
+          # @param spp_locale [String] Use this language for species common names
+          #
+          # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Array<Phoebe::Models::Data::Observation>]
+          #
+          # @see Phoebe::Models::Data::Observations::RecentListParams
+          def list(region_code, params = {})
+            parsed, options = Phoebe::Data::Observations::RecentListParams.dump_request(params)
+            @client.request(
+              method: :get,
+              path: ["data/obs/%1$s/recent", region_code],
+              query: parsed.transform_keys(
+                include_provisional: "includeProvisional",
+                max_results: "maxResults",
+                spp_locale: "sppLocale"
+              ),
+              model: Phoebe::Internal::Type::ArrayOf[Phoebe::Data::Observation],
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [Phoebe::Client]
+          def initialize(client:)
+            @client = client
+            @notable = Phoebe::Resources::Data::Observations::Recent::Notable.new(client: client)
+            @species = Phoebe::Resources::Data::Observations::Recent::Species.new(client: client)
+            @historic = Phoebe::Resources::Data::Observations::Recent::Historic.new(client: client)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        # @return [Phoebe::Resources::Data::Observations::Recent]
+        attr_reader :recent
+
+        # @return [Phoebe::Resources::Data::Observations::Geo]
+        attr_reader :geo
+
+        # @return [Phoebe::Resources::Data::Observations::Nearest]
+        attr_reader :nearest
+
+        # @api private
+        #
+        # @param client [Phoebe::Client]
+        def initialize(client:)
+          @client = client
+          @recent = Phoebe::Resources::Data::Observations::Recent.new(client: client)
+          @geo = Phoebe::Resources::Data::Observations::Geo.new(client: client)
+          @nearest = Phoebe::Resources::Data::Observations::Nearest.new(client: client)
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      # @return [Phoebe::Resources::Data::Observations]
+      attr_reader :observations
+
+      # @api private
+      #
+      # @param client [Phoebe::Client]
+      def initialize(client:)
+        @client = client
+        @observations = Phoebe::Resources::Data::Observations.new(client: client)
+      end
+    end
+  end
+end

data/lib/phoebe/resources/product/checklist.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Product
+      class Checklist
+        # Get the details and observations of a checklist.
+        #
+        # #### Notes Do NOT use this to download large amounts of data. You will be banned if you do. In the fields for each observation, the following fields are duplicates or obsolete and will be removed at a future date: _howManyAtleast_, _howManyAtmost_, _hideFlags_, _projId_, _subId_, _subnational1Code_ and _present_.
+        #
+        # @overload view(sub_id, request_options: {})
+        #
+        # @param sub_id [String] The checklist identifier.
+        #
+        # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Phoebe::Models::Product::ChecklistViewResponse]
+        #
+        # @see Phoebe::Models::Product::ChecklistViewParams
+        def view(sub_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["product/checklist/view/%1$s", sub_id],
+            model: Phoebe::Models::Product::ChecklistViewResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Phoebe::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/product/lists/historical.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Product
+      class Lists
+        class Historical
+          # Some parameter documentations has been truncated, see
+          # {Phoebe::Models::Product::Lists::HistoricalRetrieveParams} for more details.
+          #
+          # Get information on the checklists submitted on a given date for a country or
+          # region.
+          #
+          # @overload retrieve(d, region_code:, y_:, m:, max_results: nil, sort_key: nil, request_options: {})
+          #
+          # @param d [Integer] Path param: The day in the month.
+          #
+          # @param region_code [String] Path param: The country, subnational1, subnational2 or location code.
+          #
+          # @param y_ [Integer] Path param: The year, from 1800 to the present.
+          #
+          # @param m [Integer] Path param: The month, from 1-12.
+          #
+          # @param max_results [Integer] Query param: Only fetch this number of checklists.
+          #
+          # @param sort_key [Symbol, Phoebe::Models::Product::Lists::HistoricalRetrieveParams::SortKey] Query param: Order the results by the date of the checklist or by the date it wa
+          #
+          # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Array<Phoebe::Models::Product::Lists::HistoricalRetrieveResponseItem>]
+          #
+          # @see Phoebe::Models::Product::Lists::HistoricalRetrieveParams
+          def retrieve(d, params)
+            parsed, options = Phoebe::Product::Lists::HistoricalRetrieveParams.dump_request(params)
+            region_code =
+              parsed.delete(:region_code) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            y_ =
+              parsed.delete(:y_) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            m =
+              parsed.delete(:m) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            @client.request(
+              method: :get,
+              path: ["product/lists/%1$s/%2$s/%3$s/%4$s", region_code, y_, m, d],
+              query: parsed.transform_keys(max_results: "maxResults", sort_key: "sortKey"),
+              model: Phoebe::Internal::Type::ArrayOf[Phoebe::Models::Product::Lists::HistoricalRetrieveResponseItem],
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [Phoebe::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/product/lists.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Product
+      class Lists
+        # @return [Phoebe::Resources::Product::Lists::Historical]
+        attr_reader :historical
+
+        # Get information on the most recently submitted checklists for a region.
+        #
+        # @overload retrieve(region_code, max_results: nil, request_options: {})
+        #
+        # @param region_code [String] The country, subnational1, subnational2 or location code.
+        #
+        # @param max_results [Integer] Only fetch this number of checklists.
+        #
+        # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Array<Phoebe::Models::Product::ListRetrieveResponseItem>]
+        #
+        # @see Phoebe::Models::Product::ListRetrieveParams
+        def retrieve(region_code, params = {})
+          parsed, options = Phoebe::Product::ListRetrieveParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["product/lists/%1$s", region_code],
+            query: parsed.transform_keys(max_results: "maxResults"),
+            model: Phoebe::Internal::Type::ArrayOf[Phoebe::Models::Product::ListRetrieveResponseItem],
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Phoebe::Client]
+        def initialize(client:)
+          @client = client
+          @historical = Phoebe::Resources::Product::Lists::Historical.new(client: client)
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/product/species_list.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Product
+      class SpeciesList
+        # Some parameter documentations has been truncated, see
+        # {Phoebe::Models::Product::SpeciesListListParams} for more details.
+        #
+        # Get a list of species codes ever seen in a region, in taxonomic order (species
+        # taxa only)
+        #
+        # #### Notes The results are usually updated every 10 seconds for locations, every day for larger regions.
+        #
+        # @overload list(region_code, request_options: {})
+        #
+        # @param region_code [String] Any location, USFWS region, subnational2, subnational1, country, or custom regio
+        #
+        # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Array<String>]
+        #
+        # @see Phoebe::Models::Product::SpeciesListListParams
+        def list(region_code, params = {})
+          @client.request(
+            method: :get,
+            path: ["product/spplist/%1$s", region_code],
+            model: Phoebe::Internal::Type::ArrayOf[String],
+            options: params[:request_options]
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Phoebe::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/product/stats.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Product
+      class Stats
+        # Get a summary of the number of checklist submitted, species seen and
+        # contributors on a given date for a country or region.
+        #
+        # #### Notes The results are updated every 15 minutes.
+        #
+        # @overload retrieve(d, region_code:, y_:, m:, request_options: {})
+        #
+        # @param d [Integer] The day in the month.
+        #
+        # @param region_code [String] The country, subnational1, subnational2 or location code.
+        #
+        # @param y_ [Integer] The year, from 1800 to the present.
+        #
+        # @param m [Integer] The month, from 1-12.
+        #
+        # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Phoebe::Models::Product::StatRetrieveResponse]
+        #
+        # @see Phoebe::Models::Product::StatRetrieveParams
+        def retrieve(d, params)
+          parsed, options = Phoebe::Product::StatRetrieveParams.dump_request(params)
+          region_code =
+            parsed.delete(:region_code) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          y_ =
+            parsed.delete(:y_) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          m =
+            parsed.delete(:m) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["product/stats/%1$s/%2$s/%3$s/%4$s", region_code, y_, m, d],
+            model: Phoebe::Models::Product::StatRetrieveResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Phoebe::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/product/top100.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Product
+      class Top100
+        # Some parameter documentations has been truncated, see
+        # {Phoebe::Models::Product::Top100RetrieveParams} for more details.
+        #
+        # Get the top 100 contributors on a given date for a country or region.
+        #
+        # #### Notes
+        #
+        # The results are updated every 15 minutes.
+        #
+        # When ordering by the number of completed checklists, the number of species seen
+        # will always be zero. Similarly when ordering by the number of species seen the
+        # number of completed checklists will always be zero. <b>Selected Response Field
+        # Notes</b>
+        #
+        # profileHandle - if a user has enabled their profile, this is the handle to reach
+        # it via ebird.org/ebird/profile/{profileHandle}
+        #
+        # numSpecies - always zero when checklistSort parameter is true. Invalid
+        # observations ARE included in this total numCompleteChecklists - always zero when
+        # checklistSort parameter is false
+        #
+        # @overload retrieve(d, region_code:, y_:, m:, max_results: nil, ranked_by: nil, request_options: {})
+        #
+        # @param d [Integer] Path param: The day in the month.
+        #
+        # @param region_code [String] Path param: The country, subnational1, or location code.
+        #
+        # @param y_ [Integer] Path param: The year, from 1800 to the present.
+        #
+        # @param m [Integer] Path param: The month, from 1-12.
+        #
+        # @param max_results [Integer] Query param: Only fetch this number of contributors.
+        #
+        # @param ranked_by [Symbol, Phoebe::Models::Product::Top100RetrieveParams::RankedBy] Query param: Order by number of complete checklists (cl) or by number of species
+        #
+        # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Array<Phoebe::Models::Product::Top100RetrieveResponseItem>]
+        #
+        # @see Phoebe::Models::Product::Top100RetrieveParams
+        def retrieve(d, params)
+          parsed, options = Phoebe::Product::Top100RetrieveParams.dump_request(params)
+          region_code =
+            parsed.delete(:region_code) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          y_ =
+            parsed.delete(:y_) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          m =
+            parsed.delete(:m) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["product/top100/%1$s/%2$s/%3$s/%4$s", region_code, y_, m, d],
+            query: parsed.transform_keys(max_results: "maxResults", ranked_by: "rankedBy"),
+            model: Phoebe::Internal::Type::ArrayOf[Phoebe::Models::Product::Top100RetrieveResponseItem],
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Phoebe::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/product.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Product
+      # @return [Phoebe::Resources::Product::Lists]
+      attr_reader :lists
+
+      # @return [Phoebe::Resources::Product::Top100]
+      attr_reader :top100
+
+      # @return [Phoebe::Resources::Product::Stats]
+      attr_reader :stats
+
+      # @return [Phoebe::Resources::Product::SpeciesList]
+      attr_reader :species_list
+
+      # @return [Phoebe::Resources::Product::Checklist]
+      attr_reader :checklist
+
+      # @api private
+      #
+      # @param client [Phoebe::Client]
+      def initialize(client:)
+        @client = client
+        @lists = Phoebe::Resources::Product::Lists.new(client: client)
+        @top100 = Phoebe::Resources::Product::Top100.new(client: client)
+        @stats = Phoebe::Resources::Product::Stats.new(client: client)
+        @species_list = Phoebe::Resources::Product::SpeciesList.new(client: client)
+        @checklist = Phoebe::Resources::Product::Checklist.new(client: client)
+      end
+    end
+  end
+end

data/lib/phoebe/resources/ref/hotspot/geo.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Ref
+      class Hotspot
+        class Geo
+          # Get the list of hotspots, within a radius of up to 50 kilometers, from a given
+          # set of coordinates.
+          #
+          # @overload retrieve(lat:, lng:, back: nil, dist: nil, fmt: nil, request_options: {})
+          #
+          # @param lat [Float]
+          #
+          # @param lng [Float]
+          #
+          # @param back [Integer] The number of days back to fetch hotspots.
+          #
+          # @param dist [Integer] The search radius from the given position, in kilometers.
+          #
+          # @param fmt [Symbol, Phoebe::Models::Ref::Hotspot::GeoRetrieveParams::Fmt] Fetch the records in CSV or JSON format.
+          #
+          # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Array<Phoebe::Models::Ref::Hotspot::GeoRetrieveResponseItem>]
+          #
+          # @see Phoebe::Models::Ref::Hotspot::GeoRetrieveParams
+          def retrieve(params)
+            parsed, options = Phoebe::Ref::Hotspot::GeoRetrieveParams.dump_request(params)
+            @client.request(
+              method: :get,
+              path: "ref/hotspot/geo",
+              query: parsed,
+              model: Phoebe::Internal::Type::ArrayOf[Phoebe::Models::Ref::Hotspot::GeoRetrieveResponseItem],
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [Phoebe::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end