Website Snapshot - API Documents - GuGuData | Production-Ready APIs Built for Developers

Webpage Screenshot Capture
Capture a screenshot of a target webpage and return the generated image resource.

Method: POST
Path: /v1/websitetools/url2snapshot
Demo: https://api.gugudata.io/v1/websitetools/url2snapshot/demo
OpenAPI: https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json

Request Parameters:

appkey (string, required): Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.

url (string, required): Target webpage URL.

responseFormat (string, optional): Requested output format for the generated response.

fullPage (boolean, optional): Whether the capture should include the full page height instead of the visible viewport only.

width (integer, optional): Output width in pixels.

height (integer, optional): Output height in pixels.

deviceScaleFactor (integer, optional): Device scale factor used during page rendering.

userAgent (string, optional): Optional user agent string used for page rendering.

isMobile (boolean, optional): Whether the renderer should emulate a mobile device viewport.

Response Fields:

dataStatus (object, required): Response metadata returned by the current v1 contract.

dataStatus.requestParameter (string, required): Normalized request parameters echoed by the service. Sensitive credentials are omitted when available.

dataStatus.statusCode (integer, required): Application-level status code returned by the current v1 contract. Successful demo responses currently return 200.

dataStatus.status (string, required): Application-level status enum. Successful demo responses currently return SUCCESS.

dataStatus.statusDescription (string, required): Application-level status message returned by the current v1 contract.

dataStatus.responseDateTime (string, required): Response timestamp returned by the current service contract.

dataStatus.dataTotalCount (integer, required): Total number of records that match the request.

data (object, required): Primary response payload returned by the endpoint.

data.image (string, required): Base64 string or CDN URL of the screenshot

data.content (string, required): HTML content returned by Cloudflare snapshot

HTTP Status Codes:

200: Request processed successfully. Some endpoints expose a separate application-level status field in the response body, such as dataStatus.statusCode.

400: Invalid request parameters or request format. Check required fields, data types, and request body format.

401: Missing or unknown application key. Provide a valid appkey with the request.

403: The application key is recognized but access is not allowed. The key may be expired, inactive, or not permitted for the requested API.

429: Request rate or trial usage limit exceeded. Reduce concurrency or retry after the limit window resets.

500: Internal service error. Retry later or contact support if the error persists.

503: Upstream service unavailable. Retry later; the requested upstream dependency is temporarily unavailable.

Business Status Codes:

200 Normal return: Snapshot successfully generated and returned

400 Parameter error: Invalid or missing required parameters (e.g., url)

429 Request frequency limited: Cannot exceed 100 requests per second

403 Account in arrears: Payment required to continue using the service

402 APPKEY error: Please check whether the APPKEY passed is obtained from the developer center

500 API response error: Internal server error during snapshot capture

503 Service unavailable: External service temporarily unavailable

Key Features:

Capture full-page or viewport screenshots from any public URL.

Optional CDN hosting on Cloudflare R2 with secure HTTPS URLs.

Customizable viewport size, scale factor, and user agent.

Supports desktop and mobile rendering modes.

Best-effort capture using Cloudflare browser rendering.

Automatic request parameter logging for easier debugging.

Full TLS support and Apple ATS compliant.

Details:
https://gugudata.io/details/url2snapshot

Request

Query Params

Header Params

Body Params application/json

Example

{
    "url": "https://www.gugudata.io",
    "responseFormat": "base64",
    "fullPage": true,
    "width": 1920,
    "height": 1080,
    "deviceScaleFactor": 1,
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36",
    "isMobile": false
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200成功

application/json

Bodyapplication/json

Example

{
  "dataStatus": {
    "statusCode": 0,
    "status": "string",
    "statusDescription": "string",
    "responseDateTime": "string",
    "dataTotalCount": 0,
    "requestParameter": "string"
  },
  "data": {
    "image": "string",
    "content": "string"
  },
  "DataStatus": {
    "StatusCode": 100,
    "StatusDescription": "OK",
    "ResponseDateTime": "2026-01-01 00:00:00",
    "DataTotalCount": 1
  }
}