From 883565ab483684032cd98c7d8e4328a817492d8a Mon Sep 17 00:00:00 2001 From: Stepbus Date: Wed, 26 Nov 2025 15:39:24 +0200 Subject: [PATCH 1/3] added contacts and leads, examples --- examples/Contacts And Leads.md | 41 ++++++++++++++++++++ examples/Enrichments.md | 69 ++++++++++++++++++++++++++++++++++ outscraper.php | 56 +++++++++++++++++++++++++++ 3 files changed, 166 insertions(+) create mode 100644 examples/Contacts And Leads.md create mode 100644 examples/Enrichments.md diff --git a/examples/Contacts And Leads.md b/examples/Contacts And Leads.md new file mode 100644 index 0000000..6aea1aa --- /dev/null +++ b/examples/Contacts And Leads.md @@ -0,0 +1,41 @@ +# Emails And Contacts Scraper With PHP + +Allows finding email addresses, social links, and phones from domains via [Outscraper API](https://app.outscraper.cloud/api-docs#tag/Email-Related/paths/~1contacts-and-leads/get). + +## Installation + +### Composer + +You can install the bindings via [Composer](http://getcomposer.org/). Run the following command: + +```bash +composer require outscraper/outscraper +``` + +To use the bindings, use Composer's [autoload](https://getcomposer.org/doc/01-basic-usage.md#autoloading): + +```php +require_once('vendor/autoload.php'); +``` + +### Manual Installation + +If you do not wish to use Composer, you can download the [latest release](https://github.com/outscraper/outscraper-php/releases). Then, to use the bindings, include the `init.php` file. + +```php +require_once('/path/to/outscraper-php/init.php'); +``` +[Link to the PHP package page](https://packagist.org/packages/outscraper/outscraper) + +## Initialization +```php +$client = new OutscraperClient('SECRET_API_KEY'); +``` +[Link to the profile page to create the API key](https://app.outscraper.cloud/profile) + +## Usage + +```php +# Search contacts from website: +$results = $client->contacts_and_leads(['outscraper.com']); +``` diff --git a/examples/Enrichments.md b/examples/Enrichments.md new file mode 100644 index 0000000..332240e --- /dev/null +++ b/examples/Enrichments.md @@ -0,0 +1,69 @@ +# Using Enrichments With PHP + +Using enrichments with [Outscraper API](https://app.outscraper.cloud/api-docs). + +## Installation + +### Composer + +You can install the bindings via [Composer](http://getcomposer.org/). Run the following command: + +```bash +composer require outscraper/outscraper +``` + +To use the bindings, use Composer's [autoload](https://getcomposer.org/doc/01-basic-usage.md#autoloading): + +```php +require_once('vendor/autoload.php'); +``` + +### Manual Installation + +If you do not wish to use Composer, you can download the [latest release](https://github.com/outscraper/outscraper-php/releases). Then, to use the bindings, include the `init.php` file. + +```php +require_once('/path/to/outscraper-php/init.php'); +``` +[Link to the PHP package page](https://packagist.org/packages/outscraper/outscraper) + +## Initialization +```php +$client = new OutscraperClient('SECRET_API_KEY'); +``` +[Link to the profile page to create the API key](https://app.outscraper.cloud/profile) + +## Usage + +```php +// Enriching Google Maps results with Contacts & Leads, Email Validator, +// Company Insights, Phone Enricher, and Whitepages Phones: +$results = $client->google_maps_search( + query: "bars ny usa", + enrichment: [ + 'contacts_n_leads', // Contacts & Leads Enrichment + 'emails_validator_service', // Email Address Verifier + 'company_insights_service', // Company Insights + 'phones_enricher_service', // Phone Numbers Enricher + 'whitepages_phones', // Phone Identity Finder + ] +); +``` + +## Available values + +`contacts_n_leads` — **Contacts & Leads Enrichment**: finds emails, social links, phones, and other contacts from websites; + +`emails_validator_service` — **Email Address Verifier**: validates emails, checks deliverability, filters out blacklists, spam traps, and complainers, while significantly reducing your bounce rate; + +`disposable_email_checker` — **Disposable Emails Checker**: checks origins of email addresses (disposable, free, or corporate); + +`company_insights_service` — **Company Insights**: finds company details such as revenue, size, founding year, public status, etc; + +`phones_enricher_service` — **Phone Numbers Enricher**: returns phones carrier data (name/type), validates phones, ensures messages deliverability; + +`trustpilot_service` — **Trustpilot Scraper**: returns data from a list of businesses; + +`whitepages_phones` - **Phone Identity Finder**: returns insights about phone number owners (name, address, etc.); + +`ai_chain_info` - **Chain Info**: identifies if a business is part of a chain, adding a true/false indication to your data for smarter targeting. diff --git a/outscraper.php b/outscraper.php index bf5b074..05dd3ac 100644 --- a/outscraper.php +++ b/outscraper.php @@ -498,6 +498,62 @@ public function google_play_reviews( return $this->wait_request_archive($result['id']); } + /** + * Contacts and Leads Scraper. + * + * Returns emails, social links, phones, and other contacts from websites + * based on domain names or URLs. Supports batching by sending arrays with + * up to 250 queries and allows multiple queries to be sent in one request + * to save on network latency. + * + * @param string|array $query Company domains or URLs + * (e.g. 'outscraper.com' or ['tesla.com', 'microsoft.com']). + * @param string|array $fields Defines which fields to include in each returned item. + * By default, all fields are returned. + * @param bool $async_request Whether to run the request asynchronously. + * Default is true. + * @param string|array|null $preferred_contacts Contact roles you want to prioritize + * (e.g. 'influencers', 'technical', ['decision makers', 'sales']). + * @param int $contacts_per_company Number of contacts to return per company. Default is 3. + * @param int $emails_per_contact Number of email addresses to return per contact. Default is 1. + * @param bool $general_emails Whether to include only general emails + * (info@, support@, etc.) or only non-general emails + * (paul@, john@, etc.). Default is false. + * @param bool $ui Execute as a UI task. Overrides async mode on the API side. + * Default is false. + * @param string|null $webhook URL for callback notifications when a task completes. + * + * @return array Request/task result. If $async_request is true, returns the task meta + * (with ID). If false, waits for completion and returns the archived result. + */ + public function contacts_and_leads( + string|array $query, + string|array $fields = [], + bool $async_request = true, + string|array|null $preferred_contacts = null, + int $contacts_per_company = 3, + int $emails_per_contact = 1, + bool $general_emails = false, + bool $ui = false, + ?string $webhook = null + ): array { + $params = http_build_query([ + 'query' => (array) $query, + 'fields' => $fields, + 'async' => $async_request, + 'preferred_contacts' => $preferred_contacts, + 'contacts_per_company'=> $contacts_per_company, + 'emails_per_contact' => $emails_per_contact, + 'general_emails' => $general_emails, + 'ui' => $ui, + 'webhook' => $webhook, + ]); + + $result = $this->make_get_request("contacts-and-leads?{$params}"); + + return $async_request ? $result : $this->wait_request_archive($result['id']); + } + /** * Return email addresses, social links and phones from domains in seconds. * From 122c0f54d5b0bb1eb82854abb97aee92ffc0b7a6 Mon Sep 17 00:00:00 2001 From: Stepbus Date: Thu, 27 Nov 2025 09:32:20 +0200 Subject: [PATCH 2/3] bump version to 4.2.3 --- outscraper.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/outscraper.php b/outscraper.php index 05dd3ac..13296c0 100644 --- a/outscraper.php +++ b/outscraper.php @@ -6,11 +6,11 @@ * * @copyright Outscraper 2025 * @license https://raw.githubusercontent.com/outscraper/outscraper-php/main/LICENSE - * @version Release: 4.2.2 + * @version Release: 4.2.3 * @link https://github.com/outscraper/outscraper-php */ class OutscraperClient { - public $version = "4.2.2"; + public $version = "4.2.3"; private $api_url = "https://api.app.outscraper.com"; private $api_headers; private $max_ttl = 60 * 60; From 8d651bb4c136eca06f1cce8668d82f9912afc1d9 Mon Sep 17 00:00:00 2001 From: Stepbus Date: Fri, 28 Nov 2025 10:03:44 +0200 Subject: [PATCH 3/3] code refactoring --- outscraper.php | 58 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 23 deletions(-) diff --git a/outscraper.php b/outscraper.php index 13296c0..e123ac7 100644 --- a/outscraper.php +++ b/outscraper.php @@ -504,46 +504,54 @@ public function google_play_reviews( * Returns emails, social links, phones, and other contacts from websites * based on domain names or URLs. Supports batching by sending arrays with * up to 250 queries and allows multiple queries to be sent in one request - * to save on network latency. - * - * @param string|array $query Company domains or URLs - * (e.g. 'outscraper.com' or ['tesla.com', 'microsoft.com']). - * @param string|array $fields Defines which fields to include in each returned item. - * By default, all fields are returned. - * @param bool $async_request Whether to run the request asynchronously. - * Default is true. - * @param string|array|null $preferred_contacts Contact roles you want to prioritize - * (e.g. 'influencers', 'technical', ['decision makers', 'sales']). - * @param int $contacts_per_company Number of contacts to return per company. Default is 3. - * @param int $emails_per_contact Number of email addresses to return per contact. Default is 1. - * @param bool $general_emails Whether to include only general emails - * (info@, support@, etc.) or only non-general emails - * (paul@, john@, etc.). Default is false. - * @param bool $ui Execute as a UI task. Overrides async mode on the API side. - * Default is false. - * @param string|null $webhook URL for callback notifications when a task completes. + * to save on network latency time. + * + * @param string|array $query Company domains or URLs + * (e.g. 'outscraper.com' or ['tesla.com', 'microsoft.com']). + * @param string|array|null $fields Defines which fields to include in each returned item. + * By default, all fields are returned. + * @param bool $async_request The parameter defines the way you want to submit your task. + * When true, the request is submitted asynchronously and the + * method returns the task meta (ID). When false, the client + * waits for the archived result and returns the final data. + * @param string|array|null $preferred_contacts Contact roles you want to prioritize + * (e.g. 'influencers', 'technical', ['decision makers', 'sales']). + * @param int $contacts_per_company Number of contacts to return per company. Default is 3. + * @param int $emails_per_contact Number of email addresses to return per contact. Default is 1. + * @param int $skip_contacts Number of contacts to skip (for pagination). Default is 0. + * @param bool $general_emails Whether to include only general emails + * (info@, support@, etc.) or only non-general emails + * (paul@, john@, etc.). Default is false. + * @param bool $ui Execute as a UI task. On the API side this forces async mode. + * Default is false. + * @param string|null $webhook URL for callback notifications when a task completes. * * @return array Request/task result. If $async_request is true, returns the task meta - * (with ID). If false, waits for completion and returns the archived result. + * (with ID). If false, waits for completion and returns the archived result data. */ public function contacts_and_leads( string|array $query, - string|array $fields = [], + string|array|null $fields = null, bool $async_request = true, string|array|null $preferred_contacts = null, int $contacts_per_company = 3, int $emails_per_contact = 1, + int $skip_contacts = 0, bool $general_emails = false, bool $ui = false, ?string $webhook = null ): array { + $queries = (array) $query; + $wait_async = $async_request || count($queries) > 1; + $params = http_build_query([ - 'query' => (array) $query, + 'query' => $queries, 'fields' => $fields, - 'async' => $async_request, + 'async' => $wait_async, 'preferred_contacts' => $preferred_contacts, 'contacts_per_company'=> $contacts_per_company, 'emails_per_contact' => $emails_per_contact, + 'skip_contacts' => $skip_contacts, 'general_emails' => $general_emails, 'ui' => $ui, 'webhook' => $webhook, @@ -551,7 +559,11 @@ public function contacts_and_leads( $result = $this->make_get_request("contacts-and-leads?{$params}"); - return $async_request ? $result : $this->wait_request_archive($result['id']); + if ($async_request) { + return $result; + } + + return $this->wait_request_archive($result['id']); } /**