Tamil Nadu Ration Card OCR API

API Description

Objective

The Tamil Nadu Ration Card OCR API extracts the textual data from an image of a ration card document issued under Tamil Nadu(TN) and returns it in a JSON format. It includes the :

Name of the card holder
Relative's name
Date of birth of the card holder
Address
Card number
Family members

Input	Output
An image or PDF file containing a TN ration card document	The textual information extracted from the document

API URL

https://ind-engine.thomas.hyperverge.co/v1/readTNRationCard

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and ﬁles as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Type	Description	Valid Values
`content-type`	Mandatory	string	This parameter defines the media type for the request payload.	multipart/form-data
`appId`	Mandatory	string	The application ID shared by HyperVerge	Not Applicable - this is a unique value.
`appKey`	Mandatory	string	The application key shared by HyperVerge	Not Applicable - this is a unique value.
`transactionId`	Mandatory	string	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application.

Inputs

The following table provides the complete information on the parameters used in the request body for the API call.

Parameter	Mandatory or Optional	Description
`image`	Mandatory	The image file containing the document.

Caution

If you send multiple files in the same API request, the OCR extraction will be performed only on one of the files. Kindly send only one file in a request to avoid confusion.
If the PDF file has multiple pages, only the first page will be considered for the OCR extraction.

Request

The following code shows a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/readTNRationCard' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image=@"<path_to_image_file>"'

Success Response

The following is a successful response:

{
  "status": "success",
  "statusCode": "200",
  "result": [
    {
      "details": {
        "name": {
          "value": "<Name_Of_The_Card_Holder>",
          "conf": 0.97,
          "to-be-reviewed": "no"
        },
        "rel_name": {
          "value": "<Relative_Name>",
          "conf": 0.98,
          "to-be-reviewed": "no"
        },
        "dob": {
          "value": "<Date_Of_Birth_in_DD/MM/YYYY_Format>",
          "conf": 0.99,
          "to-be-reviewed": "no"
        },
        "address": {
          "value": "<Address_Of_The_Card_Holder>",
          "conf": 0.79,
          "to-be-reviewed": "no"
        },
        "card_no": {
          "value": "<Ration_Card_Number>",
          "conf": 0.99,
          "to-be-reviewed": "no"
        },
        "family_members": {
          "value": "<Family_Members>",
          "conf": 0,
          "to-be-reviewed": "yes",
          "value_list": []
        },
        "count": {
          "value": "<Count_Of_Family_Members>",
          "conf": 0,
          "to-be-reviewed": "yes"
        }
      },
      "type": "<Document_Type>"
    }
  ]
}

Success Response Details

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code returned for the request
result	array	Array containing the extracted details from the ration card
result[].details	object	Object containing the extracted fields with their values and confidence scores
result[].details.name	object	The name of the card holder extracted from the ration card
result[].details.name.value	string	The actual name value
result[].details.name.conf	number	The confidence score with which the name is extracted
result[].details.name.to-be-reviewed	string	Indicates whether the field needs to be reviewed
result[].details.rel_name	object	The relative's name extracted from the ration card
result[].details.rel_name.value	string	The actual relative's name value
result[].details.rel_name.conf	number	The confidence score with which the relative's name is extracted
result[].details.rel_name.to-be-reviewed	string	Indicates whether the field needs to be reviewed
result[].details.dob	object	The date of birth extracted from the ration card
result[].details.dob.value	string	The actual date of birth value
result[].details.dob.conf	number	The confidence score with which the date of birth is extracted
result[].details.dob.to-be-reviewed	string	Indicates whether the field needs to be reviewed
result[].details.address	object	The address extracted from the ration card
result[].details.address.value	string	The actual address value
result[].details.address.conf	number	The confidence score with which the address is extracted
result[].details.address.to-be-reviewed	string	Indicates whether the field needs to be reviewed
result[].details.card_no	object	The ration card number extracted from the document
result[].details.card_no.value	string	The actual card number value
result[].details.card_no.conf	number	The confidence score with which the card number is extracted
result[].details.card_no.to-be-reviewed	string	Indicates whether the field needs to be reviewed
result[].details.family_members	object	The family members information extracted from the ration card
result[].details.family_members.value	string	The actual family members value
result[].details.family_members.conf	number	The confidence score with which the family members information is extracted
result[].details.family_members.to-be-reviewed	string	Indicates whether the field needs to be reviewed
result[].details.family_members.value_list	array	Array containing the list of family members
result[].details.count	object	The count of family members extracted from the ration card
result[].details.count.value	string	The actual count value
result[].details.count.conf	number	The confidence score with which the count is extracted
result[].details.count.to-be-reviewed	string	Indicates whether the field needs to be reviewed
result[].type	string	The type of document processed

Failure Response

Failure - No Document Detected

The following is a failure response where the API fails to detect a document from the image:

{
  "status": "failure",
  "statusCode": 422,
  "error": "No Document detected",
  "requestId": "<Request_ID>"
}

Error Responses

Missing Input Image
Multiple Input Images
Image Size Issue

{
  "status": "failure",
  "statusCode": "400",
  "error": "API call requires one input image",
  "requestId": "<Request_ID>"
}

{
  "status": "failure",
  "statusCode": "400",
  "error": "API call handles only one input image",
  "requestId": "<Request_ID>"
}

{
  "status": "failure",
  "statusCode": "400",
  "error": "image size cannot be greater than 12MB",
  "requestId": "<Request_ID>"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.

The following table lists all error responses:

Status Code	Error Message	Error Description
400	No Image input	The request missed the `image` input.
400	More than 1 image input	The request had more than one `image` file input. It expects only one file in the request.
400	image size cannot be greater than 12MB	The image size is larger than the allowed limit.
422	Document not detected from Image	The API failed to detect a document in the image. Ensure that the image captures the document following the guidelines mentioned under the Input Image Guidelines section
5xx	Internal Server Error	There was an error with HyperVerge's server. Please contact the HyperVerge team

API Description​

Objective​

API URL​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Inputs​

Request​

Success Response​

Success Response Details​

Failure Response​

Error Responses​

Error Response Details​