feat(scrape): add Tripadvisor reviews parser (#2508)

Stainless-Generated-From: 5c1b6ad18f316dfd31c3375de6a803109db790d2

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, 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, g2-reviews returns data.reviews for a G2 product, instagram-profile and instagram-post return one record as data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return one record as data, tiktok-feed returns data.videos, tiktok-comments returns data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return data.users, yelp-search returns up to 20 ranked organic businesses in data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews returns up to 20 latest public reviews in data.reviews, with business details and next_offset, from a Yelp business URL; emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, Instagram, and TikTok 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, g2-reviews returns data.reviews for a G2 product, instagram-profile and instagram-post return one record as data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return one record as data, tiktok-feed returns data.videos, tiktok-comments returns data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return data.users, yelp-search returns up to 20 ranked organic businesses in data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews returns up to 20 latest public reviews in data.reviews, with business details and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 reviews in data.reviews, with data.location and next_offset, from a Tripadvisor hotel, restaurant, or attraction review URL; emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read their data directly, independently of DOM filters and other outputs.
     """
 
     data: Optional[Dict[str, object]] = None
@@ -329,6 +329,7 @@ class DataOkResultParsed(BaseModel):
         "reddit-user",
         "yelp-search",
         "yelp-reviews",
+        "tripadvisor-reviews",
         "emails",
         "phone-numbers",
         "links",
@@ -531,7 +532,9 @@ class DataOkResult(BaseModel):
     data.users, yelp-search returns up to 20 ranked organic businesses in
     data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews
     returns up to 20 latest public reviews in data.reviews, with business details
-    and next_offset, from a Yelp business URL; emails, phone-numbers, and links
+    and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20
+    reviews in data.reviews, with data.location and next_offset, from a Tripadvisor
+    hotel, restaurant, or attraction review URL; emails, phone-numbers, and links
     return data.emails, data.phone_numbers, and data.links from the rendered page;
     the store, Maps, G2, Instagram, and TikTok parsers read their data directly,
     independently of DOM filters and other outputs.
@@ -836,7 +839,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, 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, g2-reviews returns data.reviews for a G2 product, instagram-profile and instagram-post return one record as data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return one record as data, tiktok-feed returns data.videos, tiktok-comments returns data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return data.users, yelp-search returns up to 20 ranked organic businesses in data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews returns up to 20 latest public reviews in data.reviews, with business details and next_offset, from a Yelp business URL; emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, Instagram, and TikTok 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, g2-reviews returns data.reviews for a G2 product, instagram-profile and instagram-post return one record as data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return one record as data, tiktok-feed returns data.videos, tiktok-comments returns data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return data.users, yelp-search returns up to 20 ranked organic businesses in data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews returns up to 20 latest public reviews in data.reviews, with business details and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 reviews in data.reviews, with data.location and next_offset, from a Tripadvisor hotel, restaurant, or attraction review URL; emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read their data directly, independently of DOM filters and other outputs.
     """
 
     data: Optional[Dict[str, object]] = None
@@ -871,6 +874,7 @@ class DataErrorResultParsed(BaseModel):
         "reddit-user",
         "yelp-search",
         "yelp-reviews",
+        "tripadvisor-reviews",
         "emails",
         "phone-numbers",
         "links",
@@ -1074,7 +1078,9 @@ class DataErrorResult(BaseModel):
     data.users, yelp-search returns up to 20 ranked organic businesses in
     data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews
     returns up to 20 latest public reviews in data.reviews, with business details
-    and next_offset, from a Yelp business URL; emails, phone-numbers, and links
+    and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20
+    reviews in data.reviews, with data.location and next_offset, from a Tripadvisor
+    hotel, restaurant, or attraction review URL; emails, phone-numbers, and links
     return data.emails, data.phone_numbers, and data.links from the rendered page;
     the store, Maps, G2, Instagram, and TikTok parsers read their data directly,
     independently of DOM filters and other outputs.

src/context/dev/types/batch_submit_params.py

@@ -903,6 +903,7 @@ class InputScrapeDataBatchUnifiedScrapeDataParseParamsPrebuiltParser(TypedDict,
             "reddit-user",
             "yelp-search",
             "yelp-reviews",
+            "tripadvisor-reviews",
             "emails",
             "phone-numbers",
             "links",
@@ -1026,16 +1027,25 @@ class InputScrapeDataBatchUnifiedScrapeDataParseParamsPrebuiltParser(TypedDict,
     pagination.next_offset. Each review has rating, full text, updated_at, and
     author (id is the Yelp user id from the reviewer profile URL, url links to that
     profile, plus name, location, and review_count); owner replies and photos are
-    not included. emails accepts any page and returns its email addresses as
-    data.emails ([{ email }]), read from mailto links, Cloudflare-protected
-    addresses, and visible text. phone-numbers accepts any page and returns its
-    valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel
-    links and visible text; numbers without a country code are read for the country
-    of the site TLD, defaulting to US. links accepts any page and returns its unique
-    http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls
-    back to aria-label or image alt and is null when a link has none. The emails
-    parser reads the rendered page and respects content filters; the other prebuilt
-    parsers read their data independently of DOM filters.
+    not included. tripadvisor-reviews accepts a Tripadvisor hotel, restaurant, or
+    attraction review URL (tripadvisor.com/Hotel_Review-g{geo}-d{id}-Reviews-….html,
+    on any Tripadvisor country domain), reads -or{N}- in the path as the offset, and
+    returns 20 reviews in data.reviews in the order Tripadvisor shows them, with
+    data.location (id, name, type, url, review_count) and pagination.next_offset.
+    Each review has id, url, title, full text, rating, language, published_at,
+    visit_month, helpful_votes, subratings, photo_urls, owner_response (text,
+    published_at, author_name), and author (id, username, name, url,
+    contribution_count); an unknown location returns no reviews. emails accepts any
+    page and returns its email addresses as data.emails ([{ email }]), read from
+    mailto links, Cloudflare-protected addresses, and visible text. phone-numbers
+    accepts any page and returns its valid phone numbers in E.164 as
+    data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers
+    without a country code are read for the country of the site TLD, defaulting to
+    US. links accepts any page and returns its unique http(s) links as data.links
+    ([{ url, text }]), with absolute URLs; text falls back to aria-label or image
+    alt and is null when a link has none. The emails parser reads the rendered page
+    and respects content filters; the other prebuilt parsers read their data
+    independently of DOM filters.
     """
 
     type: Required[Literal["prebuilt"]]
@@ -2612,6 +2622,7 @@ class InputCrawlDataBatchUnifiedCrawlDataParseParamsPrebuiltParser(TypedDict, to
             "reddit-user",
             "yelp-search",
             "yelp-reviews",
+            "tripadvisor-reviews",
             "emails",
             "phone-numbers",
             "links",
@@ -2735,16 +2746,25 @@ class InputCrawlDataBatchUnifiedCrawlDataParseParamsPrebuiltParser(TypedDict, to
     pagination.next_offset. Each review has rating, full text, updated_at, and
     author (id is the Yelp user id from the reviewer profile URL, url links to that
     profile, plus name, location, and review_count); owner replies and photos are
-    not included. emails accepts any page and returns its email addresses as
-    data.emails ([{ email }]), read from mailto links, Cloudflare-protected
-    addresses, and visible text. phone-numbers accepts any page and returns its
-    valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel
-    links and visible text; numbers without a country code are read for the country
-    of the site TLD, defaulting to US. links accepts any page and returns its unique
-    http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls
-    back to aria-label or image alt and is null when a link has none. The emails
-    parser reads the rendered page and respects content filters; the other prebuilt
-    parsers read their data independently of DOM filters.
+    not included. tripadvisor-reviews accepts a Tripadvisor hotel, restaurant, or
+    attraction review URL (tripadvisor.com/Hotel_Review-g{geo}-d{id}-Reviews-….html,
+    on any Tripadvisor country domain), reads -or{N}- in the path as the offset, and
+    returns 20 reviews in data.reviews in the order Tripadvisor shows them, with
+    data.location (id, name, type, url, review_count) and pagination.next_offset.
+    Each review has id, url, title, full text, rating, language, published_at,
+    visit_month, helpful_votes, subratings, photo_urls, owner_response (text,
+    published_at, author_name), and author (id, username, name, url,
+    contribution_count); an unknown location returns no reviews. emails accepts any
+    page and returns its email addresses as data.emails ([{ email }]), read from
+    mailto links, Cloudflare-protected addresses, and visible text. phone-numbers
+    accepts any page and returns its valid phone numbers in E.164 as
+    data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers
+    without a country code are read for the country of the site TLD, defaulting to
+    US. links accepts any page and returns its unique http(s) links as data.links
+    ([{ url, text }]), with absolute URLs; text falls back to aria-label or image
+    alt and is null when a link has none. The emails parser reads the rendered page
+    and respects content filters; the other prebuilt parsers read their data
+    independently of DOM filters.
     """
 
     type: Required[Literal["prebuilt"]]

src/context/dev/types/web_scrape_params.py

@@ -240,6 +240,7 @@ class ParseParamsPrebuiltParser(TypedDict, total=False):
             "reddit-user",
             "yelp-search",
             "yelp-reviews",
+            "tripadvisor-reviews",
             "emails",
             "phone-numbers",
             "links",
@@ -363,16 +364,25 @@ class ParseParamsPrebuiltParser(TypedDict, total=False):
     pagination.next_offset. Each review has rating, full text, updated_at, and
     author (id is the Yelp user id from the reviewer profile URL, url links to that
     profile, plus name, location, and review_count); owner replies and photos are
-    not included. emails accepts any page and returns its email addresses as
-    data.emails ([{ email }]), read from mailto links, Cloudflare-protected
-    addresses, and visible text. phone-numbers accepts any page and returns its
-    valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel
-    links and visible text; numbers without a country code are read for the country
-    of the site TLD, defaulting to US. links accepts any page and returns its unique
-    http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls
-    back to aria-label or image alt and is null when a link has none. The emails
-    parser reads the rendered page and respects content filters; the other prebuilt
-    parsers read their data independently of DOM filters.
+    not included. tripadvisor-reviews accepts a Tripadvisor hotel, restaurant, or
+    attraction review URL (tripadvisor.com/Hotel_Review-g{geo}-d{id}-Reviews-….html,
+    on any Tripadvisor country domain), reads -or{N}- in the path as the offset, and
+    returns 20 reviews in data.reviews in the order Tripadvisor shows them, with
+    data.location (id, name, type, url, review_count) and pagination.next_offset.
+    Each review has id, url, title, full text, rating, language, published_at,
+    visit_month, helpful_votes, subratings, photo_urls, owner_response (text,
+    published_at, author_name), and author (id, username, name, url,
+    contribution_count); an unknown location returns no reviews. emails accepts any
+    page and returns its email addresses as data.emails ([{ email }]), read from
+    mailto links, Cloudflare-protected addresses, and visible text. phone-numbers
+    accepts any page and returns its valid phone numbers in E.164 as
+    data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers
+    without a country code are read for the country of the site TLD, defaulting to
+    US. links accepts any page and returns its unique http(s) links as data.links
+    ([{ url, text }]), with absolute URLs; text falls back to aria-label or image
+    alt and is null when a link has none. The emails parser reads the rendered page
+    and respects content filters; the other prebuilt parsers read their data
+    independently of DOM filters.
     """
 
     type: Required[Literal["prebuilt"]]

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, 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, g2-reviews returns data.reviews for a G2 product, instagram-profile and instagram-post return one record as data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return one record as data, tiktok-feed returns data.videos, tiktok-comments returns data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return data.users, yelp-search returns up to 20 ranked organic businesses in data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews returns up to 20 latest public reviews in data.reviews, with business details and next_offset, from a Yelp business URL; emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, Instagram, and TikTok 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, g2-reviews returns data.reviews for a G2 product, instagram-profile and instagram-post return one record as data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return one record as data, tiktok-feed returns data.videos, tiktok-comments returns data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return data.users, yelp-search returns up to 20 ranked organic businesses in data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews returns up to 20 latest public reviews in data.reviews, with business details and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 reviews in data.reviews, with data.location and next_offset, from a Tripadvisor hotel, restaurant, or attraction review URL; emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read their data directly, independently of DOM filters and other outputs.
     """
 
     data: Optional[Dict[str, object]] = None
@@ -302,6 +302,7 @@ class Parsed(BaseModel):
         "reddit-user",
         "yelp-search",
         "yelp-reviews",
+        "tripadvisor-reviews",
         "emails",
         "phone-numbers",
         "links",
@@ -500,7 +501,9 @@ class WebScrapeResponse(BaseModel):
     data.users, yelp-search returns up to 20 ranked organic businesses in
     data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews
     returns up to 20 latest public reviews in data.reviews, with business details
-    and next_offset, from a Yelp business URL; emails, phone-numbers, and links
+    and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20
+    reviews in data.reviews, with data.location and next_offset, from a Tripadvisor
+    hotel, restaurant, or attraction review URL; emails, phone-numbers, and links
     return data.emails, data.phone_numbers, and data.links from the rendered page;
     the store, Maps, G2, Instagram, and TikTok parsers read their data directly,
     independently of DOM filters and other outputs.