ctg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 253da2955e02d909c0f837ce71754ff59db75ce89184ffbd4e88c57d78f69620
+  data.tar.gz: '09738e44927002ad9b592ffd5b681b4948c28b61a26bf4d2efc04f6bdf565864'
+SHA512:
+  metadata.gz: ee424742892b4373f3c4738273c7a7f1b4aaa5e66a6f88c50a4f2d90b5e2e5c767ebd2ad35d630610b8399f6aafdd6161edc2512cf5a6898be695417c11b3e17
+  data.tar.gz: 66019a9f7d97dfb64a9f9f3e8d0b0b3dc9c2ce28bd8abf49dbdc1c528e202d3b9b7616bd6c4ea4ecc2493985c37a0a14760d1092c63a4cb15d7b7bb6abd12bdf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Leonid Stoianov
+
+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,300 @@
+# CTG
+
+`CTG` is a Ruby client library for interacting with the ClinicalTrials.gov API. It allows you to fetch and query clinical study data, including study metadata, search areas, study sizes, field values, and more. The library supports both JSON and CSV response formats, with built-in support for pagination and advanced querying.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ctg'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install ctg
+```
+
+## Usage
+
+### Initializing the Client
+
+To start using the `CTG`, first create a new client instance:
+
+```ruby
+require 'ctg'
+
+client = CTG.new
+```
+
+### Fetching Studies
+
+You can fetch studies using the `studies` method. This will return a `CTG::Response` object that you can query.
+
+```ruby
+response = client.studies('query.term' => 'cancer')
+studies = response.query('studies')
+puts studies
+```
+
+### Fetching a Single Study by NCT Number
+
+You can fetch a single study by its NCT number:
+
+```ruby
+response = client.number('NCT04050163')
+study = response.query('nctId')
+puts study  
+```
+
+### Fetching Study Metadata
+
+To fetch metadata information about study fields:
+
+```ruby
+response = client.metadata
+metadata = response.data
+puts metadata
+```
+
+### Handling Pagination
+
+If your query returns multiple pages of results, you can fetch the next page using the `next_page` method:
+
+```ruby
+response = client.studies('query.term' => 'cancer', 'pageSize' => 5)
+puts response.query('studies')
+
+next_page_response = response.next_page
+puts next_page_response.query('studies') if next_page_response
+```
+
+### Querying the Response
+
+You can query JSON responses using keys or XPath expressions:
+
+```ruby
+response = client.number('NCT04050163')
+nct_id = response.query('nctId')
+puts nct_id  # Outputs 'NCT04050163'
+```
+
+For CSV responses, query by column name:
+
+```ruby
+response = client.number('NCT04050163', format: 'csv')
+nct_ids = response.query('NCT Number')
+puts nct_ids
+```
+
+### Finding a Specific Key in JSON Data
+
+You can find the first occurrence of a specific key within the JSON data using the `find` method:
+
+```ruby
+response = client.number('NCT04050163')
+nct_id = response.find('nctId')
+puts nct_id  # Outputs 'NCT04050163'
+```
+
+## CTG::Query Object
+
+The `CTG::Query` class is designed to help you build complex queries for searching clinical studies on ClinicalTrials.gov. It provides a convenient way to add different query parameters and filters, allowing for advanced search capabilities.
+
+### Creating a Query
+
+To start building a query, you first need to create an instance of the `CTG::Query` class:
+
+```ruby
+query = CTG::Query.new
+```
+
+### Adding Query Parameters
+
+The `CTG::Query` object allows you to add various search parameters using method chaining. Below are the available methods:
+
+#### `condition(condition)`
+Adds a condition or disease to the query.
+
+- **Parameter**: `condition` (String) - The condition or disease to search for.
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.condition('diabetes')
+```
+
+#### `term(term)`
+Adds additional search terms to the query.
+
+- **Parameter**: `term` (String) - Additional search terms.
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.term('lung cancer')
+```
+
+#### `location(location)`
+Adds a location filter to the query.
+
+- **Parameter**: `location` (String) - The location term to filter results by.
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.location('New York')
+```
+
+#### `title(title)`
+Adds a title or acronym to the query.
+
+- **Parameter**: `title` (String) - The title or acronym to search for.
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.title('COVID-19 Vaccine')
+```
+
+#### `intervention(intervention)`
+Adds an intervention or treatment to the query.
+
+- **Parameter**: `intervention` (String) - The intervention or treatment to search for.
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.intervention('remdesivir')
+```
+
+#### `outcome(outcome)`
+Adds an outcome measure to the query.
+
+- **Parameter**: `outcome` (String) - The outcome measure to search for.
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.outcome('survival rate')
+```
+
+#### `collaborator(collaborator)`
+Adds a sponsor or collaborator to the query.
+
+- **Parameter**: `collaborator` (String) - The sponsor or collaborator to search for.
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.collaborator('IQVIA')
+```
+
+#### `sponsor(lead_sponsor)`
+Adds a lead sponsor to the query.
+
+- **Parameter**: `sponsor` (String) - The lead sponsor to search for.
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.sponsor('National Institutes of Health')
+```
+
+#### `study_id(study_id)`
+Adds a study ID filter to the query.
+
+- **Parameter**: `study_id` (String) - The study ID or IDs to search for (comma- or space-separated).
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.study_id('NCT01234567')
+```
+
+#### `status(*statuses)`
+Adds an overall status filter to the query.
+
+- **Parameter**: `statuses` (Array<String>) - The list of statuses to filter by (e.g., `['RECRUITING', 'COMPLETED']`).
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.status('RECRUITING', 'COMPLETED')
+```
+
+#### `page_size(size)`
+Specifies the number of results per page.
+
+- **Parameter**: `size` (Integer) - The number of results to return per page (max 1000).
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.page_size(50)
+```
+
+#### `format(format)`
+Specifies the format of the response.
+
+- **Parameter**: `format` (String) - The format of the response (`'json'` or `'csv'`).
+- **Returns**: The updated `CTG::Query` object.
+
+```ruby
+query = CTG::Query.new.format('json')
+```
+
+### Retrieving Query Parameters
+
+Once you’ve built your query, you can retrieve the complete set of query parameters as a hash:
+
+```ruby
+query_params = query.params
+```
+
+This `params` method returns a hash of all the query parameters that have been set.
+
+### Example: Building a Complex Query
+
+Here’s an example of how you might build a more complex query using method chaining:
+
+```ruby
+query = CTG::Query.new
+  .condition('diabetes')
+  .term('insulin')
+  .location('California')
+  .status('RECRUITING')
+  .page_size(10)
+  .format('json')
+
+# Use the query in a client request
+response = client.studies(query)
+puts response.query('studies', 'protocolSection', 'outcomesModule', 'secondaryOutcomes' )
+```
+
+In this example, the query is set to search for recruiting studies related to diabetes and insulin in California, returning results in JSON format with a page size of 10.
+
+### Finding All Occurrences of a Key in JSON Data
+
+If you need to find all occurrences of a specific key within the JSON data, use the `find_all` method:
+
+```ruby
+references = response.find_all('references')
+puts references 
+```
+
+
+## Running Tests
+
+To run the tests, use RSpec:
+
+```bash
+rspec
+```
+
+This will run all the tests located in the `spec/` directory and report on their success.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/trialize/ctg.
+
+## License
+
+This library is available as open source under the terms of the MIT License.
+Copyright 2024 Leonid Stoianov. Copyright 2024 Trialize.

