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..e123ac7 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; @@ -498,6 +498,74 @@ 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 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 data. + */ + public function contacts_and_leads( + string|array $query, + 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' => $queries, + 'fields' => $fields, + '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, + ]); + + $result = $this->make_get_request("contacts-and-leads?{$params}"); + + if ($async_request) { + return $result; + } + + return $this->wait_request_archive($result['id']); + } + /** * Return email addresses, social links and phones from domains in seconds. *