Search 模块 API 文档¶

Search（搜索采集）模块提供 X (Twitter) 平台的搜索功能，支持五种搜索类型：热门（Top）、最新（Latest）、用户（People）、媒体（Media）和 Lists。所有搜索方法均支持 cursor 分页。

目录¶

模块概述
SearchClient 类
类型定义
使用示例
高级搜索语法
常见问题

模块概述¶

Search 模块提供两种使用方式：

方式 1: 通过 Twitter 主入口访问（推荐）¶

from x_api_rs import Twitter

client = await Twitter.create(cookies)
result = await client.search.search_top("python")

方式 2: 独立创建 SearchClient¶

from x_api_rs.search import SearchClient

search_client = await SearchClient.create(cookies, proxy_url="http://proxy:8080")
result = await search_client.search_top("python")

SearchClient 类¶

创建方法¶

@staticmethod
async def create(
    cookies: str,
    proxy_url: str | None = None,
    enable_ja3: bool = True
) -> SearchClient

参数：

参数	类型	必填	说明
`cookies`	str	是	Twitter cookies 字符串
`proxy_url`	str \| None	否	代理服务器 URL
`enable_ja3`	bool	否	是否启用 JA3 指纹模拟（默认 True）

search_top¶

搜索热门内容（按相关性/热度排序）。

async def search_top(
    query: str,
    cursor: str | None = None
) -> SearchTweetsResult

参数：

参数	类型	必填	说明
`query`	str	是	搜索关键词，支持 Twitter 高级搜索语法
`cursor`	str \| None	否	分页游标

返回： SearchTweetsResult

search_latest¶

搜索最新内容（按时间倒序排列）。

async def search_latest(
    query: str,
    cursor: str | None = None
) -> SearchTweetsResult

参数： 同 search_top

返回： SearchTweetsResult

search_people¶

搜索用户账号。

async def search_people(
    query: str,
    cursor: str | None = None
) -> SearchUsersResult

参数： 同 search_top

返回： SearchUsersResult

search_media¶

搜索含图片/视频的帖子。

async def search_media(
    query: str,
    cursor: str | None = None
) -> SearchTweetsResult

参数： 同 search_top

返回： SearchTweetsResult（帖子的 media_urls 字段包含媒体链接）

search_lists¶

搜索 Twitter Lists。

async def search_lists(
    query: str,
    cursor: str | None = None
) -> SearchListsResult

参数： 同 search_top

返回： SearchListsResult

类型定义¶

SearchTweetsResult¶

帖子搜索结果（Top/Latest/Media 共用）。

属性	类型	说明
`success`	bool	请求是否成功
`tweets`	list[TweetInfo]	帖子列表
`next_cursor`	str \| None	下一页游标
`has_more`	bool	是否有更多数据
`error_msg`	str	错误信息
`http_status`	int	HTTP 状态码

TweetInfo 类型详见 Posts 模块文档

SearchUsersResult¶

用户搜索结果。

属性	类型	说明
`success`	bool	请求是否成功
`users`	list[UserResp]	用户列表
`next_cursor`	str \| None	下一页游标
`has_more`	bool	是否有更多数据
`error_msg`	str	错误信息
`http_status`	int	HTTP 状态码

UserResp 类型详见 User 模块文档，包含 user_id、screen_name、name、description、followers_count、following_count、profile_image_url 等完整字段

SearchListsResult¶

Lists 搜索结果。

属性	类型	说明
`success`	bool	请求是否成功
`lists`	list[ListInfo]	列表信息列表
`next_cursor`	str \| None	下一页游标
`has_more`	bool	是否有更多数据
`error_msg`	str	错误信息
`http_status`	int	HTTP 状态码

ListInfo¶

单个 Twitter List 的信息。

属性	类型	说明
`list_id`	str	List ID
`name`	str	List 名称
`description`	str \| None	List 描述
`member_count`	int	成员数量
`subscriber_count`	int	订阅者数量
`creator_name`	str \| None	创建者显示名称
`creator_screen_name`	str \| None	创建者用户名
`creator_id`	str \| None	创建者用户 ID
`banner_url`	str \| None	Banner 图片 URL
`created_at`	str \| None	创建时间（时间戳字符串）

使用示例¶

搜索热门帖子¶

result = await client.search.search_top("python")
if result.success:
    for tweet in result.tweets:
        print(f"@{tweet.author_screen_name}: {tweet.text}")
        print(f"  likes: {tweet.favorite_count}, retweets: {tweet.retweet_count}")

搜索用户¶

result = await client.search.search_people("Elon")
if result.success:
    for user in result.users:
        print(f"@{user.screen_name} ({user.followers_count} followers)")

搜索媒体¶

result = await client.search.search_media("cat")
if result.success:
    for tweet in result.tweets:
        if tweet.media_urls:
            print(f"媒体: {tweet.media_urls}")

搜索 Lists¶

result = await client.search.search_lists("crypto")
if result.success:
    for li in result.lists:
        print(f"{li.name} by @{li.creator_screen_name} ({li.member_count} members)")

分页采集¶

all_tweets = []
result = await client.search.search_latest("bitcoin")
if result.success:
    all_tweets.extend(result.tweets)
    while result.has_more and len(all_tweets) < 100:
        result = await client.search.search_latest("bitcoin", cursor=result.next_cursor)
        if result.success:
            all_tweets.extend(result.tweets)

print(f"共采集 {len(all_tweets)} 条帖子")

高级搜索语法¶

搜索关键词支持 Twitter 高级搜索运算符，直接在 query 参数中使用：

语法	说明	示例
`from:user`	指定用户的帖子	`from:elonmusk`
`to:user`	回复指定用户的帖子	`to:elonmusk`
`since:YYYY-MM-DD`	指定日期之后	`since:2024-01-01`
`until:YYYY-MM-DD`	指定日期之前	`until:2024-12-31`
`min_faves:N`	最少 N 个点赞	`min_faves:100`
`min_retweets:N`	最少 N 次转发	`min_retweets:50`
`lang:xx`	指定语言	`lang:zh`
`filter:media`	包含媒体	`cat filter:media`
`-filter:retweets`	排除转发	`python -filter:retweets`

组合示例：

# 搜索 Elon Musk 2024 年以来点赞超过 100 的英文帖子
result = await client.search.search_latest(
    "from:elonmusk since:2024-01-01 min_faves:100 lang:en"
)

常见问题¶

Q: 搜索返回 404？¶

GraphQL query ID 可能过期。参考 vladkens/twscrape 获取最新值。

Q: 并发搜索时部分返回 404？¶

Twitter 搜索 API 对频率敏感，并发请求过多会触发限流。建议添加请求间隔或逐个执行。

Q: 搜索结果和网页版数量不同？¶

API 返回的结果可能与网页版不同，这是 Twitter 的正常行为。API 默认每页约 20 条。