data/lib/ctg/ctg.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# This file defines the main CTG class, which serves as the interface to interact
+# with the ClinicalTrials.gov API. It includes methods to fetch data for studies, metadata,
+# areas, and statistics. Each method returns a Response object that encapsulates the data
+# along with pagination capabilities.
+#
+# Methods:
+# - `studies`: Fetches a list of studies based on query parameters with support for pagination.
+# - `number`: Fetches data for a single study by its NCT number.
+# - `metadata`: Fetches metadata information about the study fields.
+# - `areas`: Fetches the list of search areas.
+
+require 'active_support/core_ext/hash'
+require 'httparty'
+
+require_relative 'query'
+require_relative 'response/json_response'
+require_relative 'response/csv_response'
+require_relative 'response'
+
+class CTG
+  include HTTParty
+  base_uri 'https://clinicaltrials.gov/api/v2'
+  attr_reader :response
+
+  def initialize
+    @headers = { 'Content-Type' => 'application/json' }
+    @response = nil
+  end
+
+  # Fetch a list of studies based on query parameters with support for pagination
+  # @param [CTG::Query, Hash] query - Query parameters for filtering studies
+  # @return [CTG::Response] - Response object wrapping the API response
+  def studies(query)
+    params = if query.is_a?(CTG::Query)
+               query.params
+             else
+               query.stringify_keys
+             end
+
+    get('/studies', params)
+
+    CTG::Response.parse(@response.body, params['format'] || 'json', self)
+  end
+
+  # Fetch data for a single study by its NCT number
+  # @param [String] nct_id - The NCT ID of the study
+  # @param [Hash] params - Additional query parameters
+  # @option params [String] :format ('json') - The format of the response ('json', 'csv', etc.)
+  # @option params [Array<String>] :fields - A list of fields to include in the response
+  # @option params [String] :markupFormat - Format for fields that include markup ('markdown', 'legacy')
+  # @return [CTG::Response] - Response object wrapping the API response
+  def number(nct_id, params = {})
+    get("/studies/#{nct_id}", params)
+    CTG::Response.parse(@response.body, params.stringify_keys['format'] || 'json', self)
+  end
+
+  # Fetch metadata information about the study fields
+  # @param [Hash] params - Additional query parameters
+  # @option params [Boolean] :includeIndexedOnly (false) - If true, includes fields that are indexed only
+  # @option params [Boolean] :includeHistoricOnly (false) - If true, includes fields available only in historic data
+  # @return [CTG::Response] - Response object wrapping the API response
+  def metadata(params = {})
+    get('/studies/metadata', params)
+    CTG::Response.parse(@response.body, 'json', self)
+  end
+
+  # Fetch the list of search areas
+  # This method doesn't require any specific query parameters.
+  # @return [CTG::Response] - Response object wrapping the API response
+  def areas
+    get('/studies/search-areas')
+    CTG::Response.parse(@response.body, 'json', self)
+  end
+
+  # Fetch statistics of study JSON sizes
+  # @return [CTG::Response] - Response object wrapping the API response
+  def study_sizes
+    get('/stats/size')
+    CTG::Response.parse(@response.body, 'json', self)
+  end
+
+  # Fetch value statistics of study leaf fields
+  # @param [Hash] params - Query parameters for filtering field values
+  # @option params [Array<String>] :types - Filter by field types (e.g., 'ENUM', 'BOOLEAN', 'STRING')
+  # @option params [Array<String>] :fields - Filter by specific fields or field paths of leaf fields
+  # @return [CTG::Response] - Response object wrapping the API response
+  def field_values(params = {})
+    get('/stats/field/values', params)
+    CTG::Response.parse(@response.body, 'json', self)
+  end
+
+  # Fetch sizes of list/array fields
+  # @param [Hash] params - Query parameters for filtering field sizes
+  # @option params [Array<String>] :fields - Filter by specific list/array fields or field paths
+  # @return [CTG::Response] - Response object wrapping the API response
+  def field_sizes(params = {})
+    get('/stats/field/sizes', params)
+    CTG::Response.parse(@response.body, 'json', self)
+  end
+
+
+  private
+
+  # @param [String] path - The API endpoint path to send the request to.
+  # @param [Hash] params - Query parameters to include in the request.
+  # @option params [Hash<String, String>] :headers - Optional headers to include in the request.
+  # @return [HTTParty::Response] - The raw response object from the HTTP request.
+  def get(path, params = {})
+    options = { headers: @headers, query: params }
+    @response = self.class.get(path, options)
+  end
+
+end

