Get All Shapes on an Excel Worksheet

This REST API enables retrieval of all shapes on an Excel worksheet.

Security and Authentication

The Aspose.Cells Cloud APIs are secure and require JWT token-based authentication.

REST API

GET https://api.aspose.cloud/v3.0/cells/{name}/worksheets/{sheetName}/shapes

Request Parameters

Parameter Name	Type	Location	Description
name	string	path	The name of the Excel file.
sheetName	string	path	The name of the worksheet.
folder	string	query	The folder that contains the document.
storageName	string	query	The name of the storage service to use.
include	string	query	Set to `details` to return full shape properties; otherwise only the `link` objects are returned.

Optional: folder, storageName, and include can be omitted when the file resides in the root storage.

You can use the cURL command‑line tool to access Aspose.Cells web services. The example below demonstrates a request that includes the optional query parameters.

Request

curl -v "https://api.aspose.cloud/v3.0/cells/Book1.xlsx/worksheets/Sheet1/shapes?folder=Samples&storageName=MyStorage" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer <jwt token>"

Response

{
  "Shapes": {
    "ShapeList": [
      {
        "link": {
          "Href": "/0",
          "Rel": "self",
          "Type": null,
          "Title": null
        }
      },
      {
        "link": {
          "Href": "/1",
          "Rel": "self",
          "Type": null,
          "Title": null
        }
      },
      {
        "link": {
          "Href": "/2",
          "Rel": "self",
          "Type": null,
          "Title": null
        }
      },
      {
        "link": {
          "Href": "/3",
          "Rel": "self",
          "Type": null,
          "Title": null
        }
      }
    ],
    "link": {
      "Href": "https://api.aspose.cloud/v3.0/cells/Book1.xlsx/worksheets/Sheet1/shapes",
      "Rel": "self",
      "Type": null,
      "Title": null
    }
  },
  "Code": 200,
  "Status": "OK"
}

Response Fields

The Shapes object contains a list of Shape items. Each shape includes the following properties (when the include=details flag is used; otherwise only the link object is returned).

Property	Type	Description
Name	string	The name assigned to the shape (e.g., “Chart 1”).
Type	string	The shape type (e.g., `Chart`, `Picture`, `TextBox`).
Top	number	The distance, in points, from the top edge of the worksheet to the shape.
Left	number	The distance, in points, from the left edge of the worksheet to the shape.
Width	number	The width of the shape in points.
Height	number	The height of the shape in points.
Link	object	Hyperlink information (`Href`, `Rel`, `Type`, `Title`).

Error Handling

HTTP Status	Description	Sample Error Body
400	Bad request – malformed parameters.	`{ "Code": 400, "Message": "Invalid parameter value." }`
401	Unauthorized – missing or invalid token.	`{ "Code": 401, "Message": "Access token is missing or invalid." }`
404	Not found – workbook or worksheet does not exist.	`{ "Code": 404, "Message": "File or worksheet not found." }`
500	Internal server error – unexpected condition.	`{ "Code": 500, "Message": "An unexpected error occurred." }`

A successful request returns HTTP 200 with a Shapes object containing the list of shapes, as illustrated in the response example above.

The API enforces a limit of 150 requests per minute per JWT token. Exceeding this limit returns HTTP 429 with a Retry-After header indicating when to retry.

Cloud SDK Family

Using an SDK is the best way to speed up development. An SDK handles low‑level details and lets you focus on your project tasks. Please check out the GitHub repository for a complete list of Aspose.Cells Cloud SDKs.

The following code examples demonstrate how to make calls to Aspose.Cells web services using various SDKs:

Get a shape by index on an Excel worksheet