Tutorial: How to Add Multiple Annotations

Learning Objectives

In this tutorial, you’ll learn how to:

  • Add multiple annotation types to a document in a single API call
  • Configure different properties for each annotation type
  • Optimize annotation processes for multi-user scenarios
  • Implement advanced annotation patterns in various programming languages

What are Multiple Annotations?

Multiple annotations allow you to add different types of annotations (arrows, areas, text highlights, etc.) to a document in a single API request. This improves performance and creates a more efficient workflow when annotating documents collaboratively.

Prerequisites

Before starting this tutorial, ensure you have:

  1. A GroupDocs.Annotation Cloud account (or get a free trial
  2. Your Client ID and Client Secret credentials
  3. A development environment for your preferred language
  4. A sample multi-page document uploaded to your GroupDocs.Annotation Cloud storage

Implementation Steps

Let’s walk through the process of adding multiple annotations to a document:

1. Authentication

First, authenticate with the GroupDocs.Annotation Cloud API:

// Get JWT token
curl -v "https://api.groupdocs.cloud/connect/token" \
-X POST \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json"

Save the received JWT token for subsequent API calls.

2. Define Multiple Annotation Properties

For multiple annotations, you’ll need to:

  • Create an array of annotation objects
  • Define properties for each annotation type
  • Specify page numbers for each annotation (can be different pages)

3. Add Multiple Annotations

Use the POST /annotation/add endpoint to add multiple annotations:

curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d "{
  'FileInfo': {
    'FilePath': 'multi-page-document.docx'
  },
  'OutputPath': 'output/annotated-document.docx',
  'Annotations': [
    {
      'Type': 'Area',
      'Text': 'This is area annotation',
      'CreatorName': 'John Doe',
      'Box': {
        'X': 100,
        'Y': 100,
        'Width': 100,
        'Height': 100
      },
      'PageNumber': 0,
      'PenColor': 65535,
      'PenWidth': 3
    },
    {
      'Type': 'Point',
      'CreatorName': 'John Doe',
      'Box': {
        'X': 375,
        'Y': 59,
        'Width': 88,
        'Height': 37
      },
      'PageNumber': 2,
      'AnnotationPosition': {
        'X': 852,
        'Y': 59
      }
    },
    {
      'Type': 'TextHighlight',
      'Text': 'Text to highlight',
      'CreatorName': 'John Doe',
      'Points': [
        {
          'X': 80,
          'Y': 730
        },
        {
          'X': 240,
          'Y': 730
        },
        {
          'X': 80,
          'Y': 650
        },
        {
          'X': 240,
          'Y': 650
        }
      ],
      'PageNumber': 1,
      'BackgroundColor': 16711680
    }
  ]
}"

4. Download the Annotated Document

After successful annotation, download your annotated document using the File API.

Try It Yourself

Now, try implementing multiple annotations in your preferred programming language.

C# Example

// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples
string MyAppKey = "YOUR_APP_KEY"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud
string MyAppSid = "YOUR_APP_SID";

var configuration = new Configuration(MyAppSid, MyAppKey);
var apiInstance = new AnnotateApi(configuration);

var fileInfo = new FileInfo { FilePath = "multi-page-document.docx" };

// Create multiple annotation objects
AnnotationInfo[] annotations =
{
    // Area annotation on page 0
    new AnnotationInfo
    {
        AnnotationPosition = new Point { X = 1, Y = 1 },
        Box = new Rectangle { X = 100, Y = 100, Width = 100, Height = 100 },
        PageNumber = 0,
        BackgroundColor = 65535,
        PenColor = 65535,
        PenStyle = AnnotationInfo.PenStyleEnum.Solid,
        PenWidth = 3,
        Type = AnnotationInfo.TypeEnum.Area,
        Text = "This is area annotation",
        CreatorName = "John Doe",
        CreatedOn = DateTime.Now
    },
    
    // Point annotation on page 2
    new AnnotationInfo
    {
        AnnotationPosition = new Point { X = 852, Y = 59.388262910798119 },
        Box = new Rectangle { X = 375.89276123046875, Y = 59.388263702392578, Width = 88.7330551147461, Height = 37.7290153503418 },
        PageNumber = 2,
        Type = AnnotationInfo.TypeEnum.Point,
        CreatorName = "John Doe",
        CreatedOn = DateTime.Now
    },
    
    // Text highlight annotation on page 1
    new AnnotationInfo
    {
        Points = new List<Point>
        {
            new Point {X = 80, Y = 730}, new Point {X=240, Y=730}, new Point {X=80, Y=650}, new Point {X=240, Y=650}
        },
        BackgroundColor = 16711680, // Yellow
        PageNumber = 1,
        Type = AnnotationInfo.TypeEnum.TextHighlight,
        Text = "Text to highlight",
        CreatorName = "John Doe",
        CreatedOn = DateTime.Now
    }
};