data/lib/ctg/query.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+# The `CTG::Query` class provides a way to build queries for the ClinicalTrials.gov API.
+# It allows chaining methods to specify various search parameters, including conditions,
+# terms, locations, sponsors, and more. The class also supports pagination, sorting, and
+# filtering of results. The built query can be used to fetch data in either JSON or CSV format.
+#
+# Example usage:
+#   query = CTG::Query.new
+#             .condition('diabetes')
+#             .location('New York')
+#             .status('RECRUITING', 'COMPLETED')
+#             .page_size(50)
+#             .sort_by('startDate', 'desc')
+#
+#   client.studies(query.params)
+#
+# Methods:
+# - `condition`: Adds a condition or disease to the query.
+# - `term`: Adds a term to the query.
+# - `location`: Adds a location filter to the query.
+# - `title`: Adds a title or acronym to the query.
+# - `intervention`: Adds an intervention or treatment to the query.
+# - `outcome`: Adds an outcome measure to the query.
+# - `sponsor`: Adds a sponsor or collaborator to the query.
+# - `lead_sponsor`: Adds a lead sponsor to the query.
+# - `study_id`: Adds a study ID filter to the query.
+# - `patient`: Adds a patient-related search to the query.
+# - `status`: Adds an overall status filter to the query.
+# - `geo_filter`: Adds a geographical filter based on distance.
+# - `nct_ids`: Adds a filter for specific NCT IDs.
+# - `advanced_filter`: Adds an advanced filter using the Essie expression syntax.
+# - `format`: Sets the response format (json or csv).
+# - `page_size`: Sets the number of results per page.
+# - `sort_by`: Sets the sorting order for the results.
+# - `total`: Counts the total number of results.
+# - `page_token`: Sets the token to get the next page of results.
+
+class CTG
+  class Query
+    attr_reader :params
+
+    def initialize
+      @params = {}
+    end
+
+    # Add a condition or disease to the query
+    # @param [String] condition - The condition or disease to filter studies by
+    # @return [CTG::Query] - The current instance for method chaining
+    def condition(condition)
+      @params['query.cond'] = condition
+      self
+    end
+
+    # Add a term to the query
+    # @param [String] term - Additional term to filter studies by
+    # @return [CTG::Query] - The current instance for method chaining
+    def term(term)
+      @params['query.term'] = term
+      self
+    end
+
+    # Add a location filter to the query
+    # @param [String] location - The location term to filter studies by
+    # @return [CTG::Query] - The current instance for method chaining
+    def location(location)
+      @params['query.locn'] = location
+      self
+    end
+
+    # Add a title or acronym to the query
+    # @param [String] title - The title or acronym to filter studies by
+    # @return [CTG::Query] - The current instance for method chaining
+    def title(title)
+      @params['query.titles'] = title
+      self
+    end
+
+    # Add an intervention or treatment to the query
+    # @param [String] intervention - The intervention or treatment to filter studies by
+    # @return [CTG::Query] - The current instance for method chaining
+    def intervention(intervention)
+      @params['query.intr'] = intervention
+      self
+    end
+
+    # Add an outcome measure to the query
+    # @param [String] outcome - The outcome measure to filter studies by
+    # @return [CTG::Query] - The current instance for method chaining
+    def outcome(outcome)
+      @params['query.outc'] = outcome
+      self
+    end
+
+    # Add a sponsor or collaborator to the query
+    # @param [String] sponsor - The sponsor or collaborator to filter studies by
+    # @return [CTG::Query] - The current instance for method chaining
+    def sponsor(sponsor)
+      @params['query.spons'] = sponsor
+      self
+    end
+
+    # Add a lead sponsor to the query
+    # @param [String] lead_sponsor - The lead sponsor to filter studies by
+    # @return [CTG::Query] - The current instance for method chaining
+    def lead_sponsor(lead_sponsor)
+      @params['query.lead'] = lead_sponsor
+      self
+    end
+
+    # Adds a study ID filter to the query
+    # @param [String] study_id - The study ID or IDs to search for (comma- or space-separated)
+    # @return [CTG::Query] - The updated query object
+    def study_id(study_id)
+      @params['query.id'] = study_id
+      self
+    end
+
+    # Add a patient-related search to the query
+    # @param [String] patient - The patient-related search term
+    # @return [CTG::Query] - The current instance for method chaining
+    def patient(patient)
+      @params['query.patient'] = patient
+      self
+    end
+
+    # Adds an overall status filter to the query
+    # @param [Array<String>] statuses - The list of statuses to filter by (e.g., ['RECRUITING', 'COMPLETED'])
+    # @return [CTG::Query] - The updated query object
+    def status(*statuses)
+      @params['filter.overallStatus'] = statuses.join(',')
+      self
+    end
+
+    # Add a geographical filter based on distance
+    # @param [String] geo - The geo-function filter (e.g., "distance(39.0035707,-77.1013313,50mi)")
+    # @return [CTG::Query] - The current instance for method chaining
+    def geo_filter(geo)
+      @params['filter.geo'] = geo
+      self
+    end
+
+    # Add a filter for specific NCT IDs
+    # @param [Array<String>] ids - List of NCT IDs to filter by
+    # @return [CTG::Query] - The current instance for method chaining
+    def nct_ids(*ids)
+      @params['filter.ids'] = ids.join('|')
+      self
+    end
+
+    # Add an advanced filter using the Essie expression syntax
+    # @param [String] expression - The advanced filter expression
+    # @return [CTG::Query] - The current instance for method chaining
+    def advanced_filter(expression)
+      @params['filter.advanced'] = expression
+      self
+    end
+
+    # Set the response format (json or csv)
+    # @param [String] format - The format for the response, either 'json' or 'csv'
+    # @return [CTG::Query] - The current instance for method chaining
+    def format(format = 'json')
+      @params['format'] = format
+      self
+    end
+
+    # Set the number of results per page.
+    # If not specified or set to 0, the default value will be used. It will be coerced down to 1,000, if greater than that.
+    # @param [Integer] page_size - The number of results to return per page
+    # @return [CTG::Query] - The current instance for method chaining
+    def page_size(page_size = 1000)
+      @params['pageSize'] = page_size
+      self
+    end
+
+    # Set the sorting order for the results
+    # @param [String] sort_by - The field to sort by
+    # @param [String] direction - The direction to sort (asc or desc)
+    # @return [CTG::Query] - The current instance for method chaining
+    def sort_by(sort_by, direction = 'asc')
+      @params['sort'] = "#{sort_by}:#{direction}"
+      self
+    end
+
+    # Count total number of studies. The parameter is ignored for the subsequent pages.
+    # @return [CTG::Query] - The current instance for method chaining
+    def total
+      @params['countTotal'] = true
+      self
+    end
+
+    # Token to get next page. Set it to a nextPageToken value returned with the
+    # previous page in JSON format. For CSV, it can be found in x-next-page-token response header.
+    # Do not specify it for first page.
+    # @return [CTG::Query] - The current instance for method chaining
+    def page_token(token)
+      @params['pageToken'] = token
+      self
+    end
+
+  end
+end

