getanyapi 0.35.3__tar.gz → 0.37.0__tar.gz

{getanyapi-0.35.3 → getanyapi-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: getanyapi
-Version: 0.35.3
+Version: 0.37.0
 Summary: Official typed Python SDK for AnyAPI: any API, one wallet, USD, no subscriptions.
 Project-URL: Homepage, https://getanyapi.com
 Project-URL: Documentation, https://getanyapi.com/docs

{getanyapi-0.35.3 → getanyapi-0.37.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getanyapi"
-version = "0.35.3"
+version = "0.37.0"
 description = "Official typed Python SDK for AnyAPI: any API, one wallet, USD, no subscriptions."
 readme = "README.md"
 requires-python = ">=3.10"

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/__init__.py

@@ -54,7 +54,7 @@ from .types import (
     unwrap,
 )
 
-__version__ = "0.35.3"
+__version__ = "0.37.0"
 
 __all__ = [
     # clients + top-level functions

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/_account.py

@@ -49,13 +49,26 @@ def catalog_request(category: str | None) -> tuple[str, dict[str, str]]:
 
 
 def search_request(
-    query: str,
+    query: str | None,
     category: str | None,
     platform: str | None,
     limit: int | None,
 ) -> tuple[str, dict[str, str]]:
-    """Path and query params for dedicated ranked discovery search."""
-    params = {"q": query}
+    """Path and query params for dedicated ranked discovery search.
+
+    The gateway needs at least one of query, category or platform, in any
+    combination, so a scope with no query at all is a valid search. An absent or
+    empty query omits ``q`` entirely, because an empty ``q`` is a different
+    request.
+    """
+    if not query and category is None and platform is None:
+        raise AnyAPIError(
+            "search needs at least one of query, category, or platform",
+            status=0,
+        )
+    params: dict[str, str] = {}
+    if query:
+        params["q"] = query
     if category is not None:
         params["category"] = category
     if platform is not None:

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/_async_client.py

@@ -370,7 +370,7 @@ class AsyncAnyAPI:
     async def search(
         self,
         *,
-        query: str,
+        query: str | None = None,
         category: str | None = None,
         platform: str | None = None,
         limit: int | None = None,

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/_client.py

@@ -398,7 +398,7 @@ class AnyAPI:
     def search(
         self,
         *,
-        query: str,
+        query: str | None = None,
         category: str | None = None,
         platform: str | None = None,
         limit: int | None = None,

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/company_enrichment.py

@@ -275,7 +275,7 @@ class CompanyEnrichmentCrustdataV3Data(BaseModel):
     naics: CompanyEnrichmentCrustdataV3Naic | None = Field(
         default=None, description="Primary NAICS industry classification."
     )
-    name: str = Field(description="Company name.")
+    name: str | None = Field(default=None, description="Company name.")
     region_metrics: CompanyEnrichmentCrustdataV3RegionMetric | None = Field(
         default=None,
         alias="regionMetrics",

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/google.py

@@ -705,7 +705,7 @@ class GoogleNamespace:
         as cursor to walk further, or use google.search_100 for up to 100 ranked
         results in one call, which is cheaper past roughly 20 results.
 
-        Price: $0.00099 per request.
+        Price: $0.0009 per request.
 
         Example:
             res = client.google.search(gl="us", hl="en", limit=10, query="best coffee maker")
@@ -970,7 +970,7 @@ class AsyncGoogleNamespace:
         as cursor to walk further, or use google.search_100 for up to 100 ranked
         results in one call, which is cheaper past roughly 20 results.
 
-        Price: $0.00099 per request.
+        Price: $0.0009 per request.
 
         Example:
             res = client.google.search(gl="us", hl="en", limit=10, query="best coffee maker")

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/instagram.py

@@ -156,7 +156,7 @@ class InstagramPostInput(TypedDict, total=False):
     requirePlayCount: NotRequired[bool]
     """Set true to be served only by a source that reports a reel's play count. The default cheapest source does not carry play counts, so `plays` is absent from its responses; opting in guarantees the field when Instagram exposes it, at a higher price per request."""
     url: Required[str]
-    """Full Instagram post or reel URL."""
+    """Full Instagram post or reel URL, carrying the media shortcode: /p/, /reel/, /reels/, or /tv/. A profile URL such as https://www.instagram.com/username names no post, so it is rejected instead of charged for an empty result."""
 
 
 class InstagramPostCommentsInput(TypedDict, total=False):
@@ -1876,7 +1876,7 @@ class InstagramNamespace:
         Fetch a single Instagram post or reel by URL (media URLs, like count, owner,
         type) as normalized JSON.
 
-        Price: $0.0009 per request.
+        Price: $0.0015 per request.
 
         Example:
             res = client.instagram.post(url="https://www.instagram.com/reel/DWzrfE2kaY8/")
@@ -1897,7 +1897,7 @@ class InstagramNamespace:
         List the comments on an Instagram post or reel by URL with cursor pagination
         (text, author, likes).
 
-        Price: $0.0015 per request.
+        Price: $0.00144 per request.
 
         Example:
             res = client.instagram.post_comments(url="https://www.instagram.com/reel/DWzrfE2kaY8/")
@@ -2050,7 +2050,9 @@ class InstagramNamespace:
         than Instagram's own hashtag feed. That is what lets it filter by date and
         media type and return reels whose like counts have settled, and it is also
         why results skew older (median around three months) and stop at roughly 110
-        per hashtag. For Instagram's own live ranking of a tag use
+        per hashtag. If that web search index is unavailable, a first-page request
+        that sets no date and no media type is served from Instagram's own live top
+        feed instead. For Instagram's own live ranking of a tag use
         instagram.hashtag_top_posts, and for the chronological feed use
         instagram.hashtag_recent_posts.
 
@@ -2741,7 +2743,7 @@ class AsyncInstagramNamespace:
         Fetch a single Instagram post or reel by URL (media URLs, like count, owner,
         type) as normalized JSON.
 
-        Price: $0.0009 per request.
+        Price: $0.0015 per request.
 
         Example:
             res = client.instagram.post(url="https://www.instagram.com/reel/DWzrfE2kaY8/")
@@ -2762,7 +2764,7 @@ class AsyncInstagramNamespace:
         List the comments on an Instagram post or reel by URL with cursor pagination
         (text, author, likes).
 
-        Price: $0.0015 per request.
+        Price: $0.00144 per request.
 
         Example:
             res = client.instagram.post_comments(url="https://www.instagram.com/reel/DWzrfE2kaY8/")
@@ -2915,7 +2917,9 @@ class AsyncInstagramNamespace:
         than Instagram's own hashtag feed. That is what lets it filter by date and
         media type and return reels whose like counts have settled, and it is also
         why results skew older (median around three months) and stop at roughly 110
-        per hashtag. For Instagram's own live ranking of a tag use
+        per hashtag. If that web search index is unavailable, a first-page request
+        that sets no date and no media type is served from Instagram's own live top
+        feed instead. For Instagram's own live ranking of a tag use
         instagram.hashtag_top_posts, and for the chronological feed use
         instagram.hashtag_recent_posts.
 

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/maps.py

@@ -65,7 +65,7 @@ class MapsReviewsInput(TypedDict, total=False):
     language: NotRequired[str]
     """Two-letter language code for the review details (e.g. en). Default: en."""
     limit: NotRequired[int]
-    """Maximum number of results to return (1-100, default 100). You are billed per result returned, so a lower limit costs less. Range: 1 to 100."""
+    """Maximum number of results to return (1-100, default 100). Range: 1 to 100."""
     placeId: Required[str]
     """The Google Maps place ID to fetch reviews for (e.g. ChIJj61dQgK6j4AR4GeTYWZsKWw)."""
     postedLimit: NotRequired[Literal["24h", "week", "month", "year"]]
@@ -308,7 +308,7 @@ class MapsReviewsItem(BaseModel):
     place_id: str | None = Field(
         default=None,
         alias="placeId",
-        description="Google Maps place id the review belongs to. Populated whenever the provider has data for the entity. Present whenever the upstream returns this record.",
+        description="Google Maps place id the review belongs to. Echoes the requested placeId; a lane that does not repeat it per review omits it.",
     )
     published_ago: str | None = Field(
         default=None,
@@ -468,10 +468,10 @@ class MapsNamespace:
         Fetch up to 100 Google Maps reviews for a place by place ID, sorted the way
         you need, in one normalized response.
 
-        Price: $0.00006 per request plus $0.00044 per result (maximum $0.0441).
+        Price: $0.0035 per request.
 
         Example:
-            res = client.maps.reviews(limit=3, placeId="ChIJN1t_tDeuEmsRUsoyG83frY4", postedLimit="year")
+            res = client.maps.reviews(limit=3, placeId="ChIJN1t_tDeuEmsRUsoyG83frY4")
         """
         raw = self._client._run_raw(  # pyright: ignore[reportPrivateUsage]
             "maps.reviews", dict(input), options
@@ -556,10 +556,10 @@ class AsyncMapsNamespace:
         Fetch up to 100 Google Maps reviews for a place by place ID, sorted the way
         you need, in one normalized response.
 
-        Price: $0.00006 per request plus $0.00044 per result (maximum $0.0441).
+        Price: $0.0035 per request.
 
         Example:
-            res = client.maps.reviews(limit=3, placeId="ChIJN1t_tDeuEmsRUsoyG83frY4", postedLimit="year")
+            res = client.maps.reviews(limit=3, placeId="ChIJN1t_tDeuEmsRUsoyG83frY4")
         """
         raw = await self._client._arun_raw(  # pyright: ignore[reportPrivateUsage]
             "maps.reviews", dict(input), options

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/perplexity.py

@@ -66,7 +66,7 @@ class PerplexityNamespace:
         Ask Perplexity a web-grounded question and receive an answer with source
         citations.
 
-        Price: $0.00006 per request plus $0.011 per result (maximum $0.0111).
+        Price: $0.0036 per request.
 
         Example:
             res = client.perplexity.search(prompt="What is AnyAPI at getanyapi.com, and what does it offer?")
@@ -94,7 +94,7 @@ class AsyncPerplexityNamespace:
         Ask Perplexity a web-grounded question and receive an answer with source
         citations.
 
-        Price: $0.00006 per request plus $0.011 per result (maximum $0.0111).
+        Price: $0.0036 per request.
 
         Example:
             res = client.perplexity.search(prompt="What is AnyAPI at getanyapi.com, and what does it offer?")

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/reddit.py

@@ -710,7 +710,7 @@ class RedditNamespace:
         Fetch a single Reddit post by URL, including its full body text, score,
         comment count, upvote ratio, and subreddit, as normalized JSON.
 
-        Price: $0.0009 per request.
+        Price: $0.0012 per request.
 
         Example:
             res = client.reddit.post(url="https://www.reddit.com/r/IAmA/comments/z1c9z/i_am_barack_obama_president_of_the_united_states/")
@@ -815,7 +815,7 @@ class RedditNamespace:
 
         Search Reddit posts across all subreddits by query.
 
-        Price: $0.0009 per request.
+        Price: $0.0012 per request.
 
         Example:
             res = client.reddit.search(query="mechanical keyboard")
@@ -1083,7 +1083,7 @@ class AsyncRedditNamespace:
         Fetch a single Reddit post by URL, including its full body text, score,
         comment count, upvote ratio, and subreddit, as normalized JSON.
 
-        Price: $0.0009 per request.
+        Price: $0.0012 per request.
 
         Example:
             res = client.reddit.post(url="https://www.reddit.com/r/IAmA/comments/z1c9z/i_am_barack_obama_president_of_the_united_states/")
@@ -1188,7 +1188,7 @@ class AsyncRedditNamespace:
 
         Search Reddit posts across all subreddits by query.
 
-        Price: $0.0009 per request.
+        Price: $0.0012 per request.
 
         Example:
             res = client.reddit.search(query="mechanical keyboard")

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/threads.py

@@ -36,10 +36,14 @@ class ThreadsProfileInput(TypedDict, total=False):
 class ThreadsSearchInput(TypedDict, total=False):
     """Input for Threads Search."""
 
+    endDate: NotRequired[str]
+    """Only return posts published on or before this date, format YYYY-MM-DD (e.g. 2026-08-07). Threads pages backwards in time from here, so narrowing this is how you walk older results."""
     preferLatencyUnderMs: NotRequired[int]
     """Optional; omit it and routing is unchanged, with the cheapest source serving. Prefer sources whose typical response time (median over the trailing 30 days, as published on this endpoint's lane health) is under this many milliseconds; among those, the cheapest serves. This can raise your price: when the cheapest source misses the target, a faster and dearer one serves, and you are quoted and charged its price. If no source is that fast the request is still served, by whichever source offers the best speed for its price - it is never refused for being slow. Sources we have not timed are tried last. This is a preference, not a guarantee: the median describes past requests and is not a ceiling on this one, and it excludes any wait this request itself asks for. On a paginated walk it applies to the first page only: later pages stay with the source that page chose, at the price it was quoted. Minimum: 1."""
     query: Required[str]
-    """Keyword or hashtag to search public Threads posts for; the # prefix is optional (e.g. AI agents)."""
+    """Keyword or hashtag to search public Threads posts for; the # prefix is optional (e.g. AI agents). Threads matches text in posts, so search a brand or topic rather than a URL - a query that is only a domain is searched by its name (wander.com is searched as wander)."""
+    startDate: NotRequired[str]
+    """Only return posts published on or after this date, format YYYY-MM-DD (e.g. 2026-08-01)."""
 
 
 class ThreadsSearchUsersInput(TypedDict, total=False):

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/tiktok.py

@@ -465,9 +465,11 @@ class TiktokTrendingHashtagsInput(TypedDict, total=False):
 class TiktokVideoInput(TypedDict, total=False):
     """Input for TikTok Video."""
 
+    id: NotRequired[str]
+    """TikTok video ID, the numeric run at the end of a video URL. Use it when a listing SKU handed you an id and no URL."""
     preferLatencyUnderMs: NotRequired[int]
     """Optional; omit it and routing is unchanged, with the cheapest source serving. Prefer sources whose typical response time (median over the trailing 30 days, as published on this endpoint's lane health) is under this many milliseconds; among those, the cheapest serves. This can raise your price: when the cheapest source misses the target, a faster and dearer one serves, and you are quoted and charged its price. If no source is that fast the request is still served, by whichever source offers the best speed for its price - it is never refused for being slow. Sources we have not timed are tried last. This is a preference, not a guarantee: the median describes past requests and is not a ceiling on this one, and it excludes any wait this request itself asks for. On a paginated walk it applies to the first page only: later pages stay with the source that page chose, at the price it was quoted. Minimum: 1."""
-    url: Required[str]
+    url: NotRequired[str]
     """Full TikTok video URL."""
 
 
@@ -1588,7 +1590,7 @@ class TiktokVideoTranscriptFullWord(BaseModel):
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
     confidence: float = Field(
-        description="Recognizer confidence for this word, 0 to 1. Low values mark words the recognizer guessed; they are common on names, jargon, and music. Range: 0 to 1."
+        description="Recognizer score for this word, exactly as the recognizer reported it. It is normally an alignment probability between 0 and 1, but on audio the recognizer could not align it reports a negative log-scale score instead, so read the sign before treating the number as a probability. Either way, lower means less certain, and low values are common on names, jargon, and music."
     )
     end_seconds: float | None = Field(
         default=None,

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/tripadvisor.py

@@ -178,7 +178,7 @@ class TripadvisorNamespace:
         attraction by its page URL: rating, text, date, and trip details as
         normalized JSON.
 
-        Price: $0.0036 per request.
+        Price: $0.003 per request.
 
         Example:
             res = client.tripadvisor.reviews(limit=3, url="https://www.tripadvisor.com/Hotel_Review-g60763-d93450-Reviews-The_Plaza-New_York_City_New_York.html")
@@ -200,7 +200,7 @@ class TripadvisorNamespace:
         destination and get rich place records (ratings, review counts, contact
         details, pricing) as normalized JSON.
 
-        Price: $0.0036 per request.
+        Price: $0.003 per request.
 
         Example:
             res = client.tripadvisor.search(limit=3, query="Paris")
@@ -229,7 +229,7 @@ class AsyncTripadvisorNamespace:
         attraction by its page URL: rating, text, date, and trip details as
         normalized JSON.
 
-        Price: $0.0036 per request.
+        Price: $0.003 per request.
 
         Example:
             res = client.tripadvisor.reviews(limit=3, url="https://www.tripadvisor.com/Hotel_Review-g60763-d93450-Reviews-The_Plaza-New_York_City_New_York.html")
@@ -251,7 +251,7 @@ class AsyncTripadvisorNamespace:
         destination and get rich place records (ratings, review counts, contact
         details, pricing) as normalized JSON.
 
-        Price: $0.0036 per request.
+        Price: $0.003 per request.
 
         Example:
             res = client.tripadvisor.search(limit=3, query="Paris")

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/trustpilot.py

@@ -21,9 +21,9 @@ class TrustpilotReviewsInput(TypedDict, total=False):
     company: Required[str]
     """Brand name or Trustpilot review-page URL to fetch reviews for (e.g. nike or https://www.trustpilot.com/review/nike.com)."""
     countries: NotRequired[list[str]]
-    """Only return reviews from reviewers in these ISO 3166-1 alpha-2 countries (e.g. ["US", "GB"]); omit for all countries."""
+    """Only return reviews from reviewers in these ISO 3166-1 alpha-2 countries (e.g. ["US", "GB"]). Omit this field for all countries and to stay on the cheapest price; a country filter routes to the dearest source."""
     languages: NotRequired[list[str]]
-    """Only return reviews in these ISO 639-1 languages (e.g. ["en", "de"]); omit for all languages."""
+    """Only return reviews in these ISO 639-1 languages (e.g. ["en", "de"]). Omit this field for all languages and to stay on the cheapest price; a language filter routes to the dearest source."""
     limit: NotRequired[int]
     """Maximum number of results to return (1-200, default 200). Trustpilot serves at most 200 reviews per company. Range: 1 to 200. Default: 200."""
     preferLatencyUnderMs: NotRequired[int]
@@ -31,11 +31,11 @@ class TrustpilotReviewsInput(TypedDict, total=False):
     sortBy: NotRequired[str]
     """Review ordering: auto, relevancy, or recent (e.g. recent). Default: auto."""
     stars: NotRequired[str]
-    """Limit reviews to a single star rating from 1 to 5 (e.g. 5); omit for all ratings."""
+    """Limit reviews to a single star rating from 1 to 5 (e.g. 5). Omit this field to stay on the cheapest price; a star filter routes to a dearer source."""
     startDate: NotRequired[str]
-    """Only return reviews on or after this date, inclusive, in YYYY-MM-DD format (e.g. 2026-01-01)."""
+    """Only return reviews on or after this date, inclusive, in YYYY-MM-DD format (e.g. 2026-01-01). Omit this field to stay on the cheapest price; a date floor routes to the dearest source."""
     verifiedOnly: NotRequired[bool]
-    """Set true to return only verified reviews (e.g. true). Default: false."""
+    """Set true to return only verified reviews (e.g. true). Omit this field, or send false, to stay on the cheapest price; true routes to a dearer source. Default: false."""
 
 
 class TrustpilotReviewsData(BaseModel):

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/twitter.py

@@ -103,8 +103,6 @@ class TwitterSearchInput(TypedDict, total=False):
 
     cursor: NotRequired[str]
     """Opaque pagination cursor from a previous response's nextCursor. Omit for the first page; pass it to fetch the next page of search results."""
-    lang: NotRequired[str]
-    """Optional ISO 639-1 language code to restrict tweets to (e.g. en)."""
     limit: NotRequired[int]
     """Per-page maximum number of results to return (1-50, default 20). A provider may return a smaller native page; follow nextCursor for more. Range: 1 to 50. Default: 20."""
     preferLatencyUnderMs: NotRequired[int]

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/yelp.py

@@ -19,7 +19,7 @@ class YelpSearchInput(TypedDict, total=False):
     """Input for Yelp Search."""
 
     limit: NotRequired[int]
-    """Maximum number of results to return (1 to 20, default 20). Range: 1 to 20."""
+    """Maximum number of results to return (1 to 20, default 20). Range: 1 to 20. Default: 20."""
     location: Required[str]
     """City and state defining the search area (e.g. San Francisco, CA)."""
     preferLatencyUnderMs: NotRequired[int]
@@ -113,7 +113,7 @@ class YelpNamespace:
         Search Yelp for businesses by keyword and location: up to 20 listings with
         ratings, categories, and core business info per request.
 
-        Price: $0.044 per request plus $0.00083 per result (maximum $0.0605).
+        Price: $0.0035 per request.
 
         Example:
             res = client.yelp.search(limit=5, location="Chicago, IL", query="pizza")
@@ -138,7 +138,7 @@ class AsyncYelpNamespace:
         Search Yelp for businesses by keyword and location: up to 20 listings with
         ratings, categories, and core business info per request.
 
-        Price: $0.044 per request plus $0.00083 per result (maximum $0.0605).
+        Price: $0.0035 per request.
 
         Example:
             res = client.yelp.search(limit=5, location="Chicago, IL", query="pizza")

{getanyapi-0.35.3 → getanyapi-0.37.0}/src/getanyapi/platforms/youtube.py

@@ -165,8 +165,23 @@ class YoutubeSearchHashtagInput(TypedDict, total=False):
     """Hashtag to search for (without the leading #)."""
     preferLatencyUnderMs: NotRequired[int]
     """Optional; omit it and routing is unchanged, with the cheapest source serving. Prefer sources whose typical response time (median over the trailing 30 days, as published on this endpoint's lane health) is under this many milliseconds; among those, the cheapest serves. This can raise your price: when the cheapest source misses the target, a faster and dearer one serves, and you are quoted and charged its price. If no source is that fast the request is still served, by whichever source offers the best speed for its price - it is never refused for being slow. Sources we have not timed are tried last. This is a preference, not a guarantee: the median describes past requests and is not a ceiling on this one, and it excludes any wait this request itself asks for. On a paginated walk it applies to the first page only: later pages stay with the source that page chose, at the price it was quoted. Minimum: 1."""
-    type: NotRequired[Literal["all", "shorts"]]
-    """Content filter."""
+    type: NotRequired[Literal["all"]]
+    """Content filter. Only "all" is served: no source we buy returns a Shorts row with the channel and publish time this endpoint requires."""
+
+
+class YoutubeSearchShortsInput(TypedDict, total=False):
+    """Input for YouTube Shorts Search."""
+
+    cursor: NotRequired[str]
+    """Continuation token from a previous response for pagination."""
+    preferLatencyUnderMs: NotRequired[int]
+    """Optional; omit it and routing is unchanged, with the cheapest source serving. Prefer sources whose typical response time (median over the trailing 30 days, as published on this endpoint's lane health) is under this many milliseconds; among those, the cheapest serves. This can raise your price: when the cheapest source misses the target, a faster and dearer one serves, and you are quoted and charged its price. If no source is that fast the request is still served, by whichever source offers the best speed for its price - it is never refused for being slow. Sources we have not timed are tried last. This is a preference, not a guarantee: the median describes past requests and is not a ceiling on this one, and it excludes any wait this request itself asks for. On a paginated walk it applies to the first page only: later pages stay with the source that page chose, at the price it was quoted. Minimum: 1."""
+    query: Required[str]
+    """The keyword to search Shorts for."""
+    sortBy: NotRequired[Literal["relevance", "popular"]]
+    """Sort order: "relevance" (default) or "popular" (most-viewed). Default: relevance."""
+    uploadDate: NotRequired[Literal["today", "this_week", "this_month", "this_year"]]
+    """Filter by upload recency. Omit for any time."""
 
 
 class YoutubeTrendingShortsInput(TypedDict, total=False):
@@ -180,11 +195,11 @@ class YoutubeVideoInput(TypedDict, total=False):
     """Input for YouTube Video."""
 
     id: NotRequired[str]
-    """YouTube video ID."""
+    """YouTube video ID. A Short uses the same ID as any other video."""
     preferLatencyUnderMs: NotRequired[int]
     """Optional; omit it and routing is unchanged, with the cheapest source serving. Prefer sources whose typical response time (median over the trailing 30 days, as published on this endpoint's lane health) is under this many milliseconds; among those, the cheapest serves. This can raise your price: when the cheapest source misses the target, a faster and dearer one serves, and you are quoted and charged its price. If no source is that fast the request is still served, by whichever source offers the best speed for its price - it is never refused for being slow. Sources we have not timed are tried last. This is a preference, not a guarantee: the median describes past requests and is not a ceiling on this one, and it excludes any wait this request itself asks for. On a paginated walk it applies to the first page only: later pages stay with the source that page chose, at the price it was quoted. Minimum: 1."""
     url: NotRequired[str]
-    """Full YouTube video URL."""
+    """Full YouTube video URL. Shorts (youtube.com/shorts/...), youtu.be, live, and embed URLs all work."""
 
 
 class YoutubeVideoCommentsInput(TypedDict, total=False):
@@ -197,7 +212,7 @@ class YoutubeVideoCommentsInput(TypedDict, total=False):
     preferLatencyUnderMs: NotRequired[int]
     """Optional; omit it and routing is unchanged, with the cheapest source serving. Prefer sources whose typical response time (median over the trailing 30 days, as published on this endpoint's lane health) is under this many milliseconds; among those, the cheapest serves. This can raise your price: when the cheapest source misses the target, a faster and dearer one serves, and you are quoted and charged its price. If no source is that fast the request is still served, by whichever source offers the best speed for its price - it is never refused for being slow. Sources we have not timed are tried last. This is a preference, not a guarantee: the median describes past requests and is not a ceiling on this one, and it excludes any wait this request itself asks for. On a paginated walk it applies to the first page only: later pages stay with the source that page chose, at the price it was quoted. Minimum: 1."""
     url: Required[str]
-    """Full YouTube video URL."""
+    """Full YouTube video URL. Shorts (youtube.com/shorts/...) and youtu.be URLs also work."""
 
 
 class YoutubeVideoSponsorsInput(TypedDict, total=False):
@@ -215,11 +230,11 @@ class YoutubeVideoTranscriptInput(TypedDict, total=False):
     """Input for YouTube Video Transcript."""
 
     id: NotRequired[str]
-    """YouTube video ID."""
+    """YouTube video ID. A Short uses the same ID as any other video."""
     preferLatencyUnderMs: NotRequired[int]
     """Optional; omit it and routing is unchanged, with the cheapest source serving. Prefer sources whose typical response time (median over the trailing 30 days, as published on this endpoint's lane health) is under this many milliseconds; among those, the cheapest serves. This can raise your price: when the cheapest source misses the target, a faster and dearer one serves, and you are quoted and charged its price. If no source is that fast the request is still served, by whichever source offers the best speed for its price - it is never refused for being slow. Sources we have not timed are tried last. This is a preference, not a guarantee: the median describes past requests and is not a ceiling on this one, and it excludes any wait this request itself asks for. On a paginated walk it applies to the first page only: later pages stay with the source that page chose, at the price it was quoted. Minimum: 1."""
     url: NotRequired[str]
-    """Full YouTube video URL."""
+    """Full YouTube video URL. Shorts (youtube.com/shorts/...), youtu.be, live, and embed URLs all work."""
 
 
 class YoutubeVideoTranscriptFullInput(TypedDict, total=False):
@@ -232,7 +247,7 @@ class YoutubeVideoTranscriptFullInput(TypedDict, total=False):
     preferLatencyUnderMs: NotRequired[int]
     """Optional; omit it and routing is unchanged, with the cheapest source serving. Prefer sources whose typical response time (median over the trailing 30 days, as published on this endpoint's lane health) is under this many milliseconds; among those, the cheapest serves. This can raise your price: when the cheapest source misses the target, a faster and dearer one serves, and you are quoted and charged its price. If no source is that fast the request is still served, by whichever source offers the best speed for its price - it is never refused for being slow. Sources we have not timed are tried last. This is a preference, not a guarantee: the median describes past requests and is not a ceiling on this one, and it excludes any wait this request itself asks for. On a paginated walk it applies to the first page only: later pages stay with the source that page chose, at the price it was quoted. Minimum: 1."""
     url: Required[str]
-    """YouTube video URL (e.g. "https://www.youtube.com/watch?v=dQw4w9WgXcQ")."""
+    """YouTube video or Short URL (e.g. "https://www.youtube.com/watch?v=dQw4w9WgXcQ" or "https://www.youtube.com/shorts/Fir1x9cw2vg")."""
 
 
 class YoutubeChannelData(BaseModel):
@@ -388,8 +403,9 @@ class YoutubeChannelShortsShort(BaseModel):
     likes: int = Field(
         description="Public like count when supplied by the upstream response. Minimum: 0."
     )
-    title: str = Field(
-        description="Public title or caption for the Short. Populated whenever the provider has data for the entity."
+    title: str | None = Field(
+        default=None,
+        description="Public title or caption for the Short. Populated whenever the provider has data for the entity. Present whenever the upstream returns this record.",
     )
     url: str = Field(
         description="Public YouTube URL for the Short. Populated whenever the provider has data for the entity."
@@ -597,6 +613,44 @@ class YoutubeSearchHashtagVideo(BaseModel):
     views: int
 
 
+class YoutubeSearchShortsData(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    next_cursor: str | None = Field(
+        default=None,
+        alias="nextCursor",
+        description="Opaque cursor for the next page of results, or null when there are no more. Pass it back as cursor to continue.",
+    )
+    shorts: list[YoutubeSearchShortsShort] = Field(
+        description="Populated whenever the provider has data for the entity."
+    )
+
+
+class YoutubeSearchShortsShort(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    content_type: str = Field(
+        alias="contentType",
+        description='Always "short": every row here comes from YouTube\'s Shorts shelf.',
+    )
+    id: str = Field(
+        description="YouTube video id of the Short. Populated whenever the provider has data for the entity."
+    )
+    title: str = Field(
+        description="Title of the Short. Populated whenever the provider has data for the entity."
+    )
+    url: str = Field(
+        description="Watch URL for the Short. Populated whenever the provider has data for the entity."
+    )
+    views: int = Field(
+        description="View count, or 0 when the source did not publish one. Read viewsAvailable before trusting a 0."
+    )
+    views_available: bool = Field(
+        alias="viewsAvailable",
+        description="False when the source published no view count, so views is a placeholder rather than a measured zero.",
+    )
+
+
 class YoutubeTrendingShortsData(BaseModel):
     shorts: list[YoutubeTrendingShortsShort] = Field(
         description="Populated whenever the provider has data for the entity."
@@ -1203,6 +1257,50 @@ class YoutubeNamespace:
             options=options,
         )
 
+    def search_shorts(
+        self,
+        *,
+        options: RequestOptions | None = None,
+        **input: Unpack[YoutubeSearchShortsInput],
+    ) -> RunResult[YoutubeSearchShortsData]:
+        """YouTube Shorts Search
+
+        Search YouTube Shorts by keyword and get matching Shorts (title, views, URL)
+        with cursor pagination as normalized JSON.
+
+        Price: $0.002 per request.
+
+        Example:
+            res = client.youtube.search_shorts(query="cats")
+        """
+        raw = self._client._run_raw(  # pyright: ignore[reportPrivateUsage]
+            "youtube.search_shorts", dict(input), options
+        )
+        return RunResult[YoutubeSearchShortsData].model_validate(raw)
+
+    def iter_search_shorts(
+        self,
+        *,
+        options: RequestOptions | None = None,
+        **input: Unpack[YoutubeSearchShortsInput],
+    ) -> Paginator[YoutubeSearchShortsShort, YoutubeSearchShortsData]:
+        """Iterate YouTube Shorts Search results, following pagination cursors.
+
+        Yields validated `YoutubeSearchShortsShort` items from the `shorts` field of
+        each page. Use `.pages()` on the returned paginator to walk whole
+        `RunResult` pages.
+        """
+        return paginate(
+            self._client,
+            "youtube.search_shorts",
+            dict(input),
+            "shorts",
+            item_model=YoutubeSearchShortsShort,
+            data_model=YoutubeSearchShortsData,
+            bare=False,
+            options=options,
+        )
+
     def trending_shorts(
         self,
         *,
@@ -1232,8 +1330,8 @@ class YoutubeNamespace:
     ) -> RunResult[YoutubeVideoData]:
         """YouTube Video
 
-        Fetch a YouTube video's metadata (title, channel, views, likes, duration,
-        publish date) by URL or ID.
+        Fetch a YouTube video or Short's metadata (title, channel, views, likes,
+        duration, publish date) by URL or ID.
 
         Price: $0.00125 per request.
 
@@ -1253,8 +1351,8 @@ class YoutubeNamespace:
     ) -> RunResult[YoutubeVideoCommentsData]:
         """YouTube Video Comments
 
-        List the comments on a YouTube video by URL with cursor pagination (text,
-        author, likes, reply count).
+        List the comments on a YouTube video or Short by URL with cursor pagination
+        (text, author, likes, reply count).
 
         Price: $0.002 per request.
 
@@ -1318,7 +1416,7 @@ class YoutubeNamespace:
     ) -> RunResult[YoutubeVideoTranscriptData]:
         """YouTube Video Transcript
 
-        Fetch the transcript/captions of a YouTube video by URL or ID.
+        Fetch the transcript/captions of a YouTube video or Short by URL or ID.
 
         Price: $0.00125 per request.
 
@@ -1338,10 +1436,11 @@ class YoutubeNamespace:
     ) -> RunResult[YoutubeVideoTranscriptFullData]:
         """YouTube Video Transcript (Provenance)
 
-        Fetch a YouTube transcript with timed segments and its provenance: whether
-        the words are creator-written captions or machine speech recognition.
+        Fetch a YouTube video or Short transcript with timed segments and its
+        provenance: whether the words are creator-written captions or machine speech
+        recognition.
 
-        Price: $0.00308 per request plus $0 per result (maximum $0.00308).
+        Price: $0.001 per request.
 
         Example:
             res = client.youtube.video_transcript_full(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")
@@ -1775,6 +1874,50 @@ class AsyncYoutubeNamespace:
             options=options,
         )
 
+    async def search_shorts(
+        self,
+        *,
+        options: RequestOptions | None = None,
+        **input: Unpack[YoutubeSearchShortsInput],
+    ) -> RunResult[YoutubeSearchShortsData]:
+        """YouTube Shorts Search
+
+        Search YouTube Shorts by keyword and get matching Shorts (title, views, URL)
+        with cursor pagination as normalized JSON.
+
+        Price: $0.002 per request.
+
+        Example:
+            res = client.youtube.search_shorts(query="cats")
+        """
+        raw = await self._client._arun_raw(  # pyright: ignore[reportPrivateUsage]
+            "youtube.search_shorts", dict(input), options
+        )
+        return RunResult[YoutubeSearchShortsData].model_validate(raw)
+
+    def iter_search_shorts(
+        self,
+        *,
+        options: RequestOptions | None = None,
+        **input: Unpack[YoutubeSearchShortsInput],
+    ) -> AsyncPaginator[YoutubeSearchShortsShort, YoutubeSearchShortsData]:
+        """Iterate YouTube Shorts Search results, following pagination cursors.
+
+        Yields validated `YoutubeSearchShortsShort` items from the `shorts` field of
+        each page. Use `.pages()` on the returned paginator to walk whole
+        `RunResult` pages.
+        """
+        return apaginate(
+            self._client,
+            "youtube.search_shorts",
+            dict(input),
+            "shorts",
+            item_model=YoutubeSearchShortsShort,
+            data_model=YoutubeSearchShortsData,
+            bare=False,
+            options=options,
+        )
+
     async def trending_shorts(
         self,
         *,
@@ -1804,8 +1947,8 @@ class AsyncYoutubeNamespace:
     ) -> RunResult[YoutubeVideoData]:
         """YouTube Video
 
-        Fetch a YouTube video's metadata (title, channel, views, likes, duration,
-        publish date) by URL or ID.
+        Fetch a YouTube video or Short's metadata (title, channel, views, likes,
+        duration, publish date) by URL or ID.
 
         Price: $0.00125 per request.
 
@@ -1825,8 +1968,8 @@ class AsyncYoutubeNamespace:
     ) -> RunResult[YoutubeVideoCommentsData]:
         """YouTube Video Comments
 
-        List the comments on a YouTube video by URL with cursor pagination (text,
-        author, likes, reply count).
+        List the comments on a YouTube video or Short by URL with cursor pagination
+        (text, author, likes, reply count).
 
         Price: $0.002 per request.
 
@@ -1890,7 +2033,7 @@ class AsyncYoutubeNamespace:
     ) -> RunResult[YoutubeVideoTranscriptData]:
         """YouTube Video Transcript
 
-        Fetch the transcript/captions of a YouTube video by URL or ID.
+        Fetch the transcript/captions of a YouTube video or Short by URL or ID.
 
         Price: $0.00125 per request.
 
@@ -1910,10 +2053,11 @@ class AsyncYoutubeNamespace:
     ) -> RunResult[YoutubeVideoTranscriptFullData]:
         """YouTube Video Transcript (Provenance)
 
-        Fetch a YouTube transcript with timed segments and its provenance: whether
-        the words are creator-written captions or machine speech recognition.
+        Fetch a YouTube video or Short transcript with timed segments and its
+        provenance: whether the words are creator-written captions or machine speech
+        recognition.
 
-        Price: $0.00308 per request plus $0 per result (maximum $0.00308).
+        Price: $0.001 per request.
 
         Example:
             res = client.youtube.video_transcript_full(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")

{getanyapi-0.35.3 → getanyapi-0.37.0}/tests/test_account.py

@@ -12,6 +12,7 @@ import pytest
 
 from conftest import json_response, make_async_client, make_sync_client
 from getanyapi import (
+    AnyAPIError,
     DiscoveryPricing,
     FlatPricingOffer,
     LinearPricingOffer,
@@ -331,6 +332,40 @@ def test_search_reads_every_shared_ranked_field_and_forwards_filters() -> None:
     assert found.model_dump(by_alias=True, exclude_defaults=True) == body
 
 
+def test_search_scopes_without_a_query_and_omits_q_entirely() -> None:
+    body = discovery_search()
+
+    def respond(req: httpx.Request) -> httpx.Response:
+        assert req.url.path == "/catalog/search"
+        assert dict(req.url.params) == {"platform": "reddit"}
+        return json_response(200, body)
+
+    client, _ = make_sync_client(respond)
+    assert client.search(platform="reddit").results
+
+
+def test_search_omits_an_empty_query_rather_than_sending_it_empty() -> None:
+    body = discovery_search()
+
+    def respond(req: httpx.Request) -> httpx.Response:
+        assert "q" not in dict(req.url.params)
+        return json_response(200, body)
+
+    client, _ = make_sync_client(respond)
+    assert client.search(query="", category="social").results
+
+
+def test_search_without_query_category_or_platform_never_calls_the_gateway() -> None:
+    client, recorder = make_sync_client(
+        lambda _req: json_response(200, discovery_search())
+    )
+    with pytest.raises(
+        AnyAPIError, match="at least one of query, category, or platform"
+    ):
+        client.search(limit=5)
+    assert recorder.requests == []
+
+
 def test_search_drops_safe_additive_result_and_envelope_fields() -> None:
     body = discovery_search()
     results = cast("list[dict[str, object]]", body["results"])