Comparison API

Zoho Writer comparison API provides a user-friendly viewer for comparing documents.

The API accepts a pair of documents as input and returns a comparison viewer URL as a response. When a user accesses the said URL in a browser, the documents are displayed in Writer with changes highlighted.

Purpose 

To compare two versions of a document and highlight the difference in text.

HTTP Request URL

https://{api.office-integrator_domain}/writer/officeapi/v1/document/compare

Request Parameters

ParameterData TypeDescription
Mandatory Parameters
apikey423s*****Uniquely identifies the web application, which initiates the document comparison request.
document1

or

url1
File

or

String
Method of providing the input file depending on its location.

document1 - If the old version of the input file is from your local drive or desktop.

url1 - If the old version of the input file is from a publicly accessible Web URL.
document2

or

url2
File

or

String
Method of providing the input file depending on its location.

document2 - If the updated version of the input file is from your local drive or desktop.

url2 - If the updated version of the input file is from a publicly accessible Web URL.
Optional Parameters
titleStringDefines document title of the 2 versions of comparison files. 
Note: If the user fails to provide a value for 'title' parameter, Zoho Writer will combine the names from 'document1' & 'document2' parameters, and replace it as the title
langStringEnables the editor interface to open in Writer supported languages.
Default value: en (English)

 

Comparison API - Error Codes

CodeDescription
1831Error occurred. Parameter value is either incorrect or invalid.
1852File format you're trying to import is not supported.
1868Invalid parameter name for uploaded content.

For a full list of error handling cases in Comparison API, refer here.

Sample Request

Copiedcurl --request POST \
  --url 'https://api.office-integrator.com/writer/officeapi/v1/document/compare' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  --form document1=@/Users/username/Documents/Sample_V1.docx \
  --form document2=@/Users/username/Documents/Sample_V2.docx \
  --form 'apikey=423s*****'
Copiedimport * as SDK from "@zoho-corp/office-integrator-sdk";
import { readFileSync } from 'fs';
const __dirname = import.meta.dirname;

class CompareDocument {

    static async execute() {
        
        //Initializing SDK once is enough. Calling here since code sample will be tested standalone. 
        //You can place SDK initializer code in you application and call once while your application start-up. 
        await this.initializeSdk();

        try {
            var sdkOperations = new SDK.V1.V1Operations();
            var compareDocumentParameters = new SDK.V1.CompareDocumentParameters();

            //Either use url as document source or attach the document in request body use below methods
            compareDocumentParameters.setUrl1("https://demo.office-integrator.com/zdocs/MS_Word_Document_v0.docx");
            compareDocumentParameters.setUrl2("https://demo.office-integrator.com/zdocs/MS_Word_Document_v1.docx");

            var file1Name = "MS_Word_Document_v0.docx";
            // var file1Path = __dirname + "/sample_documents/MS_Word_Document_v0.docx";
            // var file1Stream = readFileSync(file1Path);
            // var stream1Wrapper = new SDK.StreamWrapper(file1Name, file1Stream, file1Path);

            var file2Name = "MS_Word_Document_v1.docx";
            // var file2Path = __dirname + "/sample_documents/MS_Word_Document_v1.docx";
            // var file2Stream = readFileSync(file2Path);
            // var stream2Wrapper = new SDK.StreamWrapper(file2Name, file2Stream, file2Path);
            
            // compareDocumentParameters.setDocument1(stream1Wrapper);
            // compareDocumentParameters.setDocument2(stream2Wrapper);

            compareDocumentParameters.setLang("en");
            compareDocumentParameters.setTitle(file1Name + " vs " + file2Name);

            var responseObject = await sdkOperations.compareDocument(compareDocumentParameters);

            if(responseObject != null) {
                //Get the status code from response
                console.log("\nStatus Code: " + responseObject.statusCode);
    
                //Get the api response object from responseObject
                let writerResponseObject = responseObject.object;
    
                if(writerResponseObject != null) {
                    //Check if expected CompareDocumentResponse instance is received
                    if(writerResponseObject instanceof SDK.V1.CompareDocumentResponse) {
                        console.log("\nCompare URL - " + writerResponseObject.getCompareUrl());
                        console.log("\nDocument session delete URL - " + writerResponseObject.getSessionDeleteUrl());
                    } else if (writerResponseObject instanceof SDK.V1.InvalidConfigurationException) {
                        console.log("\nInvalid configuration exception. Exception json - ", writerResponseObject);
                    } else {
                        console.log("\nRequest not completed successfullly");
                    }
                }
            }
        } catch (error) {
            console.log("\nException while running sample code", error);
        }
    }

    //Include office-integrator-sdk package in your package json and the execute this code.

    static async initializeSdk() {

        // Refer this help page for api end point domain details -  https://www.zoho.com/officeintegrator/api/v1/getting-started.html
        let environment = await new SDK.DataCenter.Production("https://api.office-integrator.com");

        let auth = new SDK.AuthBuilder()
                        .addParam("apikey", "2ae438cf864488657cc9754********") //Update this apikey with your own apikey signed up in office integrator service
                        .authenticationSchema(await new SDK.V1.Authentication().getTokenFlow())
                        .build();

        let tokens = [ auth ];

        //Sdk application log configuration
        let logger = new SDK.LogBuilder()
            .level(SDK.Levels.INFO)
            //.filePath("<file absolute path where logs would be written>") //No I18N
            .build();

        let initialize = await new SDK.InitializeBuilder();

        await initialize.environment(environment).tokens(tokens).logger(logger).initialize();

        console.log("SDK initialized successfully.");
    }

}

CompareDocument.execute();

Sample Response

Copied{
"compare_url":"https://api.office-integrator.com/writer/officeapi/v1/documents/1650f22c990cbbce470e0418a808480021eeffebdad549f3e5226dc8cc83a7fc2e6e38a309785f4b8848a73aca2de5a53752f96243422c0a64aa7795ee7c8c103113db9ef722e86ec3d3b98ed71f1d61/compare",
"session_delete_url":"https://api.office-integrator.com/writer/officeapi/v1/sessions/1650f22c990cbbce470e0418a808480021eeffebdad549f3e5226dc8cc83a7fc2e6e38a309785f4b8848a73aca2de5a53752f96243422c0a64aa7795ee7c8c103113db9ef722e86ec3d3b98ed71f1d61"
}