data/lib/ctg/response/csv_response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# This file defines the CTG::Response::CSVResponse class, which is a subclass of CTG::Response.
+# The CSVResponse class is responsible for handling responses in CSV format. It provides methods to query
+# the CSV data by column name.
+#
+# Methods:
+# - `initialize`: Initializes the CSVResponse object by parsing the CSV data.
+# - `query`: Queries the CSV data by column name.
+
+require 'csv'
+
+class CTG
+  class Response
+    class CSVResponse < Response
+      attr_reader :data
+
+      # Initializes the CSVResponse object by parsing the CSV data
+      # @param [String] response_body - The raw CSV response body from the API
+      # @param [CTG] client - The client instance to use for fetching subsequent pages
+      def initialize(response_body, client)
+        super(client)
+        @data = CSV.parse(response_body, headers: true)
+      end
+
+      # Queries the CSV data by column name
+      # @param [String] column_name - The name of the column to query
+      # @return [Array<String>] - An array of values from the specified column
+      def query(column_name)
+        @data.map { |row| row[column_name] }.compact
+      end
+
+    end
+  end
+end

data/lib/ctg/response/json_response.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# This file defines the CTG::Response::JSONResponse class, which is a subclass of CTGClient::Response.
+# The JSONResponse class is responsible for handling responses in JSON format. It provides methods to query
+# the JSON data by keys, as well as to find specific values or all occurrences of a key in the data.
+#
+# Methods:
+# - `initialize`: Initializes the JSONResponse object by parsing the JSON data.
+# - `query`: Queries the JSON data by keys.
+# - `find`: Finds the first occurrence of a specified key in the JSON data.
+# - `find_all`: Finds all occurrences of a specified key in the JSON data.
+
+
+require 'json'
+
+class CTG
+  class Response
+    class JSONResponse < Response
+      attr_reader :data
+
+      # Initializes the JSONResponse object by parsing the JSON data
+      # @param [String] response_body - The raw JSON response body from the API
+      # @param [CTG] client - The client instance to use for fetching subsequent pages
+      def initialize(response_body, client)
+        super(client)
+        @data = JSON.parse(response_body)
+      end
+
+      # Queries the JSON data by keys
+      # @param [Array<String>] keys - The sequence of keys to query the data
+      # @return [Object] - The queried data
+      def query(*keys)
+        keys.reduce(@data) do |current_data, key|
+          case current_data
+          when Array
+            case key
+            when '*' # Handle wildcard for array access
+              current_data.map { |element| element.is_a?(Hash) ? element : {} }
+            when Integer
+              current_data[key]
+            else
+              # If key is not an integer but the current data is an array, try to map over it
+              current_data.map { |element| element[key] if element.is_a?(Hash) }.compact
+            end
+          when Hash
+            current_data[key]
+          end
+        end
+      end
+
+      # Recursively find the first occurrence of a key in the JSON data
+      # @param [String] key - The key to find in the JSON data
+      # @param [Object] data - The current data to search within (used for recursion)
+      # @return [Object] - The value associated with the key, or nil if not found
+      def find(key, data = @data)
+        case data
+        when Hash
+          return data[key] if data.key?(key)
+
+          data.each_value do |value|
+            result = find(key, value)
+            return result if result
+          end
+        when Array
+          data.each do |element|
+            result = find(key, element)
+            return result if result
+          end
+        end
+        nil
+      end
+
+      def find_all(key)
+        results = []
+        stack = [@data]
+
+        until stack.empty?
+          current_data = stack.pop
+
+          case current_data
+          when Hash
+            results << current_data[key] if current_data.key?(key)
+            stack.concat(current_data.values)
+          when Array
+            stack.concat(current_data)
+          end
+        end
+
+        results.compact
+      end
+
+    end
+  end
+end

