Tutorial: How to Get Document Information with GroupDocs.Annotation Cloud API
Learning Objectives
In this tutorial, you’ll learn how to:
- Retrieve detailed information about a document using the GroupDocs.Annotation Cloud API
- Extract metadata such as file format, size, and modification date
- Get page dimensions for accurate annotation placement
- Implement this functionality in multiple programming languages
Prerequisites
Before starting this tutorial, make sure you have:
- A GroupDocs.Annotation Cloud account (if you don’t have one, get a free trial here
- Your API keys (AppSID and AppKey) from the dashboard
- A document uploaded to your storage (or you can use the sample documents provided by the API)
- Basic knowledge of REST APIs
- A development environment set up with your preferred language
Practical Scenario
When building a document annotation application, you often need to know details about the documents before allowing users to add annotations. For example, you need to know the page dimensions to correctly position annotations, or you might want to show document metadata to users. This tutorial shows you how to retrieve this critical information.
Step-by-Step Guide
1. Understanding the API Endpoint
GroupDocs.Annotation Cloud API provides a dedicated endpoint to retrieve document information:
POST https://api.groupdocs.cloud/v2.0/annotation/info
This endpoint requires you to specify the document path in the request body.
2. Making the API Request with cURL
Let’s try calling the API using cURL to understand the request and response structure:
curl -v "https://api.groupdocs.cloud/v2.0/annotation/info" \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d "{ 'FilePath': 'annotationdocs/one-page.docx'}"
Replace YOUR_ACCESS_TOKEN
with your actual JWT token obtained from your AppSID and AppKey.
3. Understanding the Response
The API returns a JSON response containing comprehensive information about the document, including:
- Basic file properties (name, path, extension, format)
- File size and modification date
- Page information including dimensions (width and height)
Here’s what a typical response looks like:
{
"name": "one-page.docx",
"path": "annotationdocs/one-page.docx",
"extension": ".docx",
"fileFormat": "Microsoft Word Open XML format",
"size": 16646,
"dateModified": "2021-02-05T05:17:10Z",
"pages": [
{
"number": 1,
"width": 595,
"height": 841
}
]
}
4. Why Page Dimensions Matter
The page dimensions (width and height) are particularly important for annotation. They allow you to:
- Calculate relative positions for annotations
- Ensure annotations appear in the correct location across different devices
- Scale annotations properly when the document is rendered at different sizes
5. Implementing in Different Programming Languages
Let’s implement this API call in various programming languages:
C# Implementation
// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud
var configuration = new Configuration(MyAppSid, MyAppKey);
// Create API instance
var apiInstance = new InfoApi(configuration);
// Create request object
var request = new GetInfoRequest
{
FilePath = "annotationdocs/one-page.docx"
};
// Call API method
var response = apiInstance.GetInfo(request);
// Process the document information
Console.WriteLine($"File: {response.Name}");
Console.WriteLine($"Format: {response.FileFormat}");
Console.WriteLine($"Size: {response.Size} bytes");
Console.WriteLine($"Modified: {response.DateModified}");
// Process page information
foreach (var page in response.Pages)
{
Console.WriteLine($"Page {page.Number}: Width={page.Width}, Height={page.Height}");
}
Python Implementation
# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples
import groupdocs_annotation_cloud
app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud
app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud
# Create API instance
info_api = groupdocs_annotation_cloud.InfoApi.from_keys(app_sid, app_key)
# Create request object
request = groupdocs_annotation_cloud.GetInfoRequest("annotationdocs/one-page.docx")
# Call API method
result = info_api.get_info(request)
# Process the document information
print(f"File: {result.name}")
print(f"Format: {result.file_format}")
print(f"Size: {result.size} bytes")
print(f"Modified: {result.date_modified}")
# Process page information
for page in result.pages:
print(f"Page {page.number}: Width={page.width}, Height={page.height}")
Node.js Implementation
// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-node-samples
global.annotation_cloud = require("groupdocs-annotation-cloud");
global.appSid = "XXXX-XXXX-XXXX-XXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud
global.appKey = "XXXXXXXXXXXXXXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud
// Create API instance
global.infoApi = annotation_cloud.InfoApi.fromKeys(appSid, appKey);
// Prepare request object
let request = new annotation_cloud.GetInfoRequest();
request.filePath = "annotationdocs/one-page.docx";
// Call API method
let result = await infoApi.getInfo(request);
// Process the document information
console.log(`File: ${result.name}`);
console.log(`Format: ${result.fileFormat}`);
console.log(`Size: ${result.size} bytes`);
console.log(`Modified: ${result.dateModified}`);
// Process page information
result.pages.forEach(page => {
console.log(`Page ${page.number}: Width=${page.width}, Height=${page.height}`);
});
Try It Yourself
Now that you’ve seen the examples, it’s time to try implementing this in your own application:
- Get your API credentials from the dashboard
- Upload a document to your storage or use a sample document
- Choose your preferred programming language
- Copy the appropriate code example above
- Modify it with your credentials and document path
- Run the code and observe the results
Troubleshooting Tips
- File Not Found Error: Make sure the document path is correct and the file exists in your storage.
- Authentication Error: Verify your AppSID and AppKey are correctly set up.
- Unsupported Format: If you get an error related to format, check if the file format is supported by using the Get Supported File Formats API.
- Large Files: If you’re working with large files, you might need to increase timeout values in your API client.
What You’ve Learned
In this tutorial, you have learned:
- How to retrieve document information using the GroupDocs.Annotation Cloud API
- The importance of page dimensions for annotation positioning
- How to extract metadata such as file size and format
- How to implement this functionality in C#, Python, and Node.js
Further Practice
To solidify your understanding:
- Try retrieving information for different file types (PDF, images, Excel files)
- Create a function that validates if a document is suitable for annotation based on its properties
- Build a simple UI that displays document metadata and previews page dimensions