Developer Center
Resources & examples to get you started with Modzy.

Developer Center / Integration Tutorial

Integration Tutorial

Summary

Modzy’s API makes it possible to add AI functionality to any application with a plugin capability. To date, Modzy Labs developed and tested plugins for Microsoft (MS) Office, QGIS, and the Apple ecosystem. This tutorial will demonstrate how to leverage the Modzy API to quickly get an API call working within the MS Office suite.

What You Need to Know

The Modzy API is RESTful. A data scientist or developer can easily access it using any programming language that allows for sending http POST requests. In this tutorial, we will walk through calling Modzy from the Visual Basic for Applications (VBA) development environment within MS Word. The tutorial will cover capturing text from the current MS Word document, sending it to the Modzy platform for language identification, then displaying the results of the API call in a message box to the user. To complete this tutorial, you will need a computer running a Windows operating system, with a version of MS Word installed. Additionally, you will need access to the Modzy API, including a URL endpoint for the platform server and an API access key.

Setting up for This Tutorial:

Before beginning this tutorial, open MS Word. This tutorial requires text in the document. Though any UTF-8 encoded text will work, the text this tutorial will use comes from the preamble to the U.S. Constitution:

“We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defense, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.”

Once the text has been added to the document, save the document as “Modzy Tutorial.docx” and then launch the VBA editor by pressing Alt+F11 on the keyboard.

Building an API Client Class

In the Program pane on the upper left of the VBA Editor, right click your document. Click on Insert-> Class Module.

Left click the new “Class1” where it appeared in your upper left pane. Then left click in the Name property of the bottom left pane. Change “Class1” to “API_Client”

Double Click the “API_Client” Reference in the upper left pane to open the empty class code document. Add the following lines to the top of the class code

Public mURL As String
Public mAPI_key As String
Public mJobRoute As String
Public mResultRoute As String
Public Sub Initialize(url As String, key As String)
Me.mJobRoute = "api/jobs"
Me.mResultRoute = "api/results"
Me.mURL = url
Me.mAPI_key = key
End Sub

These variables are members of your class and will hold the URL endpoint for your Modzy instance, your API key, and the routing information for your API requests.  Now that an initialization method has been set for these, we will move on to constructing a method with an API call.

To create a method which can call the Modzy API, start by adding the following code to your editor:

Public Function call_api_job_text_language_ID(routine As String, data As String) As Boolean
'setup the destination and response URLs
Dim DestURL As String
DestURL = "http://" & Me.mURL & Me.mJobRoute
Dim ResURL As String
ResURL = "http://" & Me.mURL & Me.mResultRoute

The DestURL variable holds the endpoint that our code will POST to. The ResURL variable holds the endpoint where we will check for our completed job results. With the endpoints established, we move on to the next part of our method: setting up the JSON for the POST request.

An example of a properly formatted JSON request for the Language Identification model can be found on its description page. For this tutorial we have simply copied it and altered it so that it refers to the text and VBA required String Formatting. The resulting request JSON in VBA formatting looks like this:

body = "{ " & _
    " ""model"": {" & _
        " ""identifier"": ""language-classifier""," & _
        " ""version"": ""0.0.11""" & _
    "}," & _
    " ""input"": {" & _
        " ""type"": ""text"" ," & _
        " ""sources"": {" & _
            " ""doc-text"": {""input.txt"": "" " & Mid(data, 1, Len(data) - 1) & """ }" & _
        "}" & _
    "}" & _
"}"

This body variable holds the body of the POST request. Once it has been properly formatted for Modzy, we can send the request with the following code:

Set MyRequest = CreateObject("WinHttp.WinHttpRequest.5.1")
MyRequest.Open "POST", DestURL, False
MyRequest.setRequestHeader "Content-type", "application/json"
MyRequest.setRequestHeader "Accept", "application/json"
MyRequest.setRequestHeader "Authorization", "ApiKey " & Me.mAPI_key
MyRequest.Send body

The Modzy API will immediately return a response; this contains a job identifier that is unique to your request. To capture the identifier, we use the following code:

response = MyRequest.ResponseText
Dim idlocation As Long
idlocation = InStr(response, "jobIdentifier") + 16
jobID = Mid(response, idlocation, 36)

We now use the DestURL variable to poll Modzy for status updates until our processing is complete.

Dim statusURL As String
statusURL = DestURL & "/" & jobID
Do While check_status(statusURL)
    waitTill = Now() + TimeValue("00:00:05")
    While Now() < waitTill
        DoEvents
    Wend
Loop

The loop in this code checks the status of our processing and returns False when Modzy is done processing. It checks every 5 seconds for a status update. The check_status method is implemented outside of this function and looks like this:

Public Function check_status(url As String) As Boolean
    Set MyStatus = CreateObject("WinHttp.WinHttpRequest.5.1")
    MyStatus.Open "GET", url, False
    MyStatus.setRequestHeader "Content-type", "application/json"
    MyStatus.setRequestHeader "Accept", "application/json"
    MyStatus.setRequestHeader "Authorization", "ApiKey " & Me.mAPI_key
    MyStatus.Send
    response2 = MyStatus.ResponseText
    statusLocation = InStr(response2, "status") + 9
    statusReport = Mid(response2, statusLocation, 9)
    rValue = True
    If StrComp(statusReport, "COMPLETED") = 0 Then
        rValue = False
    End If
    check_status = rValue
End Function

Once the processing is complete, we call one more helper method (described below) to display the results of the processing in an Msg Box and close the function.

'get result
MsgBox get_result(ResURL & "/" & jobID)
End Function

The last bit of code is to get the response from a call to Modzy, and then loads the response into a string.

Public Function get_result(url As String) As String
    Set MyResult = CreateObject("WinHttp.WinHttpRequest.5.1")
    MyResult.Open "GET", url, False
    MyResult.setRequestHeader "Content-type", "application/json"
    MyResult.setRequestHeader "Accept", "application/json"
    MyResult.setRequestHeader "Authorization", "ApiKey " & Me.mAPI_key
    MyResult.Send
    response = MyResult.ResponseText
    get_result = response
End Function

Demonstrating the API Call

Using the upper left pane of the VBA Editor, click on the Microsoft Word Object folder and then double click “ThisDocument” to open the document’s code window. Add the following lines of code to the “ThisDocument” Code window.

Sub http()
Dim MyRequest As Object
    Dim api As API_Client
    Set api = New API_Client
    api.Initialize "your/modzy/api/endpoint", "your-modzy-key"
    'convert document to UTF-8
    ActiveDocument.TextEncoding = msoEncodingUTF8
    api.call_api_job_text_language_ID "language-classifier", ActiveDocument.Content
End Sub

Now Click File->Save in the VBA Editor. You will be prompted to save the file as Macro Enabled.

Save the documents as macro enabled, then press F5 to run the API Call.

The returned result will include an ISO code for the one language that the model has judged the document was written in (English, Russian, etc.), along with the model’s probability score for the language.

And that’s how you call the Modzy API from a third-party application. Other application integrations are similar and require the same four steps:

  • Use the application to collect the data you want to process
  • Send the data along with the ID of the model you want to process the data to Modzy via an API POST
  • Poll Modzy to determine when processing is complete
  • Perform a GET request to obtain the output of the processing.