add async_request option

outscraper · Jan 31, 2023 · c7fc994 · c7fc994
1 parent a2c0652
commit c7fc994
Show file tree

Hide file tree

Showing 2 changed files with 96 additions and 30 deletions.
diff --git a/examples/Run Async Requests.md b/examples/Run Async Requests.md
@@ -0,0 +1,56 @@
+# Run Async Requests to Outscraper API
+
+The example shows how to send async requests to Outscraper API and retrieve the results later using request IDs (the requests are processed in parallel).
+
+## 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.com/profile)
+
+## Usage
+
+```php
+$place_ids = array(
+    'ChIJNw4_-cWXyFYRF_4GTtujVsw',
+    'ChIJ39fGAcGXyFYRNdHIXy-W5BA',
+    'ChIJVVVl-cWXyFYRQYBCEkX0W5Y',
+    'ChIJScUP1R6XyFYR0sY1UwNzq-c',
+    'ChIJmeiNBMeXyFYRzQrnMMDV8Jc',
+    'ChIJifOTBMeXyFYRmu3EGp_QBuY',
+    'ChIJ1fwt-cWXyFYR2cjoDAGs9UI',
+    'ChIJ5zQrTzSXyFYRuiY31iE7M1s',
+    'ChIJQSyf4huXyFYRpP9W4rtBelA',
+    'ChIJRWK5W2-byFYRiaF9vVgzZA4'
+);
+
+foreach ($place_ids as &$place_id) {
+    $response = $client->google_maps_search([$place_id], language: 'en', region: 'us', async_request: TRUE);
+    print_r($response['id']);
+}
+```
diff --git a/outscraper.php b/outscraper.php
@@ -6,11 +6,11 @@
  *
  * @copyright  Outscraper 2021
  * @license    https://raw.githubusercontent.com/outscraper/outscraper-php/main/LICENSE