data/lib/ctg/response.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# This file defines the CTG::Response class, which serves as a wrapper around the response
+# returned by the ClinicalTrials.gov API. The Response class provides a common interface for working
+# with different response formats (JSON, CSV) and supports functionalities like pagination, querying
+# by keys.
+#
+# The CTG::Response class delegates the format-specific behavior to its subclasses,
+# CTG::Response::JSONResponse and CTG::Response::CSVResponse.
+#
+# Methods:
+# - `parse`: Factory method that returns an appropriate response object (JSON or CSV).
+# - `query`: Queries the response data by keys.
+# - `next_page`: Next page (if page token exists)
+
+class CTG
+  class Response
+    attr_reader :client
+
+    # Factory method to create an appropriate response object based on format
+    # @param [String] response_body - The raw response body from the API
+    # @param [String] format - The format of the response ('json' or 'csv')
+    # @param [CTG] client - The client instance to use for fetching subsequent pages
+    # @return [CTG::Response] - An instance of either JSONResponse or CSVResponse
+    def self.parse(response_body, format, client)
+      case format
+      when 'json'
+        JSONResponse.new(response_body, client)
+      when 'csv'
+        CSVResponse.new(response_body, client)
+      else
+        raise "Unsupported format: #{format}"
+      end
+    end
+
+    # Initializes the Response object
+    # @param [CTG] client - The client instance that made the request
+    def initialize(client)
+      @client = client
+    end
+
+    # Queries the response data by keys (to be implemented in subclasses)
+    # @param [Array<String>] keys - The sequence of keys to query the data
+    # @return [Object] - The queried data
+    def query(*keys)
+      raise NotImplementedError, 'Subclasses must implement the `query` method'
+    end
+
+    # @return [CTG::Response, nil]
+    #   - Returns a new Response object containing the next page of data.
+    #   - Returns `nil` if no next page token is found, indicating there is no further data.
+    def next_page
+      next_page_token = @client.response.headers['x-next-page-token'] || @data['nextPageToken']
+      return unless next_page_token
+
+      request = @client.response.request
+      format = request.options[:format] || 'json'
+
+      request.options[:query].merge! CTG::Query.new
+                                               .page_token(next_page_token)
+                                               .params
+
+      CTG::Response.parse(request.perform.body, format, @client)
+    end
+
+  end
+end

data/lib/ctg/version.rb

@@ -0,0 +1,5 @@
+# lib/ctg/version.rb
+
+module CTG
+  VERSION = "0.1.0"
+end

data/lib/ctg.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+#--
+# Copyright (c) Leonid Stoianov
+#
+# 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.
+#++
+
+require 'ctg/ctg'
+require 'ctg/query'
+require 'ctg/response'
+require 'ctg/response/csv_response'
+require 'ctg/response/json_response'

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: ctg
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leonid Stoianov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.3.2
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.23.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.23.1
+description: CTG is a Ruby library that provides an interface for querying the ClinicalTrials.gov
+  API. It supports both JSON and CSV formats, pagination, and complex queries.
+email:
+- leo@@trialize.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ctg.rb
+- lib/ctg/ctg.rb
+- lib/ctg/query.rb
+- lib/ctg/response.rb
+- lib/ctg/response/csv_response.rb
+- lib/ctg/response/json_response.rb
+- lib/ctg/version.rb
+homepage: https://github.com/trialize/ctg
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/trialize/ctg
+  changelog_uri: https://github.com/trialize/ctg/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: A Ruby client for interacting with the ClinicalTrials.gov API.
+test_files: []