outscraper 0.3.5 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9476b68f4bd7fc5b7af263cc5cb28b5e753960d760c44d1e697681123aee6236
-  data.tar.gz: 298ec43dbdec09108bbf6e98660b0e1150dce799d3408740a2c6d8fdbfd33c43
+  metadata.gz: 97c677370f1667c0a830e12a858fc1aa0a830182c145830205151cbf2a0719a3
+  data.tar.gz: 541a28805f574e7ad9d57df8a7d90bb43ee7b03128cc3ca33c45e5d7f0c93a76
 SHA512:
-  metadata.gz: fb819008c8e1a0e634c4a73779842810153156b7c22fc2ce94954e8a030ee363d8dc57127a0db61e190b40dab50d349a93c852d5faf1ebe1cefeba7b7674dde0
-  data.tar.gz: 2b8beb1a3fdf33a45d0bfc20f293516b535106dfb723f5499f831fea583e5f5788423033939665ce109536ac804ecb2b47dd17f016265f860c45efdb197a7fe2
+  metadata.gz: f67f131e3546b2628c35679312655d725fb18f9fa905d41030ca7744269b9508dc0f6dcba83d0ab30355ad43b4f7858a9b9209f08cbeada6ac7047bca57a8a32
+  data.tar.gz: 5d3d36c762fd24e04266b0bb4249ae9b3183de35bd27a77c39be630ccc2af243d4055d2bdac60a69814f80b7eca812d5be1d51af59a17d646805f517a767ae7a

data/README.md

