> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Search API

从全网搜索任何网页信息和网页链接，结果准确、摘要完整，更适合 AI 使用。

搜索结果包括网页、图片

* 网页包括 name、url、snippet、summary、siteName、siteIcon、datePublished 等信息
* 图片包括 contentUrl、hostPageUrl、width、height 等信息

<Tip>
  可配置搜索时间范围、是否显示摘要，支持按分页获取更多结果。
</Tip>

## 请求头

<ParamField header="Content-Type" type="string" required={true}>
  枚举值: `application/json`
</ParamField>

<ParamField header="Authorization" type="string" required={true}>
  Bearer 身份验证格式，例如：Bearer \{\{API 密钥}}。
</ParamField>

## 请求体

<ParamField body="query" type="string" required={true}>
  用户的搜索词。
</ParamField>

<ParamField body="freshness" type="string" required={false}>
  搜索指定时间范围内的网页。

  可填值：

  * `noLimit`，不限（默认）
  * `oneDay`，一天内
  * `oneWeek`，一周内
  * `oneMonth`，一个月内
  * `oneYear`，一年内
  * `YYYY-MM-DD..YYYY-MM-DD`，搜索日期范围，例如："2025-01-01..2025-04-06"
  * `YYYY-MM-DD`，搜索指定日期，例如："2025-04-06"

  <Tip>
    推荐使用 `noLimit`。搜索算法会自动进行时间范围的改写，效果更佳。如果指定时间范围，很有可能出现时间范围内没有相关网页的情况，导致找不到搜索结果。
  </Tip>
</ParamField>

<ParamField body="summary" type="boolean" required={false}>
  是否显示文本摘要。

  可填值：

  * `true`，显示
  * `false`，不显示（默认）
</ParamField>

<ParamField body="include" type="string" required={false}>
  指定搜索的网站范围。多个域名使用 `|` 或 `,` 分隔，最多不能超过20个

  可填值：

  * 根域名
  * 子域名

  例如：qq.com|m.163.com
</ParamField>

<ParamField body="exclude" type="string" required={false}>
  排除搜索的网站范围。多个域名使用 `|` 或 `,` 分隔，最多不能超过20个

  可填值：

  * 根域名
  * 子域名

  例如：qq.com|m.163.com
</ParamField>

<ParamField body="count" type="int" required={false}>
  返回结果的条数（实际返回结果数量可能会小于count指定的数量）。

  * 可填范围：1-50，最大单次搜索返回50条
  * 默认为10
</ParamField>

## 响应

