• API 功能

    • 支持任意网页 URL 高质量截图,包括动态内容和 JavaScript 渲染页面;
    • 支持全页面截图和可视区域截图两种模式;
    • 可自定义截图尺寸、设备像素比等参数;
    • 支持桌面端和移动端设备模拟;
    • 同时返回截图图片和网页文本内容;
    • 支持 base64 编码和 CDN URL 两种返回格式;
    • 全接口支持 HTTPS(TLS v1.0 / v1.1 / v1.2 / v1.3);
    • 全面兼容 Apple ATS;
    • 全国多节点 CDN 部署;
    • 接口极速响应,多台服务器构建 API 接口负载均衡。
    • 接口调用状态与状态监控
  • API 文档

    接口地址: https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}

    返回格式: application/json; charset=utf-8

    请求方式: POST

    请求协议: HTTPS

    请求示例: https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}

    数据预览: https://www.gugudata.com/preview/url2snapshot

    接口测试:  https://api.gugudata.com/websitetools/url2snapshot/demo

    OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json

    请求参数(POST 请求参数以 application/x-www-form-urlencoded 格式、文件流以 formdata 格式传递,具体可参见下方示例代码)

    参数名 参数类型 是否必须 默认值 备注
    url string https://www.example.com 需要截图的网页 URL 地址,必须是有效的 HTTP 或 HTTPS 链接
    responseformat string base64 返回格式,可选值:base64(返回 base64 编码的图片数据)、url(返回图片 URL 链接)
    fullpage boolean true 是否截取完整页面,true 为全页面截图,false 为可视区域截图
    width integer 1920 截图宽度,单位像素,范围:320-3840
    height integer 1080 截图高度,单位像素,范围:240-2160
    devicescalefactor number 1 设备像素比,影响截图清晰度,范围:1-3
    useragent string Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 用户代理字符串,用于模拟不同的浏览器
    ismobile boolean false 是否模拟移动设备,true 为移动设备模式,false 为桌面模式

    返回参数

    参数名 参数类型 备注
    DataStatus.StatusCode integer 接口返回状态码,100 为成功
    DataStatus.StatusDescription string 接口返回状态说明
    DataStatus.ResponseDateTime string 接口数据返回时间
    DataStatus.DataTotalCount integer 此条件下的总数据量,一般为1
    Data.Image string 截图图片,当responseFormat为base64时返回base64编码的图片数据,为url时返回图片链接
    Data.Content string 网页文本内容,提取的网页主要文本信息
  • 接口 HTTP 响应标准状态码

    状态码 状态码解释 备注
    200 接口正常响应 请求成功,业务状态请结合响应体中的自定义业务码判断。
    400 请求参数错误 请求参数缺失、格式错误或参数组合不合法。
    401 鉴权失败 缺少 appkey 或 appkey 无效。
    403 无权限访问 订单到期、权限不足或接口额度不可用。
    404 资源不存在 请求路径不存在。
    405 请求方法不允许 当前路径不支持该 HTTP 方法。
    415 请求内容类型不支持 上传或请求体的内容类型不符合接口要求。
    429 请求频率受限 一般建议同一个 IP 每秒请求不超过 5 次 (QPS<=5),我们不限制同一个 key 的请求总次数,但当单位时间内同一个 IP 请求次数过多,或 AI CDN 判定为恶意抓取数据、流量攻击等异常时,CDN 会返回此状态码,请适当降低请求频率。如有特殊大并发请求场景需求,可联系我们添加白名单处理。
    500 服务内部错误 服务端处理异常,请稍后重试。
    502 上游依赖错误 上游依赖服务不可用或返回异常。
  • 接口自定义状态码

    自定义状态码 自定义状态码解释 备注
    100 正常返回
    101 参数错误 URL 参数为空或格式错误
    102 请求频率受限 每秒请求不能超过 50 次
    103 账号欠费
    104 APPKEY 错误 请检查传递的 APPKEY 是否为开发者中心获取到的值
    110 网页截图失败 网页无法访问、加载超时或截图服务异常
    111 图片上传失败 当responseFormat为url时,图片上传到CDN失败
  • 请求示例代码
    curl --location --request POST 'https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'url=https://www.example.com' \
    --data-urlencode 'responseFormat=base64' \
    --data-urlencode 'fullPage=true' \
    --data-urlencode 'width=1920' \
    --data-urlencode 'height=1080' \
    --data-urlencode 'deviceScaleFactor=1' \
    --data-urlencode 'userAgent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36' \
    --data-urlencode 'isMobile=false'
    #include <curl/curl.h>
    
    int main(void) {
      CURL *curl = curl_easy_init();
      if (curl) {
        curl_easy_setopt(curl, CURLOPT_URL, "https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}");
        curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
        curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Content-Type: application/x-www-form-urlencoded");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "url=https%3a%2f%2fwww.example.com&responseFormat=base64&fullPage=true&width=1920&height=1080&deviceScaleFactor=1&userAgent=Mozilla%2f5.0+(Windows+NT+10.0%3b+Win64%3b+x64)+AppleWebKit%2f537.36&isMobile=false");
        CURLcode res = curl_easy_perform(curl);
        (void)res;
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
      }
      return 0;
    }
    
    using System;
    using System.Collections.Generic;
    using System.IO;
    using System.Net.Http;
    
    var client = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Post, "https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}");
    request.Content = new FormUrlEncodedContent(new Dictionary<string, string>
    {
        { "url", "https://www.example.com" },
        { "responseFormat", "base64" },
        { "fullPage", "true" },
        { "width", "1920" },
        { "height", "1080" },
        { "deviceScaleFactor", "1" },
        { "userAgent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" },
        { "isMobile", "false" }
    });
    var response = client.SendAsync(request).Result;
    Console.WriteLine(response.Content.ReadAsStringAsync().Result);
    
    package main
    
    import (
      "strings"
      "fmt"
      "io"
      "net/http"
    )
    
    func main() {
      url := "https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}"
      payload := strings.NewReader("url=https%3a%2f%2fwww.example.com&responseFormat=base64&fullPage=true&width=1920&height=1080&deviceScaleFactor=1&userAgent=Mozilla%2f5.0+(Windows+NT+10.0%3b+Win64%3b+x64)+AppleWebKit%2f537.36&isMobile=false")
      req, err := http.NewRequest("POST", url, payload)
      if err != nil {
        fmt.Println(err)
        return
      }
      req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
      res, err := http.DefaultClient.Do(req)
      if err != nil {
        fmt.Println(err)
        return
      }
      defer res.Body.Close()
      body, err := io.ReadAll(res.Body)
      if err != nil {
        fmt.Println(err)
        return
      }
      fmt.Println(string(body))
    }
    
    OkHttpClient client = new OkHttpClient().newBuilder().build();
    MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
    RequestBody body = RequestBody.create(mediaType, "url=https%3a%2f%2fwww.example.com&responseFormat=base64&fullPage=true&width=1920&height=1080&deviceScaleFactor=1&userAgent=Mozilla%2f5.0+(Windows+NT+10.0%3b+Win64%3b+x64)+AppleWebKit%2f537.36&isMobile=false");
    Request request = new Request.Builder()
      .url("https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}")
      .method("POST", body)
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
    
    $.ajax({
      url: "https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}",
      method: "POST",
      data: { "url": "https://www.example.com", "responseFormat": "base64", "fullPage": "true", "width": "1920", "height": "1080", "deviceScaleFactor": "1", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "isMobile": "false" },
    }).done(function (response) {
      console.log(response);
    });
    
    const response = await fetch("https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({ "url": "https://www.example.com", "responseFormat": "base64", "fullPage": "true", "width": "1920", "height": "1080", "deviceScaleFactor": "1", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "isMobile": "false" })
    });
    console.log(await response.text());
    
    const response = await fetch("https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({ "url": "https://www.example.com", "responseFormat": "base64", "fullPage": "true", "width": "1920", "height": "1080", "deviceScaleFactor": "1", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "isMobile": "false" })
    });
    console.log(await response.text());
    
    #import <Foundation/Foundation.h>
    
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}"]];
    [request setHTTPMethod:@"POST"];
    NSString *body = @"url=https%3a%2f%2fwww.example.com&responseFormat=base64&fullPage=true&width=1920&height=1080&deviceScaleFactor=1&userAgent=Mozilla%2f5.0+(Windows+NT+10.0%3b+Win64%3b+x64)+AppleWebKit%2f537.36&isMobile=false";
    [request setValue:@"application/x-www-form-urlencoded" forHTTPHeaderField:@"Content-Type"];
    [request setHTTPBody:[body dataUsingEncoding:NSUTF8StringEncoding]];
    NSURLSessionDataTask *task = [[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
      if (error) {
        NSLog(@"%@", error);
        return;
      }
      NSLog(@"%@", [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]);
    }];
    [task resume];
    
    <?php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_FOLLOWLOCATION => true,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_POSTFIELDS => "url=https%3a%2f%2fwww.example.com&responseFormat=base64&fullPage=true&width=1920&height=1080&deviceScaleFactor=1&userAgent=Mozilla%2f5.0+(Windows+NT+10.0%3b+Win64%3b+x64)+AppleWebKit%2f537.36&isMobile=false",
      CURLOPT_HTTPHEADER => array("Content-Type: application/x-www-form-urlencoded"),
    ));
    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
    
    import requests
    
    url = "https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}"
    payload = { "url": "https://www.example.com", "responseFormat": "base64", "fullPage": "true", "width": "1920", "height": "1080", "deviceScaleFactor": "1", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "isMobile": "false" }
    response = requests.post(url, data=payload)
    print(response.text)
    
    require "uri"
    require "net/http"
    
    url = URI("https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}")
    https = Net::HTTP.new(url.host, url.port)
    https.use_ssl = true
    request = Net::HTTP::Post.new(url)
    request["Content-Type"] = "application/x-www-form-urlencoded"
    request.body = "url=https%3a%2f%2fwww.example.com&responseFormat=base64&fullPage=true&width=1920&height=1080&deviceScaleFactor=1&userAgent=Mozilla%2f5.0+(Windows+NT+10.0%3b+Win64%3b+x64)+AppleWebKit%2f537.36&isMobile=false"
    response = https.request(request)
    puts response.read_body
    
    import Foundation
    
    let semaphore = DispatchSemaphore(value: 0)
    var request = URLRequest(url: URL(string: "https://api.gugudata.com/websitetools/url2snapshot?appkey={{appkey}}")!, timeoutInterval: .infinity)
    request.httpMethod = "POST"
    request.addValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
    request.httpBody = "url=https%3a%2f%2fwww.example.com&responseFormat=base64&fullPage=true&width=1920&height=1080&deviceScaleFactor=1&userAgent=Mozilla%2f5.0+(Windows+NT+10.0%3b+Win64%3b+x64)+AppleWebKit%2f537.36&isMobile=false".data(using: .utf8)
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
      defer { semaphore.signal() }
      guard let data = data else {
        print(String(describing: error))
        return
      }
      print(String(data: data, encoding: .utf8)!)
    }
    task.resume()
    semaphore.wait()
    
  • 常见问题 Q&A

    • Q: 数据请求有缓存吗?

      A: 我们为所有数据请求提供实时响应。对于定期更新的数据,我们在其更新周期内实施缓存策略,以优化性能。

    • Q: 如何保证请求时 key 的安全性?

      A: 我们建议将对 API 的请求操作放置在您的应用程序后端。这样,前端请求只与您的后端服务交互,确保了更高的安全性和易于维护的架构。

    • Q: 接口可以用于哪些开发语言?

      A: 我们的接口支持所有能进行网络请求的开发语言,便于在各类项目中快速整合数据。

    • Q: 接口的性能可以保证吗?

      A: 我们的接口后台使用与商业级项目相同的架构,保证了稳定且高效的性能。您可以通过访问测试接口了解更多性能信息。

  • 服务协议以及服务免责声明

    用户应当充分阅读 服务协议 以及 服务免责声明 ,用户购买与使用咕咕数据 API 服务亦视为接受本协议。

  • 技术支持

    • 技术支持邮箱: support@gugudata.com
    • 微信客服: 客服链接

业务相关接口推荐

URL 生成网站截图
  • 高效生成网页截图
  • 生成网页截图 / 图片输出
  • 999元/年限时折扣 499元/年
查看详情 被调用于 7 秒前
50% 折扣
语义化获取站点 JSON 结构内容
  • 语义智能提取任意网页内容结构化 JSON 数据
  • AI 智能提取 / 结构化数据 / 网页解析
  • 3999元/年限时折扣 1999元/年
查看详情 被调用于 3 秒前
50% 折扣
网页 URL 链接提取
  • 提取指定网页中的所有链接地址
  • 网页链接提取 / 网页解析 / 链接收集
  • 1999元/年限时折扣 999元/年
查看详情 被调用于 7 秒前
50% 折扣
网页 URL 转 Markdown
  • 将任意网页 URL 转换为 Markdown 格式文本
  • 网页内容提取 / 网页解析
  • 1999元/年限时折扣 999元/年
查看详情 被调用于 1 秒前
50% 折扣