gbifrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 80db03aa9e1bc8aeb7287ce125be05e703f0f735
+  data.tar.gz: ee90262c1180b85ae3d9e6fa8378ea8875460b69
+SHA512:
+  metadata.gz: 19d373b5885fddfb769ac23ba4840ea33023b7cf9c3ed398082baea9d06a0365e8ba31f41f3052cd8df3a9b2ff275741e5950b865b08cb66410c749c56566c91
+  data.tar.gz: 894d983444649536bfeec0995c32525be08c28e3773f17c6506a604941f87b346caa18d1cf4db3b1b4bf0d4bbc2216b81919af5c31e4a844b3a969ebe4a88b90

data/.gitignore

@@ -0,0 +1,38 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+#Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+cache/
+
+lib/serrano/response.rb

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.1.8
+  - 2.2.4
+  - 2.4.1
+script:
+  bundle exec rake test TESTOPTS="-v"

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0 (2017-09-07)
+
+* First version.

data/CONDUCT.md

@@ -0,0 +1,25 @@
+# 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/

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,64 @@
+PATH
+  remote: .
+  specs:
+    gbifrb (0.1.0)
+      faraday (~> 0.12.0.1)
+      faraday_middleware (~> 0.11.0.1)
+      multi_json (~> 1.12, >= 1.12.1)
+      thor (~> 0.19.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.5.0)
+      public_suffix (~> 2.0, >= 2.0.2)
+    codecov (0.1.10)
+      json
+      simplecov
+      url
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    docile (1.1.5)
+    faraday (0.12.0.1)
+      multipart-post (>= 1.2, < 3)
+    faraday_middleware (0.11.0.1)
+      faraday (>= 0.7.4, < 1.0)
+    hashdiff (0.3.2)
+    json (2.0.3)
+    multi_json (1.12.1)
+    multipart-post (2.0.0)
+    power_assert (0.3.1)
+    public_suffix (2.0.5)
+    rake (12.0.0)
+    safe_yaml (1.0.4)
+    simplecov (0.14.1)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    test-unit (3.2.1)
+      power_assert
+    thor (0.19.4)
+    url (0.3.2)
+    vcr (3.0.3)
+    webmock (2.3.2)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.14, >= 1.14.6)
+  codecov (~> 0.1.10)
+  gbifrb!
+  json (~> 2.0, >= 2.0.3)
+  rake (~> 12.0, >= 12.0.0)
+  simplecov (~> 0.14.1)
+  test-unit (~> 3.2, >= 3.2.1)
+  vcr (~> 3.0, >= 3.0.3)
+  webmock (~> 2.3, >= 2.3.2)
+
+BUNDLED WITH
+   1.15.3

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (C) 2017 Scott Chamberlain
+
+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,127 @@
+gbifrb
+======
+
+[![gem version](https://img.shields.io/gem/v/gbifrb.svg)](https://rubygems.org/gems/gbifrb)
+[![Build Status](https://travis-ci.org/sckott/gbifrb.svg?branch=master)](https://travis-ci.org/sckott/gbifrb)
+[![codecov.io](http://codecov.io/github/sckott/gbifrb/coverage.svg?branch=master)](http://codecov.io/github/sckott/gbifrb?branch=master)
+
+`gbifrb` is a low level client for the GBIF API
+
+Other GBIF API clients:
+
+- Python: [pygbif](https://github.com/sckott/pygbif)
+- R: [rgbif](https://github.com/ropensci/rgbif)
+
+## Changes
+
+For changes see the [Changelog][changelog]
+
+## API
+
+Methods in relation to [GBIF API][gbifapi] routes
+
+registry
+
+* `/node` - `Gbif::Registry.nodes`
+* `/network` - `Gbif::Registry.networks`
+* `/installations` - `Gbif::Registry.installations`
+* `/organizations` - `Gbif::Registry.organizations`
+* `/dataset_metrics` - `Gbif::Registry.dataset_metrics`
+* `/datasets` - `Gbif::Registry.datasets`
+* `/dataset_suggest` - `Gbif::Registry.dataset_suggest`
+* `/dataset_search` - `Gbif::Registry.dataset_search`
+
+species
+
+* `/species/match` - `Gbif::Species.name_backbone`
+* `/species/suggest` - `Gbif::Species.name_suggest`
+* `/species/search` - `Gbif::Species.name_lookup`
+* `/species` - `Gbif::Species.name_usage`
+
+occurrences
+
+* `/search` - `Gbif::Occurrences.search`
+* `/get` - `Gbif::Occurrences.get`
+* `/get_verbatim` - `Gbif::Occurrences.get_verbatim`
+* `/get_fragment` - `Gbif::Occurrences.get_fragment`
+
+
+## Install
+
+### Release version
+
+```
+gem install gbifrb
+```
+
+### Development version
+
+```
+git clone git@github.com:sckott/gbifrb.git
+cd gbifrb
+rake install
+```
+
+## Examples, in Ruby repl
+
+### Registry module
+
+Nodes
+
+```ruby
+require 'gbifrb'
+registry = Gbif::Registry
+registry.nodes(limit: 5)
+```
+
+Networks
+
+```ruby
+registry.networks(uuid: '16ab5405-6c94-4189-ac71-16ca3b753df7')
+```
+
+### Species module
+
+GBIF backbone
+
+```ruby
+species = Gbif::Species
+species.name_backbone(name: "Helianthus")
+```
+
+Suggester
+
+```ruby
+species.name_suggest("Helianthus")
+```
+
+### Occurrences
+
+```ruby
+occ = Gbif::Occurrences
+occ.search(taxonKey: 3329049)
+occ.search(taxonKey: 3329049, limit: 2)
+occ.search(scientificName: 'Ursus americanus')
+```
+
+### curl options
+
+```ruby
+species = Gbif::Species
+species.name_backbone("Helianthus", verbose: true)
+```
+
+### Todo
+
+* CLI interface
+* occurrence metrics methods
+* occurrence downloads methods
+* OAI-PMH interface
+
+## Meta
+
+* Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.
+* License: MIT
+
+[gbifapi]: https://www.gbif.org/developer/summary
+[changelog]: https://github.com/sckott/gbifrb/blob/master/CHANGELOG.md

data/Rakefile

@@ -0,0 +1,41 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test-*.rb']
+  t.verbose = true
+end
+
+desc "Run tests"
+task :default => :test
+
+desc "Build gbifrb docs"
+task :docs do
+	system "yardoc"
+end
+
+desc "bundle install"
+task :bundle do
+  system "bundle install"
+end
+
+desc "clean out builds"
+task :clean do
+  system "ls | grep [0-9].gem | xargs rm"
+end
+
+desc "Build gbifrb"
+task :build do
+	system "gem build gbifrb.gemspec"
+end
+
+desc "Install gbifrb"
+task :install => [:bundle, :build] do
+	system "gem install gbifrb-#{Gbif::VERSION}.gem"
+end
+
+desc "Release to Rubygems"
+task :release => :build do
+  system "gem push gbifrb-#{Gbif::VERSION}.gem"
+end

data/gbifrb.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gbifrb/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'gbifrb'
+  s.version     = Gbif::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 2.0'
+  s.date        = '2017-09-07'
+  s.summary     = "GBIF Client"
+  s.description = "Low Level Ruby Client for the GBIF API"
+  s.authors     = "Scott Chamberlain"
+  s.email       = 'myrmecocystus@gmail.com'
+  s.homepage    = 'https://github.com/sckott/gbifrb'
+  s.licenses    = 'MIT'
+
+  s.files = `git ls-files -z`.split("\x0").reject {|f| f.match(%r{^(test|spec|features)/}) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'bundler', '~> 1.14', '>= 1.14.6'
+  s.add_development_dependency 'rake', '~> 12.0', '>= 12.0.0'
+  s.add_development_dependency 'test-unit', '~> 3.2', '>= 3.2.1'
+  s.add_development_dependency 'simplecov', '~> 0.14.1'
+  s.add_development_dependency 'codecov', '~> 0.1.10'
+  s.add_development_dependency 'json', '~> 2.0', '>= 2.0.3'
+  s.add_development_dependency 'vcr', '~> 3.0', '>= 3.0.3'
+  s.add_development_dependency 'webmock', '~> 2.3', '>= 2.3.2'
+
+  s.add_runtime_dependency 'faraday', '~> 0.12.0.1'
+  s.add_runtime_dependency 'faraday_middleware', '~> 0.11.0.1'
+  s.add_runtime_dependency 'thor', '~> 0.19.4'
+  s.add_runtime_dependency 'multi_json', '~> 1.12', '>= 1.12.1'
+end

data/lib/gbifrb.rb

@@ -0,0 +1,48 @@
+require "gbifrb/version"
+require "gbifrb/request"
+require "gbifrb/Species"
+require "gbifrb/Registry"
+require "gbifrb/Occurrences"
+
+# @!macro gbif_params
+#   @param offset [Fixnum] Number of record to start at, any non-negative integer up to 10,000
+#   @param limit [Fixnum] Number of results to return. Not relavant when searching with specific dois.
+#       Default: 20. Max: 1000
+#   @param sample [Fixnum] Number of random results to return. when you use the sample parameter,
+#       the limit and offset parameters are ignored. This parameter only used when works requested.
+#       Max: 100.
+#   @param sort [String] Field to sort on, one of score, relevance,
+#       updated (date of most recent change to metadata - currently the same as deposited),
+#       deposited (time of most recent deposit), indexed (time of most recent index), or
+#       published (publication date). Note: If the API call includes a query, then the sort
+#       order will be by the relevance score. If no query is included, then the sort order
+#       will be by DOI update date.
+#   @param order [String] Sort order, one of 'asc' or 'desc'
+#   @param facet [Boolean/String] Include facet results OR a query (e.g., `license:*`) to facet by
+#       license. Default: false
+#   @param verbose [Boolean] Print request headers to stdout. Default: false
+
+# @!macro gbif_options
+#   @param options [Hash] Hash of options for configuring the request, passed on to Faraday.new
+#     - timeout [Fixnum] open/read timeout Integer in seconds
+#     - open_timeout [Fixnum] read timeout Integer in seconds
+#     - proxy [Hash] hash of proxy options
+#       - uri [String] Proxy Server URI
+#       - user [String] Proxy server username
+#       - password [String] Proxy server password
+#     - params_encoder [Hash] not sure what this is
+#     - bind [Hash] A hash with host and port values
+#     - boundary [String] of the boundary value
+#     - oauth [Hash] A hash with OAuth details
+
+##
+# gbif - The top level module for using methods to access the GBIF API
+
+module Gbif
+  extend Configuration
+
+  define_setting :user_name
+  define_setting :pwd
+  define_setting :base_url, "https://api.gbif.org/v1"
+
+end

data/lib/gbifrb/Occurrences.rb

@@ -0,0 +1,399 @@
+require "faraday"
+require 'faraday_middleware'
+require "multi_json"
+require "gbifrb/error"
+require "gbifrb/request"
+require "gbifrb/constants"
+require 'gbifrb/helpers/configuration'
+require 'gbifrb/faraday'
+require 'gbifrb/utils'
+
+##
+# Gbif::Occurrences
+module Gbif
+  module Occurrences
+    ##
+    # Search GBIF occurrences
+    #
+    # @param taxonKey [int] A GBIF occurrence identifier
+    # @param q [String] Simple search parameter. The value for this parameter can be a simple word or a phrase.
+    # @param spellCheck [bool] If 'true' ask GBIF to check your spelling of the value passed to the 'search' parameter.
+    #       IMPORTANT: This only checks the input to the 'search' parameter, and no others. Default: 'false'
+    # @param repatriated [String] Searches for records whose publishing country is different to the country where the record was recorded in
+    # @param kingdomKey [int] Kingdom classification key
+    # @param phylumKey [int] Phylum classification key
+    # @param classKey [int] Class classification key
+    # @param orderKey [int] Order classification key
+    # @param familyKey [int] Family classification key
+    # @param genusKey [int] Genus classification key
+    # @param subgenusKey [int] Subgenus classification key
+    # @param scientificName [String] A scientific name from the GBIF backbone. All included and synonym taxa are included in the search.
+    # @param datasetKey [String] The occurrence dataset key (a uuid)
+    # @param catalogNumber [String] An identifier of any form assigned by the source within a physical collection or digital dataset for the record which may not unique, but should be fairly unique in combination with the institution and collection code.
+    # @param recordedBy [String] The person who recorded the occurrence.
+    # @param collectionCode [String] An identifier of any form assigned by the source to identify the physical collection or digital dataset uniquely within the text of an institution.
+    # @param institutionCode [String] An identifier of any form assigned by the source to identify the institution the record belongs to. Not guaranteed to be que.
+    # @param country [String] The 2-letter country code (as per ISO-3166-1) of the country in which the occurrence was recorded. See here http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+    # @param basisOfRecord [String] Basis of record, as defined in our BasisOfRecord enum here http://gbif.github.io/gbif-api/apidocs/org/gbifrb/api/vocabulary/BasisOfRecord.html Acceptable values are:
+    #    - 'FOSSIL_SPECIMEN' An occurrence record describing a fossilized specimen.
+    #    - 'HUMAN_OBSERVATION' An occurrence record describing an observation made by one or more people.
+    #    - 'LITERATURE' An occurrence record based on literature alone.
+    #    - 'LIVING_SPECIMEN' An occurrence record describing a living specimen, e.g.
+    #    - 'MACHINE_OBSERVATION' An occurrence record describing an observation made by a machine.
+    #    - 'OBSERVATION' An occurrence record describing an observation.
+    #    - 'PRESERVED_SPECIMEN' An occurrence record describing a preserved specimen.
+    #    - 'UNKNOWN' Unknown basis for the record.
+    ## @param eventDate [date] Occurrence date in ISO 8601 format: yyyy, yyyy-MM, yyyy-MM-dd, or
+    #      MM-dd. Supports range queries, smaller,larger (e.g., '1990,1991', whereas '1991,1990'
+    #      wouldn't work)
+    # @param year [int] The 4 digit year. A year of 98 will be interpreted as AD 98. Supports range queries,
+    #      smaller,larger (e.g., '1990,1991', whereas '1991,1990' wouldn't work)
+    # @param month [int] The month of the year, starting with 1 for January. Supports range queries,
+    #      smaller,larger (e.g., '1,2', whereas '2,1' wouldn't work)
+    # @param decimalLatitude [float] Latitude in decimals between -90 and 90 based on WGS 84.
+    #      Supports range queries, smaller,larger (e.g., '25,30', whereas '30,25' wouldn't work)
+    # @param decimalLongitude [float] Longitude in decimals between -180 and 180 based on WGS 84.
+    #      Supports range queries (e.g., '-0.4,-0.2', whereas '-0.2,-0.4' wouldn't work).
+    # @param publishingCountry [String] The 2-letter country code (as per ISO-3166-1) of the
+    #      country in which the occurrence was recorded.
+    # @param elevation [int/str] Elevation in meters above sea level. Supports range queries, smaller,larger
+    #      (e.g., '5,30', whereas '30,5' wouldn't work)
+    # @param depth [int/str] Depth in meters relative to elevation. For example 10 meters below a
+    #      lake surface with given elevation. Supports range queries, smaller,larger (e.g., '5,30',
+    #      whereas '30,5' wouldn't work)
+    # @param geometry [String] Searches for occurrences inside a polygon described in Well Known
+    #      Text (WKT) format. A WKT shape written as either POINT, LINESTRING, LINEARRING
+    #      POLYGON, or MULTIPOLYGON. Example of a polygon: '((30.1 10.1, 20, 20 40, 40 40, 30.1 10.1))' would be queried as http://bit.ly/1BzNwDq.
+    # @param hasGeospatialIssue [bool] Includes/excludes occurrence records which contain spatial
+    #      issues (as determined in our record interpretation), i.e. 'hasGeospatialIssue=TRUE'
+    #      returns only those records with spatial issues while 'hasGeospatialIssue=FALSE' includes
+    #      only records without spatial issues. The absence of this parameter returns any
+    #      record with or without spatial issues.
+    # @param issue [String] One or more of many possible issues with each occurrence record. See
+    #      Details. Issues passed to this parameter filter results by the issue.
+    # @param hasCoordinate [bool] Return only occurence records with lat/long data ('true') or
+    #      all records ('false', default).
+    # @param typeStatus [String] Type status of the specimen. One of many options. See ?typestatus
+    # @param recordNumber [int] Number recorded by collector of the data, different from GBIF record
+    #      number. See http://rs.tdwg.org/dwc/terms/#recordNumber} for more info
+    # @param lastInterpreted [date] Date the record was last modified in GBIF, in ISO 8601 format:
+    #      yyyy, yyyy-MM, yyyy-MM-dd, or MM-dd.  Supports range queries, smaller,larger (e.g.,
+    #      '1990,1991', whereas '1991,1990' wouldn't work)
+    # @param continent [String] Continent. One of 'africa', 'antarctica', 'asia', 'europe', 'north_america'
+    #      (North America includes the Caribbean and reachies down and includes Panama), 'oceania',
+    #      or 'south_america'
+    # @param mediatype [String] Media type. Default is 'NULL', so no filtering on mediatype. Options:
+    #      'NULL', 'MovingImage', 'Sound', and 'StillImage'
+    # @param limit [int] Number of results to return. Default: '300'
+    # @param offset [int] Record to start at. Default: '0'
+    # @param verbose [Boolean] Print request headers to stdout. Default: false
+    # @param facet [String] a character vector of length 1 or greater
+    # @param establishmentMeans [String] EstablishmentMeans, possible values include: INTRODUCED,
+    #       INVASIVE, MANAGED, NATIVE, NATURALISED, UNCERTAIN
+    # @param facetMincount [int] minimum number of records to be included in the faceting results
+    # @param facetMultiselect [bool] Set to 'true' to still return counts for values that are not currently
+    #       filtered. See examples. Default: 'false'
+    # @!macro gbif_options
+    #
+    # @return [Hash] A hash
+    #
+    # @example
+    #       require 'gbifrb'
+    #       occ = Gbif::Occurrences
+    #
+    #       occ.search(taxonKey: 3329049)
+    #
+    #       # Return 2 results, this is the default by the way
+    #       occ.search(taxonKey: 3329049, limit: 2)
+    #
+    #       # Instead of getting a taxon key first, you can search for a name directly
+    #       # However, note that using this approach (with `scientificName="..."`)
+    #       # you are getting synonyms too. The results for using `scientifcName` and
+    #       # `taxonKey` parameters are the same in this case, but I wouldn't be surprised if for some
+    #       # names they return different results
+    #       occ.search(scientificName: 'Ursus americanus')
+    #       species = Gbif::Species
+    #       key = species.name_backbone(name: 'Ursus americanus', rank: 'species')['usageKey']
+    #       occ.search(taxonKey: key)
+    #
+    #       # Search by dataset key
+    #       occ.search(datasetKey: '7b5d6a48-f762-11e1-a439-00145eb45e9a', limit: 20)
+    #
+    #       # Search by catalog number
+    #       occ.search(catalogNumber: "49366", limit: 20)
+    #       occ.search(catalogNumber: ["49366","Bird.27847588"], limit: 20)
+    #
+    #       # Use paging parameters (limit and offset) to page. Note the different results
+    #       # for the two queries below.
+    #       occ.search(datasetKey: '7b5d6a48-f762-11e1-a439-00145eb45e9a', offset: 10, limit: 5)
+    #       occ.search(datasetKey: '7b5d6a48-f762-11e1-a439-00145eb45e9a', offset: 20, limit: 5)
+    #
+    #       # Many dataset keys
+    #       # occ.search(datasetKey: ["50c9509d-22c7-4a22-a47d-8c48425ef4a7", "7b5d6a48-f762-11e1-a439-00145eb45e9a"], limit: 20)
+    #       # Search by collector name
+    #       occ.search(recordedBy: "smith", limit: 20)
+    #
+    #       # Many collector names
+    #       occ.search(recordedBy: ["smith","BJ Stacey"], limit: 20)
+    #
+    #       # Search for many species
+    #       species = Gbif::Species
+    #       splist = ['Cyanocitta stelleri', 'Junco hyemalis', 'Aix sponsa']
+    #       keys = splist.map { |x| species.name_suggest(q: x)[0]['key'] }
+    #       out = keys.map { |z| occ.search(taxonKey: z, limit: 1) }
+    #       out.collect{ |b| b['results'][0]['speciesKey'] }
+    #
+    #       # Search - q parameter
+    #       occ.search(q: "kingfisher", limit: 20)
+    #
+    #       ## spell check - only works with the `search` parameter
+    #       ### spelled correctly - same result as above call
+    #       occ.search(q: "kingfisher", limit: 20, spellCheck: true)
+    #       ### spelled incorrectly - stops with suggested spelling
+    #       occ.search(q: "kajsdkla", limit: 20, spellCheck: true)
+    #       ### spelled incorrectly - stops with many suggested spellings
+    #       ###   and number of results for each
+    #       occ.search(q: "helir", limit: 20, spellCheck: true)
+    #
+    #       # Search on latitidue and longitude
+    #       occ.search(decimalLatitude: 50, decimalLongitude: 10, limit: 2)
+    #
+    #       # Search on a bounding box
+    #       ## in well known text format
+    #       occ.search(geometry: 'POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', limit: 20)
+    #       species = Gbif::Species
+    #       key = species.name_suggest(q: 'Aesculus hippocastanum')[0]['key']
+    #       occ.search(taxonKey: key, geometry: 'POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', limit: 20)
+    #
+    #       ## multipolygon
+    #       wkt = 'MULTIPOLYGON(((-123 38, -123 43, -116 43, -116 38, -123 38)),((-97 41, -97 45, -93 45, -93 41, -97 41)))'
+    #       occ.search(geometry: wkt, limit: 20)
+    #
+    #       # Search on country
+    #       occ.search(country: 'US', limit: 20)
+    #       occ.search(country: 'FR', limit: 20)
+    #       occ.search(country: 'DE', limit: 20)
+    #
+    #       # Get only occurrences with lat/long data
+    #       occ.search(taxonKey: key, hasCoordinate: true, limit: 20)
+    #
+    #       # Get only occurrences that were recorded as living specimens
+    #       occ.search(taxonKey: key, basisOfRecord: "LIVING_SPECIMEN", hasCoordinate: true, limit: 20)
+    #
+    #       # Get occurrences for a particular eventDate
+    #       occ.search(taxonKey: key, eventDate: "2013", limit: 20)
+    #       occ.search(taxonKey: key, year: "2013", limit: 20)
+    #       occ.search(taxonKey: key, month: "6", limit: 20)
+    #
+    #       # Get occurrences based on depth
+    #       key = species.name_backbone(name: 'Salmo salar', kingdom: 'animals')['usageKey']
+    #       occ.search(taxonKey: key, depth: "5", limit: 20)
+    #
+    #       # Get occurrences based on elevation
+    #       key = species.name_backbone(name: 'Puma concolor', kingdom: 'animals')['usageKey']
+    #       occ.search(taxonKey: key, elevation: 50, hasCoordinate: true, limit: 20)
+    #
+    #       # Get occurrences based on institutionCode
+    #       occ.search(institutionCode: "TLMF", limit: 20)
+    #
+    #       # Get occurrences based on collectionCode
+    #       occ.search(collectionCode: "Floristic Databases MV - Higher Plants", limit: 20)
+    #
+    #       # Get only those occurrences with spatial issues
+    #       occ.search(taxonKey: key, hasGeospatialIssue: true, limit: 20)
+    #
+    #       # Search using a query string
+    #       occ.search(q: "kingfisher", limit: 20)
+    #
+    #       # Range queries
+    #       ## See Detail for parameters that support range queries
+    #       ### this is a range depth, with lower/upper limits in character string
+    #       occ.search(depth: '50,100')
+    #
+    #       ## Range search with year
+    #       occ.search(year: '1999,2000', limit: 20)
+    #
+    #       ## Range search with latitude
+    #       occ.search(decimalLatitude: '29.59,29.6')
+    #
+    #       # Search by specimen type status
+    #       ## Look for possible values of the typeStatus parameter looking at the typestatus dataset
+    #       occ.search(typeStatus: 'allotype')
+    #
+    #       # Search by specimen record number
+    #       ## This is the record number of the person/group that submitted the data, not GBIF's numbers
+    #       ## You can see that many different groups have record number 1, so not super helpful
+    #       occ.search(recordNumber: 1)
+    #
+    #       # Search by last time interpreted: Date the record was last modified in GBIF
+    #       ## The lastInterpreted parameter accepts ISO 8601 format dates, including
+    #       ## yyyy, yyyy-MM, yyyy-MM-dd, or MM-dd. Range queries are accepted for lastInterpreted
+    #       occ.search(lastInterpreted: '2014-04-01')
+    #
+    #       # Search by continent
+    #       ## One of africa, antarctica, asia, europe, north_america, oceania, or south_america
+    #       occ.search(continent: 'south_america')
+    #       occ.search(continent: 'africa')
+    #       occ.search(continent: 'oceania')
+    #       occ.search(continent: 'antarctica')
+    #
+    #       # Search for occurrences with images
+    #       occ.search(mediatype: 'StillImage')
+    #       occ.search(mediatype: 'MovingImage')
+    #       occ.search(mediatype: 'Sound')
+    #
+    #       # Query based on issues
+    #       occ.search(taxonKey: 1, issue: 'DEPTH_UNLIKELY')
+    #       occ.search(taxonKey: 1, issue: ['DEPTH_UNLIKELY','COORDINATE_ROUNDED'])
+    #       # Show all records in the Arizona State Lichen Collection that cant be matched to the GBIF
+    #       # backbone properly:
+    #       occ.search(datasetKey: '84c0e1a0-f762-11e1-a439-00145eb45e9a', issue: ['TAXON_MATCH_nil','TAXON_MATCH_HIGHERRANK'])
+    #
+    #       # If you pass in an invalid polygon you get hopefully informative errors
+    #       ### the WKT string is fine, but GBIF says bad polygon
+    #       wkt = 'POLYGON((-178.59375 64.83258989321493,-165.9375 59.24622380205539,
+    #       -147.3046875 59.065977905449806,-130.78125 51.04484764446178,-125.859375 36.70806354647625,
+    #       -112.1484375 23.367471303759686,-105.1171875 16.093320185359257,-86.8359375 9.23767076398516,
+    #       -82.96875 2.9485268155066175,-82.6171875 -14.812060061226388,-74.8828125 -18.849111862023985,
+    #       -77.34375 -47.661687803329166,-84.375 -49.975955187343295,174.7265625 -50.649460483096114,
+    #       179.296875 -42.19189902447192,-176.8359375 -35.634976650677295,176.8359375 -31.835565983656227,
+    #       163.4765625 -6.528187613695323,152.578125 1.894796132058301,135.703125 4.702353722559447,
+    #       127.96875 15.077427674847987,127.96875 23.689804541429606,139.921875 32.06861069132688,
+    #       149.4140625 42.65416193033991,159.2578125 48.3160811030533,168.3984375 57.019804336633165,
+    #       178.2421875 59.95776046458139,-179.6484375 61.16708631440347,-178.59375 64.83258989321493))'
+    #       occ.search(geometry: wkt)
+    #
+    #       # Faceting
+    #       ## return no occurrence records with limit: 0
+    #       x = occ.search(facet: "country", limit: 0)
+    #       x['facets']
+    #
+    #       ## also return occurrence records
+    #       x = occ.search(facet: "establishmentMeans", limit: 10)
+    #       x['facets']
+    #       x['results']
+    #
+    #       ## multiple facet variables
+    #       x = occ.search(facet: ["country", "basisOfRecord"], limit: 10)
+    #       x['results']
+    #       x['facets']
+    #       x['facets']['country']
+    #       x['facets']['basisOfRecord']
+    #       x['facets']['basisOfRecord']['count']
+    #
+    #       ## set a minimum facet count
+    #       x = occ.search(facet: "country", facetMincount: 30000000L, limit: 0)
+    #       x['facets']
+    #
+    #       ## paging per each faceted variable
+    #       ### do so by passing in variables like "country" + "_facetLimit" = "country_facetLimit"
+    #       ### or "country" + "_facetOffset" = "country_facetOffset"
+    #       x = occ.search(
+    #         facet: ["country", "basisOfRecord", "hasCoordinate"],
+    #         country_facetLimit: 3,
+    #         basisOfRecord_facetLimit: 6,
+    #         limit: 0
+    #       )
+    #       x['facets']
+    #
+    #       # requests package options
+    #       ## There's an acceptable set of requests options (['timeout', 'cookies', 'auth',
+    #       ## 'allow_redirects', 'proxies', 'verify', 'stream', 'cert']) you can pass
+    #       ## in via **kwargs, e.g., set a timeout
+    #       x = occ.search(timeout: 1)
+
+    def self.search(taxonKey: nil, repatriated: nil,
+        kingdomKey: nil, phylumKey: nil, classKey: nil, orderKey: nil,
+        familyKey: nil, genusKey: nil, subgenusKey: nil, scientificName: nil,
+        country: nil, publishingCountry: nil, hasCoordinate: nil, typeStatus: nil,
+        recordNumber: nil, lastInterpreted: nil, continent: nil,
+        geometry: nil, recordedBy: nil, basisOfRecord: nil, datasetKey: nil,
+        eventDate: nil, catalogNumber: nil, year: nil, month: nil,
+        decimalLatitude: nil, decimalLongitude: nil, elevation: nil,
+        depth: nil, institutionCode: nil, collectionCode: nil,
+        hasGeospatialIssue: nil, issue: nil, q: nil, spellCheck: nil, mediatype: nil,
+        limit: 300, offset: 0, establishmentMeans: nil,
+        facet: nil, facetMincount: nil, facetMultiselect: nil,
+        verbose: nil, options: nil)
+
+        arguments = { taxonKey: taxonKey, repatriated: repatriated,
+             kingdomKey: kingdomKey, phylumKey: phylumKey, classKey: classKey,
+             orderKey: orderKey, familyKey: familyKey, genusKey: genusKey,
+             subgenusKey: subgenusKey, scientificName: scientificName,
+             country: country, publishingCountry: publishingCountry,
+             hasCoordinate: hasCoordinate, typeStatus: typeStatus,
+             recordNumber: recordNumber, lastInterpreted: lastInterpreted,
+             continent: continent, geometry: geometry, recordedBy: recordedBy,
+             basisOfRecord: basisOfRecord, datasetKey: datasetKey, eventDate: eventDate,
+             catalogNumber: catalogNumber, year: year, month: month,
+             decimalLatitude: decimalLatitude, decimalLongitude: decimalLongitude,
+             elevation: elevation, depth: depth, institutionCode: institutionCode,
+             collectionCode: collectionCode, hasGeospatialIssue: hasGeospatialIssue,
+             issue: issue, q: q, spellCheck: spellCheck, mediatype: mediatype,
+             limit: limit, offset: offset, establishmentMeans: establishmentMeans,
+             facetMincount: facetMincount, facet: facet,
+             facetMultiselect: facetMultiselect}.tostrings
+        opts = arguments.delete_if { |k, v| v.nil? }
+        return Request.new('occurrence/search', opts, verbose, options).perform
+    end
+
+    ##
+    # Gets details for a single, interpreted occurrence
+    #
+    # @param key [int] A GBIF occurrence key
+    #
+    # @return [hash]
+    #
+    # @example
+    #
+    #       require 'gbifrb'
+    #
+    #       occ = Gbif::Occurrences
+    #       occ.get(key: 1258202889)
+    #       occ.get(key: 1227768771)
+    def self.get(key:, verbose: nil, options: nil)
+        url = 'occurrence/' + key.to_s
+        Request.new(url, {}, verbose, options).perform
+    end
+
+    ##
+    # Gets a verbatim occurrence record without any interpretation
+    #
+    # @param key [int] A GBIF occurrence key
+    #
+    # @return [hash]
+    #
+    # @example
+    #
+    #     require 'gbifrb'
+    #
+    #     occ = Gbif::Occurrences
+    #     occ.get_verbatim(key: 1258202889)
+    #     occ.get_verbatim(key: 1227768771)
+    def self.get_verbatim(key:, verbose: nil, options: nil)
+        url = 'occurrence/' + key.to_s + '/verbatim'
+        Request.new(url, {}, verbose, options).perform
+    end
+
+    ##
+    # Get a single occurrence fragment in its raw form (xml or json)
+    #
+    # @param key [int] A GBIF occurrence key
+    #
+    # @return: [hash]
+    #
+    # @example
+    #
+    #     require 'gbifrb'
+    #
+    #     occ = Gbif::Occurrences
+    #     occ.get_fragment(key: 1052909293)
+    #     occ.get_fragment(key: 1227768771)
+    #     occ.get_fragment(key: 1227769518)
+    def self.get_fragment(key:, verbose: nil, options: nil)
+        url = 'occurrence/' + key.to_s + '/fragment'
+        Request.new(url, {}, verbose, options).perform
+    end
+
+  end
+end