diff --git a/examples/Businesses.md b/examples/Businesses.md index 1f2f08f..7c6bf8f 100644 --- a/examples/Businesses.md +++ b/examples/Businesses.md @@ -95,6 +95,91 @@ When both structured params and `query` are provided: - 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 diff --git a/lib/outscraper.rb b/lib/outscraper.rb index 948f5ca..7e921c9 100644 --- a/lib/outscraper.rb +++ b/lib/outscraper.rb @@ -378,7 +378,7 @@ def company_website_finder(query, fields: '', async_request: false) 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,27 +412,92 @@ def businessesSearch( include_total: false, cursor: nil, fields: nil, + enrichments: nil, + contacts_per_company: nil, + emails_per_contact: nil, async_request: false, ui: false, webhook: nil, query: nil ) - payload = { - filters: (filters || {}), - limit: limit, - include_total: include_total, - cursor: cursor, - fields: fields ? Array(fields) : nil, - query: query, - 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 = [] @@ -443,6 +508,10 @@ def businessesIterSearch(filters: {}, limit: 10, fields: nil, include_total: fal 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 ) diff --git a/lib/outscraper/version.rb b/lib/outscraper/version.rb index cc20a44..5352dfd 100644 --- a/lib/outscraper/version.rb +++ b/lib/outscraper/version.rb @@ -1,5 +1,5 @@ # frozen_string_literal: true module Outscraper - VERSION = "0.3.6" + VERSION = "0.3.7" end