feat(scrape): add prebuilt Google Maps parsing (#1824)

Stainless-Generated-From: 8e806a9f36d3df52f3aa22964dbb78619cf2e265

Author: stlc-bot

src/context/dev/types/web_scrape_params.py

@@ -16,8 +16,10 @@
     "JsonParams",
     "MarkdownParams",
     "ParseParams",
-    "ParseParamsRules",
-    "ParseParamsRulesUnionMember1",
+    "ParseParamsCustomParser",
+    "ParseParamsCustomParserRules",
+    "ParseParamsCustomParserRulesUnionMember1",
+    "ParseParamsPrebuiltParser",
     "ProductParams",
     "ScreenshotParams",
     "ScreenshotParamsArea",
@@ -115,7 +117,7 @@ class Formats(TypedDict, total=False):
     """Page content as Markdown."""
 
     parse: bool
-    """Fields extracted with `parseParams.rules`, returned as `parsed`."""
+    """Fields extracted with custom rules or a prebuilt parser, returned as `parsed`."""
 
     product: bool
     """Product details such as name, price, and availability."""
@@ -173,7 +175,7 @@ class MarkdownParams(TypedDict, total=False):
     """
 
 
-class ParseParamsRulesUnionMember1(TypedDict, total=False):
+class ParseParamsCustomParserRulesUnionMember1(TypedDict, total=False):
     selector: Required[str]
     """CSS selector to match within the current page or parent rule."""
 
@@ -187,18 +189,38 @@ class ParseParamsRulesUnionMember1(TypedDict, total=False):
     """Return the first match with `item` or all matches with `list`."""
 
 
-ParseParamsRules: TypeAlias = Union[str, ParseParamsRulesUnionMember1]
+ParseParamsCustomParserRules: TypeAlias = Union[str, ParseParamsCustomParserRulesUnionMember1]
 
 
-class ParseParams(TypedDict, total=False):
-    """Requires `formats.parse: true`; required when it is set."""
-
-    rules: Required[Dict[str, ParseParamsRules]]
+class ParseParamsCustomParser(TypedDict, total=False):
+    rules: Required[Dict[str, ParseParamsCustomParserRules]]
     """Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects.
 
     Max 100 fields, 5 levels.
     """
 
+    type: Literal["custom"]
+    """Extract fields using custom CSS rules.
+
+    This is the default when type is omitted.
+    """
+
+
+class ParseParamsPrebuiltParser(TypedDict, total=False):
+    parser: Required[Literal["google-maps"]]
+    """Parse 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, and reads Maps data independently of
+    DOM filters.
+    """
+
+    type: Required[Literal["prebuilt"]]
+    """Use a prebuilt parser instead of custom rules."""
+
+
+ParseParams: TypeAlias = Union[ParseParamsCustomParser, ParseParamsPrebuiltParser]
+
 
 class ProductParams(TypedDict, total=False):
     """Product options. Requires formats.product: true."""
@@ -390,7 +412,8 @@ class SharedParams(TypedDict, total=False):
     """Create or reuse an authenticated browser profile.
 
     Requires a paid plan and an HTTPS target. Profiles persist session state, bypass
-    shared caches, and cannot be combined with ZDR, custom headers, or raw bytes.
+    shared caches, and cannot be combined with ZDR, custom headers, raw bytes, or
+    prebuilt parsers.
     """
 
     settle_animations: Annotated[bool, PropertyInfo(alias="settleAnimations")]

src/context/dev/types/web_scrape_response.py

@@ -266,9 +266,8 @@ class Metadata(BaseModel):
 
 
 class Parsed(BaseModel):
-    """Fields from `parseParams.rules`, after content filters.
-
-    Unmatched fields are `null` (`[]` for lists).
+    """
+    Custom rules return fields after content filters; unmatched fields are null ([] for lists). The google-maps parser returns business records in data.results and reads Maps data directly, independently of DOM filters and other outputs.
     """
 
     data: Optional[Dict[str, object]] = None
@@ -278,6 +277,12 @@ class Parsed(BaseModel):
     success: Optional[bool] = None
     """`true` if returned, `false` if it failed, `null` if not requested."""
 
+    type: Literal["custom", "google-maps"]
+    """
+    The selected prebuilt parser name, or custom when type is omitted, custom rules
+    are used, or parsing is not requested.
+    """
+
     error_code: Optional[str] = None
     """Why the output failed. Present only when `success` is `false`."""
 
@@ -454,9 +459,10 @@ class WebScrapeResponse(BaseModel):
     """Page metadata. Fields are omitted when not found."""
 
     parsed: Parsed
-    """Fields from `parseParams.rules`, after content filters.
-
-    Unmatched fields are `null` (`[]` for lists).
+    """
+    Custom rules return fields after content filters; unmatched fields are null ([]
+    for lists). The google-maps parser returns business records in data.results and
+    reads Maps data directly, independently of DOM filters and other outputs.
     """
 
     product: Product

tests/api_resources/test_web.py

@@ -283,7 +283,8 @@ def test_method_scrape_with_all_params(self, client: ContextDev) -> None:
                         "output": "@href",
                         "type": "list",
                     },
-                }
+                },
+                "type": "custom",
             },
             product_params={"dedupe_images": True},
             screenshot_params={
@@ -829,7 +830,8 @@ async def test_method_scrape_with_all_params(self, async_client: AsyncContextDev
                         "output": "@href",
                         "type": "list",
                     },
-                }
+                },
+                "type": "custom",
             },
             product_params={"dedupe_images": True},
             screenshot_params={