var options = new AnnotateOptions
{
    FileInfo = fileInfo,
    Annotations = annotations.ToList(),
    OutputPath = "output/multi-annotated-document.docx"
};

var link = apiInstance.Annotate(new AnnotateRequest(options));
Console.WriteLine("Multiple Annotations added: " + link.Title);

Java Example

// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples
String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud
String clientSecret = "YOUR_CLIENT_SECRET";

Configuration configuration = new Configuration(clientId, clientSecret);
AnnotateApi apiInstance = new AnnotateApi(configuration);

// Create annotation objects
AnnotationInfo[] annotations = new AnnotationInfo[3];

// Area annotation on page 0
annotations[0] = new AnnotationInfo();
Point pt = new Point();
pt.setX(1.0);
pt.setY(1.0);
annotations[0].setAnnotationPosition(pt);

Rectangle r = new Rectangle();
r.setX(100.0);
r.setY(100.0);
r.setWidth(100.0);
r.setHeight(100.0);

annotations[0].setBox(r);
annotations[0].setPageNumber(0);
annotations[0].setPenColor(65535);
annotations[0].setPenStyle(PenStyleEnum.SOLID);
annotations[0].setPenWidth(3);
annotations[0].setType(TypeEnum.AREA);
annotations[0].setText("This is area annotation");
annotations[0].setCreatorName("John Doe");

// Point annotation on page 2
annotations[1] = new AnnotationInfo();
Point pt2 = new Point();
pt2.setX(852.0);
pt2.setY(59.388262910798119);
annotations[1].setAnnotationPosition(pt2);

Rectangle r2 = new Rectangle();
r2.setX(375.89276123046875);
r2.setY(59.388263702392578);
r2.setWidth(88.7330551147461);
r2.setHeight(37.7290153503418);
annotations[1].setBox(r2);
annotations[1].setPageNumber(2);
annotations[1].setType(TypeEnum.POINT);
annotations[1].setCreatorName("John Doe");

// Text highlight annotation on page 1
annotations[2] = new AnnotationInfo();
Point[] points = new Point[4];
points[0] = new Point();
points[0].setX(80.0);
points[0].setY(730.0);
points[1] = new Point();
points[1].setX(240.0);
points[1].setY(730.0);
points[2] = new Point();
points[2].setX(80.0);
points[2].setY(650.0);
points[3] = new Point();
points[3].setX(240.0);
points[3].setY(650.0);
annotations[2].setPoints(Arrays.asList(points));
annotations[2].setPageNumber(1);
annotations[2].setBackgroundColor(16711680); // Yellow
annotations[2].setType(TypeEnum.TEXTHIGHLIGHT);
annotations[2].setText("Text to highlight");
annotations[2].setCreatorName("John Doe");

// Create request object
FileInfo fileInfo = new FileInfo();
fileInfo.setFilePath("multi-page-document.docx");

AnnotateOptions options = new AnnotateOptions();
options.setFileInfo(fileInfo);
options.setAnnotations(Arrays.asList(annotations));
options.setOutputPath("output/multi-annotated-document.docx");

AnnotateRequest request = new AnnotateRequest(options);

// Execute API method
AnnotationApiLink result = apiInstance.annotate(request);

System.out.println("Multiple Annotations added: " + result.getTitle());

Python Example

# For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples
import groupdocs_annotation_cloud

app_sid = "YOUR_APP_SID"  # Get AppKey and AppSID from https://dashboard.groupdocs.cloud
app_key = "YOUR_APP_KEY"

api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key)

