Etsy · Schema

ListingImage

Reference urls and metadata for an image associated with a specific listing. The `url_fullxfull` parameter contains the URL for full-sized binary image file.

MarketplaceEcommerceHandmadeListingsOrdersPaymentsReviewsShippingTaxonomyOAuth2

Properties

Name Type Description
listing_id integer The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
listing_image_id integer The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
hex_code string The webhex string for the image's average color, in webhex notation.
red integer The numeric red value equal to the image's average red value, from 0-255 (RGB color).
green integer The numeric red value equal to the image's average red value, from 0-255 (RGB color).
blue integer The numeric red value equal to the image's average red value, from 0-255 (RGB color).
hue integer The numeric hue equal to the image's average hue, from 0-360 (HSV color).
saturation integer The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).
brightness integer The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).
is_black_and_white boolean When true, the image is in black & white.
creation_tsz integer The listing image's creation time, in epoch seconds.
created_timestamp integer The listing image's creation time, in epoch seconds.
rank integer The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.
url_75x75 string The url string for a 75x75 pixel thumbnail of the image.
url_170x135 string The url string for a 170x135 pixel thumbnail of the image.
url_570xN string The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.
url_fullxfull string The url string for the full-size image, up to 3000 pixels in each dimension.
full_height integer The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.
full_width integer The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.
alt_text string Alt text for the listing image. Max length 500 characters.
View JSON Schema on GitHub

JSON Schema

open-api-v3-listing-image-schema.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ListingImage",
  "description": "Reference urls and metadata for an image associated with a specific listing. The `url_fullxfull` parameter contains the URL for full-sized binary image file.",
  "$id": "https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/json-schema/open-api-v3-listing-image-schema.json",
  "type": "object",
  "properties": {
    "listing_id": {
      "type": "integer",
      "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.",
      "format": "int64",
      "minimum": 1,
      "example": 123456789
    },
    "listing_image_id": {
      "type": "integer",
      "description": "The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.",
      "format": "int64",
      "minimum": 1,
      "example": 1
    },
    "hex_code": {
      "type": "string",
      "description": "The webhex string for the image's average color, in webhex notation.",
      "nullable": true,
      "example": "example string"
    },
    "red": {
      "type": "integer",
      "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "green": {
      "type": "integer",
      "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "blue": {
      "type": "integer",
      "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "hue": {
      "type": "integer",
      "description": "The numeric hue equal to the image's average hue, from 0-360 (HSV color).",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "saturation": {
      "type": "integer",
      "description": "The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "brightness": {
      "type": "integer",
      "description": "The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "is_black_and_white": {
      "type": "boolean",
      "description": "When true, the image is in black & white.",
      "nullable": true,
      "example": true
    },
    "creation_tsz": {
      "type": "integer",
      "description": "The listing image's creation time, in epoch seconds.",
      "minimum": 0,
      "example": 1
    },
    "created_timestamp": {
      "type": "integer",
      "description": "The listing image's creation time, in epoch seconds.",
      "minimum": 0,
      "example": 1758153645
    },
    "rank": {
      "type": "integer",
      "description": "The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.",
      "minimum": 0,
      "example": 1
    },
    "url_75x75": {
      "type": "string",
      "description": "The url string for a 75x75 pixel thumbnail of the image.",
      "example": "https://www.etsy.com/listing/123456789"
    },
    "url_170x135": {
      "type": "string",
      "description": "The url string for a 170x135 pixel thumbnail of the image.",
      "example": "https://www.etsy.com/listing/123456789"
    },
    "url_570xN": {
      "type": "string",
      "description": "The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.",
      "example": "https://www.etsy.com/listing/123456789"
    },
    "url_fullxfull": {
      "type": "string",
      "description": "The url string for the full-size image, up to 3000 pixels in each dimension.",
      "example": "https://www.etsy.com/listing/123456789"
    },
    "full_height": {
      "type": "integer",
      "description": "The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "full_width": {
      "type": "integer",
      "description": "The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "alt_text": {
      "type": "string",
      "description": "Alt text for the listing image. Max length 500 characters.",
      "nullable": true,
      "example": "example string"
    }
  }
}