Overview

This endpoint allows you to compare two screenshots and allows you to visually spot the difference between the two.

Compare two screenshots

You can compare two screenshots asynchronously by creating a job.

POST /screenshot/diff

Request

{
  "baseImage": {
    "fileObject": "hyder/1.png"
  },
  "comparisonImage": {
    "fileObject": "hyder/2.png"
  }
}

Response: On Success

The response will be a JSON object acknowledging your request was received and queued.

Condition: If everything is OK

Code: 202

Example:

{
  "id": "536ca23e-10b3-4eb4-9677-24e0b556a069",
  "createdAt": "2023-11-27T16:07:26.459Z",
  "updatedAt": "2023-11-27T16:07:26.459Z",
  "message": "Your Diff Image request has been successfully queued."
}

Response: On Error(s)

Code: 500

Content Example:

{
  "status": "failed",
  "message": "The two images are not of the same size",
  "createdAt": "2023-06-20T11:55:39.594Z",
  "updatedAt": "2023-06-20T11:57:23.033Z"
}

Code: 422

Content Example:

{
  "errors": [
    "The responseType does not support this value"
  ]
}

Supported Attributes

List of optional attributes

Option	Default value (if not specified)	description
cloud.upload	s3	Save images to Amazon S3 or Cloudflare R2 bucket
cloud.fileObject	e.g /path/acme/light-arr.png	Sets the path including file name of your screenshot

Check progress of screenshot comparison

GET /screenshot/diff/:id

{
  "status": "success",
  "pixelDifference": {
    "count": 1670,
    "percentage": 0.35
  },
  "url": "https://launchbrightlyf137-prod.s3.us-east-1.amazonaws.com/diff/hyder_1_hyder/2.png.png"
}

Bulk Screenshot comparison

If you would like to compare more than just a pair of screenshots at a time. You can use the following endpoint:

POST /screenshot/diff/bulk

Request:

[
  {
    "baseImage": {
      "fileObject": "hyder/1xx.png"
    },
    "comparisonImage": {
      "fileObject": "hyder/2.png"
    }
  },
  {
    "baseImage": {
      "fileObject": "hyder/1.png"
    },
    "comparisonImage": {
      "fileObject": "hyder/2.png"
    }
  }
]

Response:

{
  "id": "7c75dd41-12cb-429e-b11e-a2c98844b654",
  "message": "Your Diff Screenshot request has been successfully queued.",
  "data": [
    {
      "id": "d6efdfa1-eb32-48e3-b24e-611a893f2781",
      "createdAt": "2024-02-16T16:50:28.308Z",
      "updatedAt": "2024-02-16T16:50:28.308Z"
    },
    {
      "id": "2f108e61-cd46-4e3e-9a5d-deab7f6a63e8",
      "createdAt": "2024-02-16T16:50:30.103Z",
      "updatedAt": "2024-02-16T16:50:30.103Z"
    }
  ]
}

HTTP Status codes:

HTTP Code	Description
202	The job was successfully created.
403	Validation-related errors
500	Any unhandled crash

---

Check the progress of the bulk transload operation

GET /screenshot/diff/bulk/:id

Response:

{
  "summary": {
    "total": 2,
    "success": 1,
    "pending": 0,
    "failed": 1
  },
  "data": [
    {
      "id": "2f108e61-cd46-4e3e-9a5d-deab7f6a63e8",
      "jobId": "156b6acd-0562-41e1-8160-f45c78e8dd51",
      "status": "success",
      "baseImage": {
        "fileObject": "hyder/1.png"
      },
      "comparisonImage": {
        "fileObject": "hyder/2.png"
      },
      "url": "https://launchbrightlyf9ff5e67329842e1a3a8fc00d5a7569c145137-prod.s3.us-east-1.amazonaws.com/diff/hyder_1_hyder_2.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20240216%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240216T165142Z&X-Amz-Expires=3600&X-Amz-Signature=603280608b8c9a758700a662cb9bfde6965a9a5f1feb5c170ac66de5bb7eddee&X-Amz-SignedHeaders=host&x-id=GetObject",
      "pixelDifference": {
        "count": 1670,
        "percentage": 0.34900439703743336
      },
      "createdAt": "2024-02-16T16:50:30.103Z",
      "updatedAt": "2024-02-16T16:50:34.674Z"
    },
    {
      "id": "d6efdfa1-eb32-48e3-b24e-611a893f2781",
      "jobId": "156b6acd-0562-41e1-8160-f45c78e8dd51",
      "status": "failed",
      "baseImage": {
        "fileObject": "hyder/1xx.png"
      },
      "comparisonImage": {
        "fileObject": "hyder/2.png"
      },
      "error": "The specified key does not exist.",
      "createdAt": "2024-02-16T16:50:28.308Z",
      "updatedAt": "2024-02-16T16:50:33.654Z"
    }
  ]
}

Percentage Field

The percentage field represents a float value between 0 and 100, indicating the proportion of pixels changed relative to the whole image.

Calculation Example:

Consider an image with dimensions 1200px by 1200px. If there is a difference of 4958 pixels, the percentage difference is calculated as follows:

Percentage difference = (4958 / (1200 * 1200)) * 100 = 0.344%

In this example, the percentage difference of 0.344% reflects the pixel difference in relation to the total number of pixels in the image.

Job Statuses:

Status	Description
completed	The screenshot diff job was successful.
failed	An error occurred. See error field for details.
pending	The screenshot diff job has not yet been processed.

HTTP Status codes:

HTTP Code	Description
200	On success
500	Any unhandled crash

Limitation of Bulk endpoints

The bulk endpoints allow you to submit up to 100 screenshot capture jobs in a single request. If you have more than 100 jobs, you will need to send multiple API requests.

To check the progress of multiple job IDs, separate them with commas, as shown below:

GET /screenshot/diff/bulk/:jobId1,: jobId2,: jobId3