feat(scrape): add google-maps-reviews prebuilt parser with oldest-first sort (#1928)

Stainless-Generated-From: 53896a2d8f88944c2dbfd2ae3f71fa5ce5377564

Author: stlc-bot

src/context/dev/types/batch_get_results_response.py

@@ -294,7 +294,7 @@ class DataOkResultMetadata(BaseModel):
 
 class DataOkResultParsed(BaseModel):
     """
-    Custom rules return fields after content filters; unmatched fields are null ([] for lists). The google-maps parser returns business records in data.results, and the google-play parser returns one app record as data, google-play-reviews returns data.reviews, app-store and app-store-reviews do the same for the App Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store and Maps parsers read their data directly, independently of DOM filters and other outputs.
+    Custom rules return fields after content filters; unmatched fields are null ([] for lists). The google-maps parser returns business records in data.results, google-maps-reviews returns data.reviews, and the google-play parser returns one app record as data, google-play-reviews returns data.reviews, app-store and app-store-reviews do the same for the App Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store and Maps parsers read their data directly, independently of DOM filters and other outputs.
     """
 
     data: Optional[Dict[str, object]] = None
@@ -307,6 +307,7 @@ class DataOkResultParsed(BaseModel):
     type: Literal[
         "custom",
         "google-maps",
+        "google-maps-reviews",
         "google-play",
         "google-play-reviews",
         "app-store",
@@ -502,12 +503,13 @@ class DataOkResult(BaseModel):
     parsed: DataOkResultParsed
     """
     Custom rules return fields after content filters; unmatched fields are null ([]
-    for lists). The google-maps parser returns business records in data.results, and
-    the google-play parser returns one app record as data, google-play-reviews
-    returns data.reviews, app-store and app-store-reviews do the same for the App
-    Store, emails, phone-numbers, and links return data.emails, data.phone_numbers,
-    and data.links from the rendered page; the store and Maps parsers read their
-    data directly, independently of DOM filters and other outputs.
+    for lists). The google-maps parser returns business records in data.results,
+    google-maps-reviews returns data.reviews, and the google-play parser returns one
+    app record as data, google-play-reviews returns data.reviews, app-store and
+    app-store-reviews do the same for the App Store, emails, phone-numbers, and
+    links return data.emails, data.phone_numbers, and data.links from the rendered
+    page; the store and Maps parsers read their data directly, independently of DOM
+    filters and other outputs.
     """
 
     product: DataOkResultProduct
@@ -809,7 +811,7 @@ class DataErrorResultMetadata(BaseModel):
 
 class DataErrorResultParsed(BaseModel):
     """
-    Custom rules return fields after content filters; unmatched fields are null ([] for lists). The google-maps parser returns business records in data.results, and the google-play parser returns one app record as data, google-play-reviews returns data.reviews, app-store and app-store-reviews do the same for the App Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store and Maps parsers read their data directly, independently of DOM filters and other outputs.
+    Custom rules return fields after content filters; unmatched fields are null ([] for lists). The google-maps parser returns business records in data.results, google-maps-reviews returns data.reviews, and the google-play parser returns one app record as data, google-play-reviews returns data.reviews, app-store and app-store-reviews do the same for the App Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store and Maps parsers read their data directly, independently of DOM filters and other outputs.
     """
 
     data: Optional[Dict[str, object]] = None
@@ -822,6 +824,7 @@ class DataErrorResultParsed(BaseModel):
     type: Literal[
         "custom",
         "google-maps",
+        "google-maps-reviews",
         "google-play",
         "google-play-reviews",
         "app-store",
@@ -1018,12 +1021,13 @@ class DataErrorResult(BaseModel):
     parsed: DataErrorResultParsed
     """
     Custom rules return fields after content filters; unmatched fields are null ([]
-    for lists). The google-maps parser returns business records in data.results, and
-    the google-play parser returns one app record as data, google-play-reviews
-    returns data.reviews, app-store and app-store-reviews do the same for the App
-    Store, emails, phone-numbers, and links return data.emails, data.phone_numbers,
-    and data.links from the rendered page; the store and Maps parsers read their
-    data directly, independently of DOM filters and other outputs.
+    for lists). The google-maps parser returns business records in data.results,
+    google-maps-reviews returns data.reviews, and the google-play parser returns one
+    app record as data, google-play-reviews returns data.reviews, app-store and
+    app-store-reviews do the same for the App Store, emails, phone-numbers, and
+    links return data.emails, data.phone_numbers, and data.links from the rendered
+    page; the store and Maps parsers read their data directly, independently of DOM
+    filters and other outputs.
     """
 
     product: DataErrorResultProduct

src/context/dev/types/batch_submit_params.py

@@ -242,6 +242,7 @@ class InputScrapeDataParseParamsPrebuiltParser(TypedDict, total=False):
     parser: Required[
         Literal[
             "google-maps",
+            "google-maps-reviews",
             "google-play",
             "google-play-reviews",
             "app-store",
@@ -254,7 +255,15 @@ class InputScrapeDataParseParamsPrebuiltParser(TypedDict, total=False):
     """google-maps parses Google Maps business data into data.results.
 
     Accepts Maps place, search, and internal data URLs. Uses a US exit and English
-    labels regardless of hl or Accept-Language. google-play parses a Play Store app
+    labels regardless of hl or Accept-Language. google-maps-reviews returns the
+    reviews of a place in data.reviews, in the same shape as the Serper reviews API
+    (rating, date, isoDate, snippet, translatedSnippet, likes, user, media,
+    response, link, id), plus language, guided ratings in details, and
+    user.isLocalGuide; data also carries the place featureId, cid, and sort. sort
+    and limit pick the order and count, and oldest is exact. It accepts Maps place,
+    search, and ?cid= URLs, plus search.google.com/local/reviews URLs, so the
+    google_maps_url and google_reviews_url fields of google-maps results work as
+    input. An unknown place returns no reviews. google-play parses a Play Store app
     into data: details, developer contact, ratings, price, permissions, and data
     safety. google-play-reviews returns the 200 newest reviews of the app, with
     developer replies, in data.reviews. Both Play parsers accept app details URLs
@@ -279,6 +288,19 @@ class InputScrapeDataParseParamsPrebuiltParser(TypedDict, total=False):
     type: Required[Literal["prebuilt"]]
     """Use a prebuilt parser instead of custom rules."""
 
+    limit: int
+    """google-maps-reviews only.
+
+    Maximum number of reviews to return. Defaults to 100; maximum 1000.
+    """
+
+    sort: Literal["newest", "oldest", "relevant", "highest", "lowest"]
+    """google-maps-reviews only.
+
+    Order of data.reviews. newest, relevant, highest, and lowest follow Google;
+    oldest returns the earliest reviews first, which Google itself does not offer.
+    """
+
 
 InputScrapeDataParseParams: TypeAlias = Union[
     InputScrapeDataParseParamsCustomParser, InputScrapeDataParseParamsPrebuiltParser
@@ -785,6 +807,7 @@ class InputCrawlDataParseParamsPrebuiltParser(TypedDict, total=False):
     parser: Required[
         Literal[
             "google-maps",
+            "google-maps-reviews",
             "google-play",
             "google-play-reviews",
             "app-store",
@@ -797,7 +820,15 @@ class InputCrawlDataParseParamsPrebuiltParser(TypedDict, total=False):
     """google-maps parses Google Maps business data into data.results.
 
     Accepts Maps place, search, and internal data URLs. Uses a US exit and English
-    labels regardless of hl or Accept-Language. google-play parses a Play Store app
+    labels regardless of hl or Accept-Language. google-maps-reviews returns the
+    reviews of a place in data.reviews, in the same shape as the Serper reviews API
+    (rating, date, isoDate, snippet, translatedSnippet, likes, user, media,
+    response, link, id), plus language, guided ratings in details, and
+    user.isLocalGuide; data also carries the place featureId, cid, and sort. sort
+    and limit pick the order and count, and oldest is exact. It accepts Maps place,
+    search, and ?cid= URLs, plus search.google.com/local/reviews URLs, so the
+    google_maps_url and google_reviews_url fields of google-maps results work as
+    input. An unknown place returns no reviews. google-play parses a Play Store app
     into data: details, developer contact, ratings, price, permissions, and data
     safety. google-play-reviews returns the 200 newest reviews of the app, with
     developer replies, in data.reviews. Both Play parsers accept app details URLs
@@ -822,6 +853,19 @@ class InputCrawlDataParseParamsPrebuiltParser(TypedDict, total=False):
     type: Required[Literal["prebuilt"]]
     """Use a prebuilt parser instead of custom rules."""
 
+    limit: int
+    """google-maps-reviews only.
+
+    Maximum number of reviews to return. Defaults to 100; maximum 1000.
+    """
+
+    sort: Literal["newest", "oldest", "relevant", "highest", "lowest"]
+    """google-maps-reviews only.
+
+    Order of data.reviews. newest, relevant, highest, and lowest follow Google;
+    oldest returns the earliest reviews first, which Google itself does not offer.
+    """
+
 
 InputCrawlDataParseParams: TypeAlias = Union[
     InputCrawlDataParseParamsCustomParser, InputCrawlDataParseParamsPrebuiltParser

src/context/dev/types/web_scrape_params.py

@@ -210,6 +210,7 @@ class ParseParamsPrebuiltParser(TypedDict, total=False):
     parser: Required[
         Literal[
             "google-maps",
+            "google-maps-reviews",
             "google-play",
             "google-play-reviews",
             "app-store",
@@ -222,7 +223,15 @@ class ParseParamsPrebuiltParser(TypedDict, total=False):
     """google-maps parses Google Maps business data into data.results.
 
     Accepts Maps place, search, and internal data URLs. Uses a US exit and English
-    labels regardless of hl or Accept-Language. google-play parses a Play Store app
+    labels regardless of hl or Accept-Language. google-maps-reviews returns the
+    reviews of a place in data.reviews, in the same shape as the Serper reviews API
+    (rating, date, isoDate, snippet, translatedSnippet, likes, user, media,
+    response, link, id), plus language, guided ratings in details, and
+    user.isLocalGuide; data also carries the place featureId, cid, and sort. sort
+    and limit pick the order and count, and oldest is exact. It accepts Maps place,
+    search, and ?cid= URLs, plus search.google.com/local/reviews URLs, so the
+    google_maps_url and google_reviews_url fields of google-maps results work as
+    input. An unknown place returns no reviews. google-play parses a Play Store app
     into data: details, developer contact, ratings, price, permissions, and data
     safety. google-play-reviews returns the 200 newest reviews of the app, with
     developer replies, in data.reviews. Both Play parsers accept app details URLs
@@ -247,6 +256,19 @@ class ParseParamsPrebuiltParser(TypedDict, total=False):
     type: Required[Literal["prebuilt"]]
     """Use a prebuilt parser instead of custom rules."""
 
+    limit: int
+    """google-maps-reviews only.
+
+    Maximum number of reviews to return. Defaults to 100; maximum 1000.
+    """
+
+    sort: Literal["newest", "oldest", "relevant", "highest", "lowest"]
+    """google-maps-reviews only.
+
+    Order of data.reviews. newest, relevant, highest, and lowest follow Google;
+    oldest returns the earliest reviews first, which Google itself does not offer.
+    """
+
 
 ParseParams: TypeAlias = Union[ParseParamsCustomParser, ParseParamsPrebuiltParser]
 

src/context/dev/types/web_scrape_response.py

@@ -267,7 +267,7 @@ class Metadata(BaseModel):
 
 class Parsed(BaseModel):
     """
-    Custom rules return fields after content filters; unmatched fields are null ([] for lists). The google-maps parser returns business records in data.results, and the google-play parser returns one app record as data, google-play-reviews returns data.reviews, app-store and app-store-reviews do the same for the App Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store and Maps parsers read their data directly, independently of DOM filters and other outputs.
+    Custom rules return fields after content filters; unmatched fields are null ([] for lists). The google-maps parser returns business records in data.results, google-maps-reviews returns data.reviews, and the google-play parser returns one app record as data, google-play-reviews returns data.reviews, app-store and app-store-reviews do the same for the App Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store and Maps parsers read their data directly, independently of DOM filters and other outputs.
     """
 
     data: Optional[Dict[str, object]] = None
@@ -280,6 +280,7 @@ class Parsed(BaseModel):
     type: Literal[
         "custom",
         "google-maps",
+        "google-maps-reviews",
         "google-play",
         "google-play-reviews",
         "app-store",
@@ -471,12 +472,13 @@ class WebScrapeResponse(BaseModel):
     parsed: Parsed
     """
     Custom rules return fields after content filters; unmatched fields are null ([]
-    for lists). The google-maps parser returns business records in data.results, and
-    the google-play parser returns one app record as data, google-play-reviews
-    returns data.reviews, app-store and app-store-reviews do the same for the App
-    Store, emails, phone-numbers, and links return data.emails, data.phone_numbers,
-    and data.links from the rendered page; the store and Maps parsers read their
-    data directly, independently of DOM filters and other outputs.
+    for lists). The google-maps parser returns business records in data.results,
+    google-maps-reviews returns data.reviews, and the google-play parser returns one
+    app record as data, google-play-reviews returns data.reviews, app-store and
+    app-store-reviews do the same for the App Store, emails, phone-numbers, and
+    links return data.emails, data.phone_numbers, and data.links from the rendered
+    page; the store and Maps parsers read their data directly, independently of DOM
+    filters and other outputs.
     """
 
     product: Product