# Create area annotation for page 0
area_annotation = groupdocs_annotation_cloud.AnnotationInfo()
area_annotation.annotation_position = groupdocs_annotation_cloud.Point()
area_annotation.annotation_position.x = 1
area_annotation.annotation_position.y = 1
area_annotation.box = groupdocs_annotation_cloud.Rectangle()
area_annotation.box.x = 100
area_annotation.box.y = 100
area_annotation.box.width = 100
area_annotation.box.height = 100
area_annotation.page_number = 0
area_annotation.pen_color = 65535
area_annotation.pen_style = "Solid"
area_annotation.pen_width = 3
area_annotation.type = "Area"
area_annotation.text = "This is area annotation"
area_annotation.creator_name = "John Doe"

# Create point annotation for page 2
point_annotation = groupdocs_annotation_cloud.AnnotationInfo()
point_annotation.annotation_position = groupdocs_annotation_cloud.Point()
point_annotation.annotation_position.x = 852
point_annotation.annotation_position.y = 59
point_annotation.box = groupdocs_annotation_cloud.Rectangle()
point_annotation.box.x = 375
point_annotation.box.y = 59
point_annotation.box.width = 88
point_annotation.box.height = 37
point_annotation.page_number = 2
point_annotation.type = "Point"
point_annotation.creator_name = "John Doe"

# Create text highlight annotation for page 1
highlight_annotation = groupdocs_annotation_cloud.AnnotationInfo()
p1 = groupdocs_annotation_cloud.Point()
p1.x = 80
p1.y = 730
p2 = groupdocs_annotation_cloud.Point()
p2.x = 240
p2.y = 730
p3 = groupdocs_annotation_cloud.Point()
p3.x = 80
p3.y = 650
p4 = groupdocs_annotation_cloud.Point()
p4.x = 240
p4.y = 650
highlight_annotation.points = [p1, p2, p3, p4]
highlight_annotation.page_number = 1
highlight_annotation.background_color = 16711680  # Yellow
highlight_annotation.type = "TextHighlight"
highlight_annotation.text = "Text to highlight"
highlight_annotation.creator_name = "John Doe"

# Set up options
file_info = groupdocs_annotation_cloud.FileInfo()
file_info.file_path = "multi-page-document.docx"

options = groupdocs_annotation_cloud.AnnotateOptions()
options.file_info = file_info
options.annotations = [area_annotation, point_annotation, highlight_annotation]
options.output_path = "output/multi-annotated-document.docx"

request = groupdocs_annotation_cloud.AnnotateRequest(options)
result = api.annotate(request)

print("Multiple Annotations added: " + result.title)

Best Practices for Multiple Annotations

  1. Batch Processing: Group related annotations together in a single API call to reduce network overhead.

  2. Page Organization: Organize annotations by page number to make document review easier.

  3. Performance Considerations: While you can add many annotations in a single call, very large batches (hundreds of annotations) may impact performance. Consider splitting very large annotation sets into multiple reasonable-sized batches.

  4. Error Handling: When adding multiple annotations, implement robust error handling to identify which specific annotations failed, if any.

  5. Annotation IDs: Keep track of annotation IDs returned by the API to allow for later updates or deletions of specific annotations.

Troubleshooting Tips

  1. Mixed Annotation Types: Ensure each annotation object has the correct Type property set to avoid rendering issues
  2. Page Numbers: Verify all page numbers are within the document’s page range (remember, page numbers are zero-based)
  3. Coordinate Systems: Different annotation types may use coordinates differently - check documentation for each type
  4. Output Path: Ensure the output path directory exists in your cloud storage

What You’ve Learned

In this tutorial, you’ve learned how to:

  • Add multiple different types of annotations to a document in a single API call
  • Configure properties specific to each annotation type
  • Optimize annotation processes for better performance
  • Implement multiple annotation patterns in different programming languages

Further Practice

To enhance your understanding of multiple annotations, try these exercises:

  1. Create a workflow that adds different annotation types based on document content
  2. Implement a solution that allows multiple users to add annotations to the same document
  3. Add annotations to all pages of a large document efficiently
  4. Create a pattern for programmatically generating annotations based on document analysis

Next Steps

Continue your learning journey with these related tutorials:

Helpful Resources