@@ -22,7 +22,7 @@ require 'Outscraper'
 
 client = Outscraper::Client.new('SECRET_API_KEY')
 ```
-[Link to the profile page to create the API key](https://app.outscraper.com/profile)
+[Link to the account page to create the API key](https://app.outscraper.com/account/api)
 
 ## Usage
 

data/examples/Businesses.md

@@ -0,0 +1,208 @@
+# Businesses Search With Ruby
+
+The library provides real-time access to business records via the [Outscraper API](https://app.outscraper.com/api-docs).
+It supports classic structured filters and AI-powered plain-text queries for flexible search.
+
+- Structured search using `filters`, `fields`, `limit`, and other parameters
+- AI-powered search using the `query` parameter
+- Combined mode where structured params and `query` are merged by the server
+
+---
+
+## Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+```bash
+bundle add outscraper
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install outscraper
+```
+
+[Link to the Ruby package page](https://rubygems.org/gems/outscraper)
+
+---
+
+## Initialization
+
+```ruby
+require "outscraper"
+
+client = Outscraper::Client.new("SECRET_API_KEY")
+```
+
+[Link to the profile page to create the API key](https://app.outscraper.com/profile)
+
+---
+
+## Usage
+
+### Search businesses with structured filters
+
+```ruby
+results = client.businessesSearch(
+  filters: {
+    country_code: "US",
+    states: ["NY"],
+    cities: ["New York", "Buffalo"],
+    types: ["restaurant", "cafe"],
+    has_website: true,
+    has_phone: true,
+    business_statuses: ["operational"]
+  },
+  limit: 50,
+  include_total: false,
+  fields: ["name", "phone", "website", "address", "rating", "reviews"]
+)
+
+puts results
+```
+
+### Search businesses with AI plain-text query
+
+```ruby
+results = client.businessesSearch(
+  query: "Find cafes in New York, NY. Limit 25. Return name, address, phone, website, rating and reviews."
+)
+
+puts results
+```
+
+### Combine structured params and plain-text query
+
+```ruby
+results = client.businessesSearch(
+  filters: {
+    country_code: "US",
+    states: ["CA"],
+    types: ["restaurant"]
+  },
+  fields: ["name", "phone"],
+  limit: 15,
+  query: "Add cafes too. Return address and reviews. Limit 20. Include total."
+)
+
+puts results
+```
+
+When both structured params and `query` are provided:
+
+- `filters` and `fields` are merged
+- for `limit`, `cursor`, and `include_total`, plain-text values take priority when present
+- if a value is not specified, API defaults are used
+
+### Search businesses with enrichments
+
+`enrichments` can be provided in three formats:
+
+- **Hash (recommended)** — send a structured object with options per enrichment
+- **Array** — enable enrichments without options
+- **String** — enable a single enrichment without options
+
+#### Enrichments as Hash (recommended)
+
+```ruby
+results = client.businessesSearch(
+  filters: {
+    country_code: "US",
+    states: ["CA", "NY"],
+    types: ["restaurant", "cafe"]
+  },
+  limit: 10,
+  fields: ["name", "phone", "website", "rating", "reviews"],
+  enrichments: {
+    "contacts_n_leads" => {
+      "contacts_per_company" => 4,
+      "emails_per_contact" => 2
+    },
+    "company_insights" => {}
+  }
+)
+
+puts results
+```
+
+#### Enrichments as Array
+
+```ruby
+results = client.businessesSearch(
+  filters: { country_code: "US", states: ["NY"] },
+  limit: 10,
+  enrichments: ["contacts_n_leads", "company_insights"]
+)
+
+puts results
+```
+
+#### Enrichments as String
+
+```ruby
+results = client.businessesSearch(
+  filters: { country_code: "US", states: ["NY"] },
+  limit: 10,
+  enrichments: "contacts_n_leads"
+)
+
+puts results
+```
+
+#### Full JSON-style parameters example
+
+```ruby
+params = {
+  filters: {
+    country_code: "US",
+    states: ["CA", "NY"],
+    types: ["restaurant", "cafe"]
+  },
+  limit: 900,
+  cursor: nil,
+  include_total: false,
+  fields: [
+    "name", "types", "address", "country", "website",
+    "phone", "rating", "reviews"
+  ],
+  enrichments: {
+    "contacts_n_leads" => {
+      "contacts_per_company" => 4,
+      "emails_per_contact" => 2
+    },
+    "company_insights" => {}
+  },
+  query: "Find hotels in California and Illinois with rating 4.2+ and status operational. Return fields: name, address, rating and reviews. Limit results to 6. Enrich data with contacts_n_leads. Contact per company set to 8"
+}
+
+results = client.businessesSearch(**params)
+puts results
+```
+
+### Iterate through all results (auto-pagination)
+
+```ruby
+items = client.businessesIterSearch(
+  filters: {
+    country_code: "US",
+    states: ["NY"],
+    business_statuses: ["operational"]
+  },
+  limit: 100,
+  fields: ["name", "phone", "address", "rating", "reviews"]
+)
+
+puts items.length
+```
+
+### Get business details by ID
+
+```ruby
+business = client.businessesGet(
+  "YOUR_BUSINESS_ID",
+  fields: ["name", "phone", "website", "address", "rating", "reviews"]
+)
+
+puts business
+```

data/lib/outscraper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Outscraper
-  VERSION = "0.3.5"
+  VERSION = "0.3.7"
 end

data/lib/outscraper.rb

@@ -378,7 +378,7 @@ module Outscraper
         async: async_request
       }).parsed_response['data']
     end
-    
+
     def yellowpages_search(query, location: 'New York, NY', limit: 100, region: nil, enrichment: [], fields: '', async_request: false, ui: nil, webhook: nil)
       enrichment_array = enrichment.is_a?(Array) ? enrichment : [enrichment]
       response = self.class.get('/yellowpages-search', query: {
@@ -412,25 +412,92 @@ module Outscraper
       include_total: false,
       cursor: nil,
       fields: nil,
+      enrichments: nil,
+      contacts_per_company: nil,
+      emails_per_contact: nil,
       async_request: false,
       ui: false,
-      webhook: nil
+      webhook: nil,
+      query: nil
     )
-      payload = {
-        filters: (filters || {}),
-        limit: limit,
-        include_total: include_total,
-        cursor: cursor,
-        fields: fields ? Array(fields) : nil,
-        async: async_request,
-        ui: ui,
-        webhook: webhook
-      }.compact
+      if contacts_per_company && contacts_per_company < 1
+        raise ArgumentError, 'contacts_per_company must be >= 1'
+      end
+
+      if emails_per_contact && emails_per_contact < 1
+        raise ArgumentError, 'emails_per_contact must be >= 1'
+      end
+
+enrichments_normalized = nil
+
+if enrichments.is_a?(Hash)
+  enrichments_normalized = enrichments
+elsif enrichments.is_a?(Array)
+  enrichments_normalized = enrichments
+elsif enrichments.is_a?(String) || enrichments.is_a?(Symbol)
+  enrichments_normalized = enrichments.to_s
+elsif !enrichments.nil?
+  enrichments_normalized = Array(enrichments)
+end
+
+if !contacts_per_company.nil? || !emails_per_contact.nil?
+  cpp = contacts_per_company || 3
+  epc = emails_per_contact || 1
+
+  case enrichments_normalized
+  when nil
+    enrichments_normalized = { 'contacts_n_leads' => { 'contacts_per_company' => cpp, 'emails_per_contact' => epc } }
+  when Hash
+    enrichments_normalized['contacts_n_leads'] ||= {}
+    enrichments_normalized['contacts_n_leads']['contacts_per_company'] = cpp
+    enrichments_normalized['contacts_n_leads']['emails_per_contact'] = epc
+  when Array
+    unless enrichments_normalized.map(&:to_s).include?('contacts_n_leads')
+      raise ArgumentError, 'contacts_per_company and emails_per_contact require enrichments to include "contacts_n_leads"'
+    end
+    # Expand array to object so we can include options
+    expanded = {}
+    enrichments_normalized.each { |name| expanded[name.to_s] = {} }
+    expanded['contacts_n_leads']['contacts_per_company'] = cpp
+    expanded['contacts_n_leads']['emails_per_contact'] = epc
+    enrichments_normalized = expanded
+  when String
+    unless enrichments_normalized == 'contacts_n_leads'
+      raise ArgumentError, 'contacts_per_company and emails_per_contact require enrichments to include "contacts_n_leads"'
+    end
+    enrichments_normalized = { 'contacts_n_leads' => { 'contacts_per_company' => cpp, 'emails_per_contact' => epc } }
+  else
+    raise ArgumentError, 'Invalid enrichments type'
+  end
+end
+
+payload = {
+  filters: (filters || {}),
+  limit: limit,
+  include_total: include_total,
+  cursor: cursor,
+  fields: fields ? Array(fields) : nil,
+  enrichments: enrichments_normalized,
+  query: query,
+  async: async_request,
+  ui: ui,
+  webhook: webhook
+}.compact
+
+postAPIRequest('/businesses', payload)
 
-      postAPIRequest('/businesses', payload)
     end
 
-    def businessesIterSearch(filters: {}, limit: 10, fields: nil, include_total: false)
+    def businessesIterSearch(
+      filters: {},
+      limit: 10,
+      fields: nil,
+      include_total: false,
+      enrichments: nil,
+      contacts_per_company: nil,
+      emails_per_contact: nil,
+      query: nil
+    )
       cursor = nil
       all_items = []
 
@@ -441,6 +508,10 @@ module Outscraper
           include_total: include_total,
           cursor: cursor,
           fields: fields,
+          enrichments: enrichments,
+          contacts_per_company: contacts_per_company,
+          emails_per_contact: emails_per_contact,
+          query: query,
           async_request: false
         )
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: outscraper
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.7
 platform: ruby
 authors:
 - Outscraper
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-26 00:00:00.000000000 Z
+date: 2026-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -39,6 +39,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/Businesses.md
 - examples/Company Insights.md
 - examples/Company Website Finder.md
 - examples/Contacts And Leads.md