<ResponseField name="SearchData" type="object">
  搜索响应的主要数据对象

  <Expandable title="properties">
    <ResponseField name="_type" type="string">
      搜索的类型，固定值为 "SearchResponse"
    </ResponseField>

    <ResponseField name="queryContext" type="WebSearchQueryContext">
      搜索查询的上下文信息
    </ResponseField>

    <ResponseField name="webPages" type="WebSearchWebPages">
      搜索的网页结果
    </ResponseField>

    <ResponseField name="images" type="WebSearchImages">
      搜索的图片结果
    </ResponseField>

    <ResponseField name="videos" type="WebSearchVideos">
      搜索的视频结果
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="WebSearchQueryContext" type="object">
  搜索查询的上下文信息

  <Expandable title="properties">
    <ResponseField name="originalQuery" type="string">
      原始的搜索关键字
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="WebSearchWebPages" type="object">
  搜索的网页结果集合

  <Expandable title="properties">
    <ResponseField name="webSearchUrl" type="string">
      搜索结果的URL
    </ResponseField>

    <ResponseField name="totalEstimatedMatches" type="int">
      搜索匹配的网页总数
    </ResponseField>

    <ResponseField name="value" type="List<WebPageValue>">
      网页搜索结果列表
    </ResponseField>

    <ResponseField name="someResultsRemoved" type="boolean">
      结果中是否有被安全过滤的内容
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="WebPageValue" type="object">
  单个网页搜索结果的详细信息

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      网页的排序ID
    </ResponseField>

    <ResponseField name="name" type="string">
      网页的标题
    </ResponseField>

    <ResponseField name="url" type="string">
      网页的URL
    </ResponseField>

    <ResponseField name="displayUrl" type="string">
      网页的展示URL（url decode后的格式）
    </ResponseField>

    <ResponseField name="snippet" type="string">
      网页内容的简短描述
    </ResponseField>

    <ResponseField name="summary" type="string">
      网页内容的文本摘要，当请求参数中 summary 为 true 时显示此属性
    </ResponseField>

    <ResponseField name="siteName" type="string">
      网页的网站名称
    </ResponseField>

    <ResponseField name="siteIcon" type="string">
      网页的网站图标
    </ResponseField>

    <ResponseField name="datePublished" type="string">
      网页的发布时间（例如：2025-02-23T08:18:30+08:00），UTC+8时间
    </ResponseField>

    <ResponseField name="dateLastCrawled" type="string">
      网页的发布时间（此处其实是发布时间，名字起为LastCrawled是兼容性适配）

      <Tip>
        接口中返回的 `dateLastCrawled` 值（例如：2025-02-23T08:18:30Z）实际上要表达的是 UTC+8 北京时间2025-02-23 08:18:30，并非UTC时间。

        实际应用中请使用 `datePublished` 字段，或将 "2025-02-23T08:18:30Z" 替换成 "2025-02-23T08:18:30+08:00"，即得到正确的UTC+8时间，可以使用 datetime 函数正确解析。
      </Tip>
    </ResponseField>

    <ResponseField name="cachedPageUrl" type="string">
      网页的缓存页面URL
    </ResponseField>

    <ResponseField name="language" type="string">
      网页的语言
    </ResponseField>

    <ResponseField name="isFamilyFriendly" type="boolean">
      是否为家庭友好的页面
    </ResponseField>

    <ResponseField name="isNavigational" type="boolean">
      是否为导航性页面
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="WebSearchImages" type="object">
  搜索的图片结果集合

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      图片搜索结果的ID
    </ResponseField>

    <ResponseField name="readLink" type="string">
      图片的读取链接
    </ResponseField>

    <ResponseField name="webSearchUrl" type="string">
      图片搜索结果的URL
    </ResponseField>

    <ResponseField name="isFamilyFriendly" type="boolean">
      是否为家庭友好的图片
    </ResponseField>

    <ResponseField name="value" type="List<ImageValue>">
      图片搜索结果列表
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="WebSearchVideos" type="object">
  搜索的视频结果集合

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      视频搜索结果的ID
    </ResponseField>

    <ResponseField name="readLink" type="string">
      视频的读取链接
    </ResponseField>

    <ResponseField name="webSearchUrl" type="string">
      视频搜索结果的URL
    </ResponseField>

    <ResponseField name="isFamilyFriendly" type="boolean">
      是否为家庭友好的视频
    </ResponseField>

    <ResponseField name="scenario" type="string">
      视频的场景描述
    </ResponseField>

    <ResponseField name="value" type="List<VideoValue>">
      视频搜索结果列表
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ImageValue" type="object">
  单个图片搜索结果的详细信息

  <Expandable title="properties">
    <ResponseField name="webSearchUrl" type="string">
      图片的搜索URL
    </ResponseField>

    <ResponseField name="name" type="string">
      图片的名称
    </ResponseField>

    <ResponseField name="thumbnailUrl" type="string">
      图片的缩略图URL
    </ResponseField>

    <ResponseField name="datePublished" type="string">
      图片的发布时间
    </ResponseField>

    <ResponseField name="contentUrl" type="string">
      图片的内容URL
    </ResponseField>

    <ResponseField name="hostPageUrl" type="string">
      图片所在页面的URL
    </ResponseField>

    <ResponseField name="contentSize" type="string">
      图片的文件大小
    </ResponseField>

    <ResponseField name="encodingFormat" type="string">
      图片的编码格式
    </ResponseField>

    <ResponseField name="hostPageDisplayUrl" type="string">
      图片所在页面的展示URL
    </ResponseField>

    <ResponseField name="width" type="int">
      图片的宽度
    </ResponseField>

    <ResponseField name="height" type="int">
      图片的高度
    </ResponseField>

    <ResponseField name="thumbnail" type="Thumbnail">
      图片的缩略图信息
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="VideoValue" type="object">
  单个视频搜索结果的详细信息

  <Expandable title="properties">
    <ResponseField name="webSearchUrl" type="string">
      视频的搜索URL
    </ResponseField>

    <ResponseField name="name" type="string">
      视频的名称
    </ResponseField>

    <ResponseField name="description" type="string">
      视频的描述
    </ResponseField>

    <ResponseField name="thumbnailUrl" type="string">
      视频的缩略图URL
    </ResponseField>

    <ResponseField name="publisher" type="List<Publisher>">
      视频的发布者列表
    </ResponseField>

    <ResponseField name="creator" type="Creator">
      视频的创建者信息
    </ResponseField>

    <ResponseField name="contentUrl" type="string">
      视频的内容URL
    </ResponseField>

    <ResponseField name="hostPageUrl" type="string">
      视频所在页面的URL
    </ResponseField>

    <ResponseField name="encodingFormat" type="string">
      视频的编码格式
    </ResponseField>

    <ResponseField name="hostPageDisplayUrl" type="string">
      视频所在页面的展示URL
    </ResponseField>

    <ResponseField name="width" type="int">
      视频的宽度
    </ResponseField>

    <ResponseField name="height" type="int">
      视频的高度
    </ResponseField>

    <ResponseField name="duration" type="string">
      视频的时长
    </ResponseField>

    <ResponseField name="motionThumbnailUrl" type="string">
      视频的动态缩略图URL
    </ResponseField>

    <ResponseField name="embedHtml" type="string">
      视频的嵌入HTML代码
    </ResponseField>

    <ResponseField name="allowHttpsEmbed" type="boolean">
      是否允许HTTPS嵌入
    </ResponseField>

    <ResponseField name="viewCount" type="int">
      视频的观看次数
    </ResponseField>

    <ResponseField name="thumbnail" type="Thumbnail">
      视频的缩略图信息
    </ResponseField>

    <ResponseField name="allowMobileEmbed" type="boolean">
      是否允许移动端嵌入
    </ResponseField>

    <ResponseField name="isSuperfresh" type="boolean">
      是否为超新鲜内容
    </ResponseField>

    <ResponseField name="datePublished" type="string">
      视频的发布时间
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Creator" type="object">
  创建者信息

  <Expandable title="properties">
    <ResponseField name="name" type="string">
      创建者的名称
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Publisher" type="object">
  发布者信息

  <Expandable title="properties">
    <ResponseField name="name" type="string">
      发布者的名称
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Thumbnail" type="object">
  缩略图信息

  <Expandable title="properties">
    <ResponseField name="height" type="int">
      缩略图的高度
    </ResponseField>

    <ResponseField name="width" type="int">
      缩略图的宽度
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="RankingResponse" type="object">
  排名响应信息

  <Expandable title="properties">
    <ResponseField name="mainline" type="Mainline">
      主线排名信息
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Mainline" type="object">
  主线排名信息

  <Expandable title="properties">
    <ResponseField name="items" type="List<MainlineItem>">
      主线项目列表
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="MainlineItem" type="object">
  主线项目信息

  <Expandable title="properties">
    <ResponseField name="answerType" type="string">
      答案类型
    </ResponseField>

    <ResponseField name="value" type="MainlineItemValue">
      主线项目的值
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="MainlineItemValue" type="object">
  主线项目值信息

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      主线项目值的ID
    </ResponseField>
  </Expandable>
</ResponseField>