- * @version    Release: 1.1.0
+ * @version    Release: 3.0.0
  * @link       https://github.com/outscraper/outscraper-php
  */
 class OutscraperClient {
-    public $version = "2.0.1";
+    public $version = "3.0.0";
     private $api_url = "https://api.app.outscraper.com";
     private $api_headers;
     private $max_ttl = 60 * 60;
@@ -127,7 +127,7 @@ public function google_search(
     }
 
     /**
-     * Get data from Google Maps
+     * Get data from Google Maps (speed optimized endpoint)
      *
      * @param string|array $query Parameter defines the query or queries you want to search on Google Maps. Using an array allows multiple queries to be sent in one request and save on network latency time.
      * @param string $language Parameter specifies the language to use for Google. Available values: "en", "de", "es", "es-419", "fr", "hr", "it", "nl", "pl", "pt-BR", "pt-PT", "vi", "tr", "ru", "ar", "th", "ko", "zh-CN", "zh-TW", "ja", "ach", "af", "ak", "ig", "az", "ban", "ceb", "xx-bork", "bs", "br", "ca", "cs", "sn", "co", "cy", "da", "yo", "et", "xx-elmer", "eo", "eu", "ee", "tl", "fil", "fo", "fy", "gaa", "ga", "gd", "gl", "gn", "xx-hacker", "ht", "ha", "haw", "bem", "rn", "id", "ia", "xh", "zu", "is", "jw", "rw", "sw", "tlh", "kg", "mfe", "kri", "la", "lv", "to", "lt", "ln", "loz", "lua", "lg", "hu", "mg", "mt", "mi", "ms", "pcm", "no", "nso", "ny", "nn", "uz", "oc", "om", "xx-pirate", "ro", "rm", "qu", "nyn", "crs", "sq", "sk", "sl", "so", "st", "sr-ME", "sr-Latn", "su", "fi", "sv", "tn", "tum", "tk", "tw", "wo", "el", "be", "bg", "ky", "kk", "mk", "mn", "sr", "tt", "tg", "uk", "ka", "hy", "yi", "iw", "ug", "ur", "ps", "sd", "fa", "ckb", "ti", "am", "ne", "mr", "hi", "bn", "pa", "gu", "or", "ta", "te", "kn", "ml", "si", "lo", "my", "km", "chr".
@@ -136,28 +136,35 @@ public function google_search(
      * @param bool $extract_contacts Parameter specifies whether the bot will scrape additional data (emails, social links, site keywords…) from companies’ websites. It increases the time of the extraction.
      * @param string $coordinates Parameter defines the coordinates to use along with the query. Example: "@41.3954381,2.1628662,15.1z".
      * @param bool $drop_duplicates Parameter specifies whether the bot will drop the same organizations from different queries. Using the parameter combines results from each query inside one big array.
+     * @param int $skip Skip first N places, where N should be multiple to 20 (e.g. 0, 20, 40). It's commonly used in pagination.
+     * @param bool $async_request Parameter defines the way you want to submit your task to Outscraper. It can be set to `False` (default) to send a task and wait until you got your results, or `True` to submit your task and retrieve the results later using a request ID with `get_request_archive`. Each response is available for `2` hours after a request has been completed.
      *
      * @return array request/task result
      */
-    public function google_maps_search_v1(
+    public function google_maps_search(
         string|array $query, string $language = "en", string $region = NULL, int $limit = 400,
-        bool $extract_contacts = FALSE, string $coordinates = NULL, bool $drop_duplicates = FALSE
-    ) : array {
+        string $coordinates = NULL, bool $drop_duplicates = FALSE, int $skip = 0, bool $async_request = FALSE
+    ) : array|string {
         $params = http_build_query(array(
             "query" => $this->to_array($query),
             "language" => $language,
             "region" => $region,
             "organizationsPerQueryLimit" => $limit,
             "coordinates" => $coordinates,
-            "extractContacts" => $extract_contacts,
             "dropDuplicates" => $drop_duplicates,
+            "skipPlaces" => $skip,
+            "async" => $async_request,
         ));
-        $result = $this->make_get_request("maps/search?{$params}");
-        return $this->wait_request_archive($result["id"]);
+        $result = $this->make_get_request("maps/search-v2?{$params}");
+
+        if($async_request)
+            return $result;
+
+        return $result["data"];
     }
 
     /**
-     * Get data from Google Maps (speed optimized endpoint)
+     * Get data from Google Maps
      *
      * @param string|array $query Parameter defines the query or queries you want to search on Google Maps. Using an array allows multiple queries to be sent in one request and save on network latency time.
      * @param string $language Parameter specifies the language to use for Google. Available values: "en", "de", "es", "es-419", "fr", "hr", "it", "nl", "pl", "pt-BR", "pt-PT", "vi", "tr", "ru", "ar", "th", "ko", "zh-CN", "zh-TW", "ja", "ach", "af", "ak", "ig", "az", "ban", "ceb", "xx-bork", "bs", "br", "ca", "cs", "sn", "co", "cy", "da", "yo", "et", "xx-elmer", "eo", "eu", "ee", "tl", "fil", "fo", "fy", "gaa", "ga", "gd", "gl", "gn", "xx-hacker", "ht", "ha", "haw", "bem", "rn", "id", "ia", "xh", "zu", "is", "jw", "rw", "sw", "tlh", "kg", "mfe", "kri", "la", "lv", "to", "lt", "ln", "loz", "lua", "lg", "hu", "mg", "mt", "mi", "ms", "pcm", "no", "nso", "ny", "nn", "uz", "oc", "om", "xx-pirate", "ro", "rm", "qu", "nyn", "crs", "sq", "sk", "sl", "so", "st", "sr-ME", "sr-Latn", "su", "fi", "sv", "tn", "tum", "tk", "tw", "wo", "el", "be", "bg", "ky", "kk", "mk", "mn", "sr", "tt", "tg", "uk", "ka", "hy", "yi", "iw", "ug", "ur", "ps", "sd", "fa", "ckb", "ti", "am", "ne", "mr", "hi", "bn", "pa", "gu", "or", "ta", "te", "kn", "ml", "si", "lo", "my", "km", "chr".
@@ -166,30 +173,28 @@ public function google_maps_search_v1(
      * @param bool $extract_contacts Parameter specifies whether the bot will scrape additional data (emails, social links, site keywords…) from companies’ websites. It increases the time of the extraction.
      * @param string $coordinates Parameter defines the coordinates to use along with the query. Example: "@41.3954381,2.1628662,15.1z".
      * @param bool $drop_duplicates Parameter specifies whether the bot will drop the same organizations from different queries. Using the parameter combines results from each query inside one big array.
-     * @param int $skip Skip first N places, where N should be multiple to 20 (e.g. 0, 20, 40). It's commonly used in pagination.
      *
      * @return array request/task result
      */
-    public function google_maps_search(
+    public function google_maps_search_v1(
         string|array $query, string $language = "en", string $region = NULL, int $limit = 400,
-        string $coordinates = NULL, bool $drop_duplicates = FALSE, int $skip = 0
+        bool $extract_contacts = FALSE, string $coordinates = NULL, bool $drop_duplicates = FALSE
     ) : array {
         $params = http_build_query(array(
             "query" => $this->to_array($query),
             "language" => $language,
             "region" => $region,
             "organizationsPerQueryLimit" => $limit,
             "coordinates" => $coordinates,
+            "extractContacts" => $extract_contacts,
             "dropDuplicates" => $drop_duplicates,
-            "skipPlaces" => $skip,
-            "async" => FALSE,
         ));
-        $result = $this->make_get_request("maps/search-v2?{$params}");
-        return $result["data"];
+        $result = $this->make_get_request("maps/search?{$params}");
+        return $this->wait_request_archive($result["id"]);
     }
 
     /**
-     * Get reviews from Google Maps
+     * Get reviews from Google Maps (speed optimized)
      *
      * @param string|array $query Parameter defines the query or queries you want to search on Google Maps. Using an array allows multiple queries to be sent in one request and save on network latency time.
      * @param string $language Parameter specifies the language to use for Google. Available values: "en", "de", "es", "es-419", "fr", "hr", "it", "nl", "pl", "pt-BR", "pt-PT", "vi", "tr", "ru", "ar", "th", "ko", "zh-CN", "zh-TW", "ja", "ach", "af", "ak", "ig", "az", "ban", "ceb", "xx-bork", "bs", "br", "ca", "cs", "sn", "co", "cy", "da", "yo", "et", "xx-elmer", "eo", "eu", "ee", "tl", "fil", "fo", "fy", "gaa", "ga", "gd", "gl", "gn", "xx-hacker", "ht", "ha", "haw", "bem", "rn", "id", "ia", "xh", "zu", "is", "jw", "rw", "sw", "tlh", "kg", "mfe", "kri", "la", "lv", "to", "lt", "ln", "loz", "lua", "lg", "hu", "mg", "mt", "mi", "ms", "pcm", "no", "nso", "ny", "nn", "uz", "oc", "om", "xx-pirate", "ro", "rm", "qu", "nyn", "crs", "sq", "sk", "sl", "so", "st", "sr-ME", "sr-Latn", "su", "fi", "sv", "tn", "tum", "tk", "tw", "wo", "el", "be", "bg", "ky", "kk", "mk", "mn", "sr", "tt", "tg", "uk", "ka", "hy", "yi", "iw", "ug", "ur", "ps", "sd", "fa", "ckb", "ti", "am", "ne", "mr", "hi", "bn", "pa", "gu", "or", "ta", "te", "kn", "ml", "si", "lo", "my", "km", "chr".
@@ -201,14 +206,15 @@ public function google_maps_search(
      * @param int $cutoffRating Parameter specifies the maximum (for lowest_rating sorting) or minimum (for highest_rating sorting) rating for reviews. Using the cutoffRating requires sorting to be set to "lowest_rating" or "highest_rating".
      * @param string $sort Parameter specifies one of the sorting types. Available values: "most_relevant", "newest", "highest_rating", "lowest_rating".
      * @param string $reviews_query Parameter specifies the query to search among the reviews (e.g. wow, amazing, horrible place).
+     * @param bool $async_request Parameter defines the way you want to submit your task to Outscraper. It can be set to `False` (default) to send a task and wait until you got your results, or `True` to submit your task and retrieve the results later using a request ID with `get_request_archive`. Each response is available for `2` hours after a request has been completed.
      *
      * @return array request/task result
      */
-    public function google_maps_reviews_v2(
+    public function google_maps_reviews(
         string|array $query, string $language = "en", string $region = NULL, int $limit = 1,
         int $reviews_limit = 100, string $coordinates = NULL, int $cutoff = NULL, int $cutoff_rating = NULL,
-        string $sort = "most_relevant", string $reviews_query = NULL
-    ) : array {
+        string $sort = "most_relevant", string $reviews_query = NULL, bool $async_request = FALSE
+    ) : array|string {
         $params = http_build_query(array(
             "query" => $this->to_array($query),
             "language" => $language,
@@ -219,14 +225,19 @@ public function google_maps_reviews_v2(
             "cutoff" => $cutoff,
             "cutoffRating" => $cutoff_rating,
             "reviewsQuery" => $reviews_query,
-            "sort" => $sort
+            "sort" => $sort,
+            "async" => $async_request,
         ));
-        $result = $this->make_get_request("maps/reviews-v2?{$params}");
-        return $this->wait_request_archive($result["id"]);
+        $result = $this->make_get_request("maps/reviews-v3?{$params}");
+
+        if($async_request)
+            return $result;
+
+        return $result["data"];
     }
 
     /**
-     * Get reviews from Google Maps (speed optimized)
+     * Get reviews from Google Maps
      *
      * @param string|array $query Parameter defines the query or queries you want to search on Google Maps. Using an array allows multiple queries to be sent in one request and save on network latency time.
      * @param string $language Parameter specifies the language to use for Google. Available values: "en", "de", "es", "es-419", "fr", "hr", "it", "nl", "pl", "pt-BR", "pt-PT", "vi", "tr", "ru", "ar", "th", "ko", "zh-CN", "zh-TW", "ja", "ach", "af", "ak", "ig", "az", "ban", "ceb", "xx-bork", "bs", "br", "ca", "cs", "sn", "co", "cy", "da", "yo", "et", "xx-elmer", "eo", "eu", "ee", "tl", "fil", "fo", "fy", "gaa", "ga", "gd", "gl", "gn", "xx-hacker", "ht", "ha", "haw", "bem", "rn", "id", "ia", "xh", "zu", "is", "jw", "rw", "sw", "tlh", "kg", "mfe", "kri", "la", "lv", "to", "lt", "ln", "loz", "lua", "lg", "hu", "mg", "mt", "mi", "ms", "pcm", "no", "nso", "ny", "nn", "uz", "oc", "om", "xx-pirate", "ro", "rm", "qu", "nyn", "crs", "sq", "sk", "sl", "so", "st", "sr-ME", "sr-Latn", "su", "fi", "sv", "tn", "tum", "tk", "tw", "wo", "el", "be", "bg", "ky", "kk", "mk", "mn", "sr", "tt", "tg", "uk", "ka", "hy", "yi", "iw", "ug", "ur", "ps", "sd", "fa", "ckb", "ti", "am", "ne", "mr", "hi", "bn", "pa", "gu", "or", "ta", "te", "kn", "ml", "si", "lo", "my", "km", "chr".
@@ -241,7 +252,7 @@ public function google_maps_reviews_v2(
      *
      * @return array request/task result
      */
-    public function google_maps_reviews(
+    public function google_maps_reviews_v2(
         string|array $query, string $language = "en", string $region = NULL, int $limit = 1,
         int $reviews_limit = 100, string $coordinates = NULL, int $cutoff = NULL, int $cutoff_rating = NULL,
         string $sort = "most_relevant", string $reviews_query = NULL
@@ -256,11 +267,10 @@ public function google_maps_reviews(
             "cutoff" => $cutoff,
             "cutoffRating" => $cutoff_rating,
             "reviewsQuery" => $reviews_query,
-            "sort" => $sort,
-            "async" => FALSE,
+            "sort" => $sort
         ));
-        $result = $this->make_get_request("maps/reviews-v3?{$params}");
-        return $result["data"];
+        $result = $this->make_get_request("maps/reviews-v2?{$params}");
+        return $this->wait_request_archive($result["id"]);
     }
 
     /**