Language

The DocAI language service is able to determine the predominant language of document.

Like most of the DocAI API, the language service works asynchronously, requiring you to first make a POST to create the language request, then use a GET endpoint to poll the status of the request and obtain the results once complete.

When you make a language request, DocAI automatically applies OCR to the document (if necessary - see file submission for exceptions) and caches the OCR results for reuse by any of the other services (classification, field extraction and OCR).

Using this guide

This guide uses plain Python 3 and built-in libraries here for illustrative purposes, but if you plan to use Python in your own code you may want to check out our prebuilt Python wrapper.

To run the code samples, you’ll need the following imports and constants:

1
2
3
4
5
6
7
import os, json, requests

# Assumes you've exported your token as an environment variable
TOKEN = os.getenv('DOCAI_TOKEN')

# Change this if you are using another region
REGION_URL = "https://us.app.zuva.ai"

Step 1: Upload your file to DocAI

Follow the instructions in the File Management Workflow to upload your file to DocAI and obtain its file_id.

Step 2: Create a document classification request

To start processing your file, use the Create language requests endpoint, providing the file_id from step 1.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
def create_language_requests(file_id):
   resp = requests.request("POST",
                           REGION_URL + "/api/v2/language",
                           headers={"Authorization": "Bearer " + TOKEN},
                           json={"file_ids": [file_id]})
   if resp.status_code==202:
       return json.loads(resp.text)
   else:
       raise RuntimeError(f'Unexpected status code: {resp.status_code}')

language_requests = create_language_requests(file_id)["file_ids"]

The response includes a request_id for each file_id - in this case, since we included only one file ID, we get a single-element array. We’ll need the request_id in the next step:

1
request_id = language_requests[0]['request_id']

Step 3: Poll for the status and results

Begin polling the Get language request status endpoint until the status is “complete”.

Note: you should also check for a “failed” status, to avoid waiting on a request that will never complete.

Once the status is complete, the response will also include the language field, which as the result of the request.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import time

def poll_language(request_id, timeout_seconds=180, interval_seconds=2):
   t_start = time.time()
   while time.time() < t_start + timeout_seconds:
       resp=requests.request("GET",
                             REGION_URL + "/api/v2/language/"+request_id,
                             headers={"Authorization": "Bearer " + TOKEN})
       if resp.status_code!=200:
           raise RuntimeError(f'Unexpected status code: {resp.status_code}')
       status_results = json.loads(resp.text)
       if status_results['status'] == 'failed':
           raise RuntimeError('languagerequest failed')
       if status_results['status'] == 'complete':
           return status_results
       time.sleep(interval_seconds)
   raise RuntimeError("Timed out waiting for language request to process")

When the request is complete, the results will be included in the response.

1
2
results = poll_language(request_id)
print(f'The document language is {results["language"]}')

Step 4 (optional): Delete the file from DocAI

If desired, you may now Delete the file from DocAI. Otherwise, it will automatically be removed after 48 hours.

On This Page